From d10d1f4a8dce68c404de4a18dc936d973e890092 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Damir=20Jeli=C4=87?= Date: Wed, 11 Sep 2024 11:32:38 +0200 Subject: [PATCH] Apply suggestions from code review Co-authored-by: Denis Kasak --- src/pk_encryption.rs | 46 ++++++++++++++++++++++++-------------------- 1 file changed, 25 insertions(+), 21 deletions(-) diff --git a/src/pk_encryption.rs b/src/pk_encryption.rs index 64acbad3..1d75f6ea 100644 --- a/src/pk_encryption.rs +++ b/src/pk_encryption.rs @@ -15,10 +15,12 @@ //! ☣️ Compat support for libolm's PkEncryption and PkDecryption //! //! This implements the `m.megolm_backup.v1.curve25519-aes-sha2` described in -//! the Matrix [spec]. This is a asymmetric encrytpion scheme based on -//! Curve25519. +//! the Matrix [spec]. This is a hybrid encryption scheme utilizing Curve25519 +//! and AES-CBC. X25519 ECDH is performed between an ephemeral key pair and a +//! long-lived backup key pair to establish a shared secret, from which +//! symmetric encryption and message authentication (MAC) keys are derived. //! -//! **Warning**: Please note the algorithm contains a critical flaw and does not +//! **WARNING**: Please note the algorithm contains a critical flaw and does not //! provide authentication of the ciphertext. //! //! # Examples @@ -60,7 +62,8 @@ use crate::{ Curve25519PublicKey, Curve25519SecretKey, KeyError, }; -/// Error type describing the failure cases the Pk decryption step can have. +/// An error type describing failures which can happen during the decryption +/// step. #[derive(Debug, Error)] pub enum Error { /// The message has invalid [Pkcs7] padding. @@ -71,7 +74,7 @@ pub enum Error { Mac(#[from] MacError), } -/// Error describing failures that might happen during the decoding of a +/// An error type describing failures which can happen during the decoding of an /// encrypted [`Message`]. #[derive(Debug, Error)] pub enum MessageDecodeError { @@ -90,16 +93,16 @@ pub struct Message { pub ciphertext: Vec, /// The message authentication code of the message. /// - /// *Warning*: As stated in the module description, this does not + /// **WARNING**: As stated in the module description, this does not /// authenticate the message. pub mac: Vec, - /// The ephemeral [`Curve25519PublicKey`] of the message which was used to - /// derive the individual message key. + /// The ephemeral [`Curve25519PublicKey`] used to derive the individual + /// message key. pub ephemeral_key: Curve25519PublicKey, } impl Message { - /// Attempt to decode a PkEncryption [`Message`] from a Base64 encoded + /// Attempt to decode a PkEncryption [`Message`] from a Base64-encoded /// triplet of ciphertext, MAC, and ephemeral key. pub fn from_base64( ciphertext: &str, @@ -116,8 +119,8 @@ impl Message { /// The decryption component of the PkEncryption support. /// -/// This struct allows you to share a public key, enabling others to encrypt -/// messages that can be decrypted using the corresponding private key. +/// The public key can be shared with others, allowing them to encrypt messages +/// which can be decrypted using the corresponding private key. pub struct PkDecryption { secret_key: Curve25519SecretKey, public_key: Curve25519PublicKey, @@ -126,8 +129,9 @@ pub struct PkDecryption { impl PkDecryption { /// Create a new random [`PkDecryption`] object. /// - /// This will create a new random [`Curve25519SecretKey`] which is used as - /// the long-term key to derive individual message keys. + /// This contains a fresh [`Curve25519SecretKey`] which is used as a + /// long-term key to derive individual message keys and effectively serves + /// as the decryption secret. pub fn new() -> Self { let secret_key = Curve25519SecretKey::new(); let public_key = Curve25519PublicKey::from(&secret_key); @@ -146,14 +150,15 @@ impl PkDecryption { /// Get the [`Curve25519SecretKey`] of this [`PkDecryption`] object. /// - /// You should serialize and store this key safely to be able to decrypt - /// messages you receive. + /// If persistence is required, securely serialize and store this key. It + /// can be used to reconstruct the [`PkDecryption`] object for decrypting + /// associated messages. pub const fn secret_key(&self) -> &Curve25519SecretKey { &self.secret_key } - /// Get the [`Curve25519PublicKey`] which can be used to encrypt a message - /// for this [`PkDecryption`] object. + /// Get the associated ephemeral [`Curve25519PublicKey`]. This key can be + /// used to reconstruct the [`PkEncryption`] object to encrypt messages. pub const fn public_key(&self) -> Curve25519PublicKey { self.public_key } @@ -188,9 +193,8 @@ impl Default for PkDecryption { /// The encryption component of PkEncryption support. /// -/// This struct can be created using a [`Curve25519PublicKey`] corresponding to -/// a [`PkDecryption`] object, allowing messages to be encrypted for the -/// associated decryption object. +/// This struct can be created from a [`Curve25519PublicKey`] corresponding to +/// a [`PkDecryption`] object, allowing encryption of messages for that object. pub struct PkEncryption { public_key: Curve25519PublicKey, } @@ -198,7 +202,7 @@ pub struct PkEncryption { impl PkEncryption { /// Create a new [`PkEncryption`] object from a [`Curve25519PublicKey`]. /// - /// The public key should come from an existing [`PkDecryption`] object. + /// The public key should be obtained from an existing [`PkDecryption`] object. pub const fn from_key(public_key: Curve25519PublicKey) -> Self { Self { public_key } }