Apply suggestions from code review

Co-authored-by: Denis Kasak <[email protected]>

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<u8>,
     /// 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<u8>,
-    /// 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,17 +193,16 @@ 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,
 }
 
 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 }
     }