From 99ed73349dcb67a64ec335203b7a467127ec17ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D1=80=D1=82=D1=91=D0=BC=20=D0=9F=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=BE=D0=B2=20=5BArtyom=20Pavlov=5D?= Date: Mon, 18 Nov 2024 16:40:29 +0300 Subject: [PATCH] Add some docs --- aead/src/dyn_aead.rs | 11 +++++--- aead/src/lib.rs | 63 +++++++++++++++++++++++++++++++++++++++----- 2 files changed, 63 insertions(+), 11 deletions(-) diff --git a/aead/src/dyn_aead.rs b/aead/src/dyn_aead.rs index 88e458df..79a2da20 100644 --- a/aead/src/dyn_aead.rs +++ b/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,7 +58,7 @@ 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], @@ -63,7 +66,7 @@ pub trait DynAead: sealed::Sealed { buffer: &mut dyn Buffer, ) -> Result<()>; - fn decrypt_to_buffer( + fn decrypt_to_buffer2( &self, nonce: &[u8], associated_data: &[u8], @@ -154,7 +157,7 @@ impl 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 DynAead for T { Aead::encrypt_to_buffer(self, nonce, payload, buffer) } - fn decrypt_to_buffer( + fn decrypt_to_buffer2( &self, nonce: &[u8], aad: &[u8], diff --git a/aead/src/lib.rs b/aead/src/lib.rs index 4b17ac8f..2556b99a 100644 --- a/aead/src/lib.rs +++ b/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,