Add some docs

aead/src/dyn_aead.rs

@@ -9,6 +9,9 @@ mod sealed {
     pub trait Sealed {}
 }
 
+/// Object-safe variant of the [`Aead`] trait.
+///
+/// This trait is implemented automaticlly for all types which implement the [`Aead`] trait.
 pub trait DynAead: sealed::Sealed {
     fn postfix_encrypt_inout<'out>(
         &self,
@@ -55,15 +58,15 @@ pub trait DynAead: sealed::Sealed {
         buffer: &'out mut [u8],
     ) -> Result<&'out mut [u8]>;
 
-    fn encrypt_to_buffer(
+    fn encrypt_to_buffer2(
         &self,
         nonce: &[u8],
         associated_data: &[u8],
         plaintext: &[u8],
         buffer: &mut dyn Buffer,
     ) -> Result<()>;
 
-    fn decrypt_to_buffer(
+    fn decrypt_to_buffer2(
         &self,
         nonce: &[u8],
         associated_data: &[u8],
@@ -154,7 +157,7 @@ impl<T: Aead> DynAead for T {
         Aead::postfix_decrypt_to_buf(self, nonce, associated_data, ciphertext, buffer)
     }
 
-    fn encrypt_to_buffer(
+    fn encrypt_to_buffer2(
         &self,
         nonce: &[u8],
         aad: &[u8],
@@ -166,7 +169,7 @@ impl<T: Aead> DynAead for T {
         Aead::encrypt_to_buffer(self, nonce, payload, buffer)
     }
 
-    fn decrypt_to_buffer(
+    fn decrypt_to_buffer2(
         &self,
         nonce: &[u8],
         aad: &[u8],

aead/src/lib.rs

@@ -80,11 +80,14 @@ pub trait Aead {
     /// The length of a nonce.
     type NonceSize: ArraySize;
 
-    /// The maximum length of the tag.
+    /// The length of a tag.
     type TagSize: ArraySize;
 
     /// Constant which defines whether AEAD specification appends or prepends tags.
     ///
+    /// It influences the behavior of the [`Aead::encrypt_to_vec`], [`Aead::decrypt_to_vec`],
+    /// [`Aead::encrypt_to_buffer`], and [`Aead::decrypt_to_buffer`] methods.
+    ///
     /// If the specification does not explicitly specify tag kind, we default to postfix tags.
     const IS_POSTFIX: bool = true;
 
@@ -158,6 +161,13 @@ pub trait Aead {
         self.detached_decrypt_inout(nonce, associated_data, buf, tag)
     }
 
+    /// Encrypt the [`InOutBufReserved`] data, append the authentication tag, and return
+    /// the resulting byte slice.
+    ///
+    /// `buffer` should have at least [`TagSize`][Aead::TagSize] bytes of additional output
+    /// capacity; otherwise, the method will return an error.
+    ///
+    /// The returned byte slice is guaranteed to point to the output of `buffer`.
     #[inline]
     fn postfix_encrypt_inout<'out>(
         &self,
@@ -176,8 +186,13 @@ pub trait Aead {
         Ok(&mut out_buf[..res_len])
     }
 
-    /// Decrypt the [`InOutBuf`] data, returning an error in the event the provided
-    /// authentication tag does not match the given ciphertext.
+    /// Decrypt the [`InOutBuf`] data, verify the appended authentication tag, and return
+    /// the resulting byte slice in case of success.
+    ///
+    /// Returns an error if the provided authentication tag does not match the given ciphertext
+    /// or if the size of `buffer` is smaller than the tag size.
+    ///
+    /// The returned byte slice is guaranteed to point to the output of `buffer`.
     #[inline]
     fn postfix_decrypt_inout<'out>(
         &self,
@@ -193,6 +208,13 @@ pub trait Aead {
         Ok(into_out_buf(buf))
     }
 
+    /// Encrypt the plaintext data of length `plaintext_len` residing at the beggining of `buffer`
+    /// in-place, append the authentication tag, and return the resulting byte slice.
+    ///
+    /// `buffer` should have at least [`TagSize`][Aead::TagSize] bytes of additional output
+    /// capacity; otherwise, the method will return an error.
+    ///
+    /// The returned byte slice is guaranteed to point to `buffer`.
     #[inline]
     fn postfix_encrypt_inplace<'out>(
         &self,
@@ -210,8 +232,13 @@ pub trait Aead {
         Ok(buf)
     }
 
-    /// Encrypt the data in-place, returning an error in the event the provided
-    /// authentication tag does not match the given ciphertext.
+    /// Decrypt the data in `buffer` in-place, verify the appended authentication tag, and return
+    /// the resulting byte slice in case of success.
+    ///
+    /// Returns an error if the provided authentication tag does not match the given ciphertext
+    /// or if the size of `buffer` is smaller than the tag size.
+    ///
+    /// The returned byte slice is guaranteed to point to the output of `buffer`.
     #[inline]
     fn postfix_decrypt_inplace<'out>(
         &self,
@@ -227,6 +254,13 @@ pub trait Aead {
         Ok(buf)
     }
 
+    /// Encrypt the data in `plaintext`, write resulting ciphertext to `buffer`, append
+    /// the authentication tag, and return the resulting byte slice.
+    ///
+    /// `buffer` should have at least [`TagSize`][Aead::TagSize] bytes of additional capacity;
+    /// otherwise, the method will return an error.
+    ///
+    /// The returned byte slice is guaranteed to point to the output of `buffer`.
     #[inline]
     fn postfix_encrypt_to_buf<'out>(
         &self,
@@ -245,8 +279,15 @@ pub trait Aead {
         Ok(buf)
     }
 
-    /// Encrypt the data buffer-to-buffer, returning an error in the event the provided
-    /// authentication tag does not match the given ciphertext.
+    /// Decrypt the data in `ciphertext`, write resulting ciphertext to `buffer`, verify
+    /// the appended authentication tag, and return the resulting byte slice in case of success.
+    ///
+    /// Returns an error if the provided authentication tag does not match the given ciphertext,
+    /// if the size of `ciphertext` is smaller than the tag size, or if the size of `buffer` is
+    /// too small for resulting plaintext (i.e. it should have capacity of at least
+    /// `ciphertext.len() - tag_size`).
+    ///
+    /// The returned byte slice is guaranteed to point to the output of `buffer`.
     #[inline]
     fn postfix_decrypt_to_buf<'out>(
         &self,
@@ -265,6 +306,9 @@ pub trait Aead {
         Ok(pt_dst)
     }
 
+    /// Encrypt the data in `buffer`, and append the authentication tag to it.
+    ///
+    /// `buffer` is a generic [`Buffer`] type. See the trait docs for more information.
     #[inline]
     fn postfix_encrypt_buffer(
         &self,
@@ -276,6 +320,11 @@ pub trait Aead {
         buffer.extend_from_slice(&tag)
     }
 
+    /// Decrypt the data in `buffer`, verify the appended authentication tag, and truncate `buffer`
+    /// to contain only the resulting plaintext.
+    ///
+    /// Returns an error if the provided authentication tag does not match the given ciphertext,
+    /// or if the length of `buffer` is smaller than the tag size.
     #[inline]
     fn postfix_decrypt_buffer(
         &self,