diff options
author | Justus Winter <justus@sequoia-pgp.org> | 2020-08-11 14:05:50 +0200 |
---|---|---|
committer | Justus Winter <justus@sequoia-pgp.org> | 2020-08-11 14:32:13 +0200 |
commit | 59ff6d48ab1f025db560e361c3b65790581f18b0 (patch) | |
tree | 4b8663d294aba1c0a79db4252a49f4d4d61f649e /openpgp/src/crypto/s2k.rs | |
parent | 219c0008a028167430025ca669bbcc89fb17eff6 (diff) |
openpgp: Improve S2K's documentation.
- See #474.
Diffstat (limited to 'openpgp/src/crypto/s2k.rs')
-rw-r--r-- | openpgp/src/crypto/s2k.rs | 23 |
1 files changed, 21 insertions, 2 deletions
diff --git a/openpgp/src/crypto/s2k.rs b/openpgp/src/crypto/s2k.rs index 09a6a178..1a2d3707 100644 --- a/openpgp/src/crypto/s2k.rs +++ b/openpgp/src/crypto/s2k.rs @@ -23,21 +23,34 @@ use rand::Rng; /// /// String-to-key (S2K) specifiers are used to convert password /// strings into symmetric-key encryption/decryption keys. See -/// [Section 3.7 of RFC 4880]. +/// [Section 3.7 of RFC 4880]. This is used to encrypt messages with +/// a password (see [`SKESK`]), and to protect secret keys (see +/// [`key::Encrypted`]). /// /// [Section 3.7 of RFC 4880]: https://tools.ietf.org/html/rfc4880#section-3.7 +/// [`SKESK`]: ../../packet/enum.SKESK.html +/// [`key::Encrypted`]: ../../packet/key/struct.Encrypted.html /// /// Note: This enum cannot be exhaustively matched to allow future /// extensions. #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)] pub enum S2K { /// Simply hashes the password. + /// + /// This mechanism uses neither iteration to increase the time it + /// takes to derive the key from the password nor does it salt the + /// password. This makes dictionary attacks more feasible. Do + /// not use this variant. #[deprecated(since = "rfc4880", note = "Use `S2K::Iterated`.")] Simple { /// Hash used for key derivation. hash: HashAlgorithm }, /// Hashes the password with a public `salt` value. + /// + /// This mechanism does not use iteration to increase the time it + /// takes to derive the key from the password. This makes + /// dictionary attacks more feasible. Do not use this variant. #[deprecated(note = "Use `S2K::Iterated`.")] Salted { /// Hash used for key derivation. @@ -52,6 +65,12 @@ pub enum S2K { /// Public salt value mixed into the password. salt: [u8; 8], /// Number of bytes to hash. + /// + /// This parameter increases the workload for an attacker + /// doing a dictionary attack. Note that not all values are + /// representable. See [`S2K::new_iterated`]. + /// + /// [`S2K::new_iterated`]: #method.new_iterated hash_bytes: u32, }, /// Private S2K algorithm @@ -112,7 +131,7 @@ impl S2K { } } - /// Convert the string to a key using the S2K's parameters. + /// Derives a key of the given size from a password. pub fn derive_key(&self, password: &Password, key_size: usize) -> Result<SessionKey> { #[allow(deprecated)] |