diff options
author | Justus Winter <justus@sequoia-pgp.org> | 2020-08-04 16:22:53 +0200 |
---|---|---|
committer | Justus Winter <justus@sequoia-pgp.org> | 2020-08-04 16:42:33 +0200 |
commit | c9d4d70b94c8440c8cb74e2dedffa8d8dc214866 (patch) | |
tree | 4dabb82a59a834f1249aee1610e74dad5ed7d271 | |
parent | 7ac4d250914ba4349614a860ff2a7635ba704936 (diff) |
openpgp: Improve documentation of mod asymmetric.
- See #474.
-rw-r--r-- | openpgp/src/crypto/asymmetric.rs | 66 | ||||
-rw-r--r-- | openpgp/src/crypto/backend/nettle/asymmetric.rs | 1 | ||||
-rw-r--r-- | openpgp/src/crypto/mod.rs | 2 |
3 files changed, 67 insertions, 2 deletions
diff --git a/openpgp/src/crypto/asymmetric.rs b/openpgp/src/crypto/asymmetric.rs index dd650ff2..fbd94d93 100644 --- a/openpgp/src/crypto/asymmetric.rs +++ b/openpgp/src/crypto/asymmetric.rs @@ -1,4 +1,4 @@ -//! Asymmetric crypt operations. +//! Asymmetric crypto operations. use crate::packet::{self, key, Key}; use crate::crypto::SessionKey; @@ -9,10 +9,33 @@ use crate::Result; /// Creates a signature. /// +/// Used in the streaming [`Signer`], the methods binding components +/// to certificates (e.g. [`UserID::bind`]), [`SignatureBuilder`]'s +/// signing functions (e.g. [`SignatureBuilder::sign_standalone`]), +/// and likely many more places. +/// +/// [`Signer`]: ../serialize/stream/struct.Signer.html +/// [`UserID::bind`]: ../packet/struct.UserID.html#method.bind +/// [`SignatureBuilder`]: ../packet/signature/struct.SignatureBuilder.html +/// [`SignatureBuilder::sign_standalone`]: ../packet/signature/struct.SignatureBuilder.html#method.sign_standalone +/// /// This is a low-level mechanism to produce an arbitrary OpenPGP /// signature. Using this trait allows Sequoia to perform all /// operations involving signing to use a variety of secret key /// storage mechanisms (e.g. smart cards). +/// +/// A signer consists of the public key and a way of creating a +/// signature. This crate implements `Signer` for [`KeyPair`], which +/// is a tuple containing the public and unencrypted secret key in +/// memory. Other crates my provide their own implementations of +/// `Signer` to utilize keys stored in various places. Currently, the +/// following implementations exist: +/// +/// - [`KeyPair`]: In-memory keys. +/// - [`sequoia_rpc::gnupg::KeyPair`]: Connects to the `gpg-agent`. +/// +/// [`KeyPair`]: struct.KeyPair.html +/// [`sequoia_rpc::gnupg::KeyPair`]: https://docs.sequoia-pgp.org/sequoia_ipc/gnupg/struct.KeyPair.html pub trait Signer { /// Returns a reference to the public key. fn public(&self) -> &Key<key::PublicParts, key::UnspecifiedRole>; @@ -35,10 +58,27 @@ impl Signer for Box<dyn Signer> { /// Decrypts a message. /// +/// Used by [`PKESK::decrypt`] to decrypt session keys. +/// +/// [`PKESK::decrypt`]: ../packet/enum.PKESK.html#method.decrypt +/// /// This is a low-level mechanism to decrypt an arbitrary OpenPGP /// ciphertext. Using this trait allows Sequoia to perform all /// operations involving decryption to use a variety of secret key /// storage mechanisms (e.g. smart cards). +/// +/// A decryptor consists of the public key and a way of decrypting a +/// session key. This crate implements `Decryptor` for [`KeyPair`], +/// which is a tuple containing the public and unencrypted secret key +/// in memory. Other crates my provide their own implementations of +/// `Signer` to utilize keys stored in various places. Currently, the +/// following implementations exist: +/// +/// - [`KeyPair`]: In-memory keys. +/// - [`sequoia_rpc::gnupg::KeyPair`]: Connects to the `gpg-agent`. +/// +/// [`KeyPair`]: struct.KeyPair.html +/// [`sequoia_rpc::gnupg::KeyPair`]: https://docs.sequoia-pgp.org/sequoia_ipc/gnupg/struct.KeyPair.html pub trait Decryptor { /// Returns a reference to the public key. fn public(&self) -> &Key<key::PublicParts, key::UnspecifiedRole>; @@ -57,6 +97,30 @@ pub trait Decryptor { /// /// [`Signer`]: trait.Signer.html /// [`Decryptor`]: trait.Decryptor.html +/// +/// # Examples +/// +/// ``` +/// # fn main() -> sequoia_openpgp::Result<()> { +/// use sequoia_openpgp as openpgp; +/// use openpgp::types::Curve; +/// use openpgp::cert::prelude::*; +/// use openpgp::packet::prelude::*; +/// +/// // Conveniently create a KeyPair from a bare key: +/// let keypair = +/// Key4::<_, key::UnspecifiedRole>::generate_ecc(false, Curve::Cv25519)? +/// .into_keypair()?; +/// +/// // Or from a query over a certificate: +/// let (cert, _) = +/// CertBuilder::general_purpose(None, Some("alice@example.org")) +/// .generate()?; +/// let keypair = +/// cert.keys().unencrypted_secret().nth(0).unwrap().key().clone() +/// .into_keypair()?; +/// # Ok(()) } +/// ``` #[derive(Clone)] pub struct KeyPair { public: Key<key::PublicParts, key::UnspecifiedRole>, diff --git a/openpgp/src/crypto/backend/nettle/asymmetric.rs b/openpgp/src/crypto/backend/nettle/asymmetric.rs index 6445fd71..cc7cb2e4 100644 --- a/openpgp/src/crypto/backend/nettle/asymmetric.rs +++ b/openpgp/src/crypto/backend/nettle/asymmetric.rs @@ -146,7 +146,6 @@ impl Decryptor for KeyPair { KeyPair::public(self) } - /// Creates a signature over the `digest` produced by `hash_algo`. fn decrypt(&mut self, ciphertext: &mpi::Ciphertext, plaintext_len: Option<usize>) -> Result<SessionKey> diff --git a/openpgp/src/crypto/mod.rs b/openpgp/src/crypto/mod.rs index c4ea6ab8..eccd1b7c 100644 --- a/openpgp/src/crypto/mod.rs +++ b/openpgp/src/crypto/mod.rs @@ -13,9 +13,11 @@ //! //! - *Converting a string to a `Password`*: Use [`Password::from`]. //! - *Create a session key*: Use [`SessionKey::new`]. +//! - *Use secret keys*: See the [`KeyPair` example]. //! //! [`Password::from`]: https://doc.rust-lang.org/std/convert/trait.From.html //! [`SessionKey::new`]: struct.SessionKey.html#method.new +//! [`KeyPair` example]: struct.KeyPair.html#examples use std::io::Read; use std::ops::{Deref, DerefMut}; |