From 4b8c50a075e300a087c7898b2225569c3a195d38 Mon Sep 17 00:00:00 2001 From: Yuxiang Cao Date: Tue, 2 May 2023 13:07:41 -0700 Subject: [PATCH] doc: add comments for functions Add comments for functions: - encrypt_auth_inplace - decrypt_auth_inplace --- mbedtls/src/cipher/raw/mod.rs | 42 +++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/mbedtls/src/cipher/raw/mod.rs b/mbedtls/src/cipher/raw/mod.rs index 0b546043f..05d451898 100644 --- a/mbedtls/src/cipher/raw/mod.rs +++ b/mbedtls/src/cipher/raw/mod.rs @@ -423,6 +423,25 @@ impl Cipher { Ok(plain_len) } + /// The authenticated encryption (AEAD/NIST_KW) function. + /// + /// For AEAD modes, the tag will be appended to the ciphertext, as recommended by RFC 5116. + /// (NIST_KW doesn't have a separate tag.) + /// + /// # Arguments + /// + /// * `ad` - The additional data to authenticate + /// * `data_with_tag` - The data to be encrypted and authenticated, along with space for the tag + /// * `tag_len` - The length of the tag to be generated + /// + /// # Returns + /// + /// * `Result` - The length of the encrypted data on success + /// + /// # Errors + /// + /// * `Error::CipherBadInputData` - If the size of `data_with_tag` minus `tag_len` is less than + /// or equal to zero pub fn encrypt_auth_inplace( &mut self, ad: &[u8], @@ -455,6 +474,29 @@ impl Cipher { Ok(olen) } + + /// The authenticated encryption (AEAD/NIST_KW) function. + /// + /// If the data is not authentic, then the output buffer is zeroed out to + /// prevent the unauthentic plaintext being used, making this interface safer. + /// + /// For AEAD modes, the tag must be appended to the ciphertext, as recommended by RFC 5116. + /// (NIST_KW doesn't have a separate tag.) + /// + /// # Arguments + /// + /// * `ad` - The additional data to authenticate + /// * `data_with_tag` - The data to be encrypted and authenticated, along with space for the tag + /// * `tag_len` - The length of the tag to be generated + /// + /// # Returns + /// + /// * `Result` - The length of the decrypted data on success + /// + /// # Errors + /// + /// * `Error::CipherBadInputData` - If the size of `data_with_tag` minus `tag_len` is less than + /// or equal to zero pub fn decrypt_auth_inplace( &mut self, ad: &[u8],