From 44f677ce10e2af6dbab532f996cf685e8c55afe5 Mon Sep 17 00:00:00 2001
From: "Neal H. Walfield" <neal@pep.foundation>
Date: Thu, 28 May 2020 10:34:00 +0200
Subject: openpgp: Improve Key::decrypt_secret's discoverability

  - At appropriate places in the documentation, add a reference to
    `Key::decrypt_secret`.
---
 openpgp/src/cert/mod.rs   | 32 ++++++++++++++++++++++++++++++++
 openpgp/src/packet/mod.rs | 10 ++++++++--
 2 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/openpgp/src/cert/mod.rs b/openpgp/src/cert/mod.rs
index 40899555..7de9f286 100644
--- a/openpgp/src/cert/mod.rs
+++ b/openpgp/src/cert/mod.rs
@@ -567,6 +567,13 @@ use super::*;
 ///
 /// [`Cert::as_tsk()`]: #method.as_tsk
 ///
+/// Secret key material may be protected with a password.  In such
+/// cases, it needs to be decrypted before it can be used to decrypt
+/// data or generate a signature.  Refer to [`Key::decrypt_secret`]
+/// for details.
+///
+/// [`Key::decrypt_secret`]: ../packet/enum.Key.html#method.decrypt_secret
+///
 /// # Filtering Certificates
 ///
 /// To filter certificates, iterate over all components, clone what
@@ -732,7 +739,13 @@ impl Cert {
     /// [`Cert::keys`] method, this method does not erase the key's
     /// role.
     ///
+    /// A key's secret key material may be protected with a password.
+    /// In such cases, it needs to be decrypted before it can be used
+    /// to decrypt data or generate a signature.  Refer to
+    /// [`Key::decrypt_secret`] for details.
+    ///
     /// [`Cert::keys`]: #method.keys
+    /// [`Key::decrypt_secret`]: ../packet/enum.Key.html#method.decrypt_secret
     ///
     /// # Examples
     ///
@@ -1066,8 +1079,14 @@ impl Cert {
     /// subkeys, use [`KeyAmalgamationIter::subkeys`].  These
     /// functions preserve the keys' role in the type system.
     ///
+    /// A key's secret secret key material may be protected with a
+    /// password.  In such cases, it needs to be decrypted before it
+    /// can be used to decrypt data or generate a signature.  Refer to
+    /// [`Key::decrypt_secret`] for details.
+    ///
     /// [`Cert::primary_key`]: #method.primary_key
     /// [`KeyAmalgamationIter::subkeys`]: amalgamation/key/struct.KeyAmalgamationIter.html#method.subkeys
+    /// [`Key::decrypt_secret`]: ../packet/enum.Key.html#method.decrypt_secret
     ///
     /// # Examples
     ///
@@ -2746,6 +2765,13 @@ impl<'a> ValidCert<'a> {
 
     /// Returns the certificate's primary key.
     ///
+    /// A key's secret secret key material may be protected with a
+    /// password.  In such cases, it needs to be decrypted before it
+    /// can be used to decrypt data or generate a signature.  Refer to
+    /// [`Key::decrypt_secret`] for details.
+    ///
+    /// [`Key::decrypt_secret`]: ../packet/enum.Key.html#method.decrypt_secret
+    ///
     /// # Examples
     ///
     /// ```
@@ -2784,7 +2810,13 @@ impl<'a> ValidCert<'a> {
     /// instead of skipping the first key: this causes the iterator to
     /// return values with a more accurate type.
     ///
+    /// A key's secret secret key material may be protected with a
+    /// password.  In such cases, it needs to be decrypted before it
+    /// can be used to decrypt data or generate a signature.  Refer to
+    /// [`Key::decrypt_secret`] for details.
+    ///
     /// [`ValidKeyAmalgamationIter::subkeys`]: amalgamation/key/struct.ValidKeyAmalgamationIter.html#method.subkeys
+    /// [`Key::decrypt_secret`]: ../packet/enum.Key.html#method.decrypt_secret
     ///
     /// # Examples
     ///
diff --git a/openpgp/src/packet/mod.rs b/openpgp/src/packet/mod.rs
index a1f6480f..fec3ee2a 100644
--- a/openpgp/src/packet/mod.rs
+++ b/openpgp/src/packet/mod.rs
@@ -1332,7 +1332,10 @@ impl<R: key::KeyRole> Key<key::SecretParts, R> {
     ///
     /// # Errors
     ///
-    /// Fails if the secret key is missing, or encrypted.
+    /// Fails if the secret key is encrypted.  You can use
+    /// [`Key::decrypt_secret`] to decrypt a key.
+    ///
+    /// [`Key::decrypt_secret`]: key.html#method.decrypt_secret
     pub fn into_keypair(self) -> Result<KeyPair> {
         use crate::packet::key::SecretKeyMaterial;
         let (key, secret) = self.take_secret();
@@ -1491,7 +1494,10 @@ impl<R: key::KeyRole> key::Key4<key::SecretParts, R> {
     ///
     /// # Errors
     ///
-    /// Fails if the secret key is missing, or encrypted.
+    /// Fails if the secret key is encrypted.  You can use
+    /// [`Key::decrypt_secret`] to decrypt a key.
+    ///
+    /// [`Key::decrypt_secret`]: key.html#method.decrypt_secret
     pub fn into_keypair(self) -> Result<KeyPair> {
         use crate::packet::key::SecretKeyMaterial;
         let (key, secret) = self.take_secret();
-- 
cgit v1.2.3