yuzu-emu/mbedtls
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Clarify calling sequence in the Cipher layer

Browse source 
Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
This commit is contained in:
Manuel Pégourié-Gonnard 2021-05-31 11:13:35 +02:00
parent e9cac0e277
commit c42a0be00b
1 changed files with 36 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

37
include/mbedtls/cipher.h
View file

@ -440,6 +440,18 @@ void mbedtls_cipher_free( mbedtls_cipher_context_t *ctx );
* \brief This function prepares a cipher context for
* use with the given cipher primitive.
*
* \note After calling this function, you should call
* mbedtls_cipher_setkey() and, if the mode uses padding,
* mbedtls_cipher_set_padding_mode(), then for each
* message to encrypt or decrypt with this key, either:
* - mbedtls_cipher_crypt() for one-shot processing with
* non-AEAD modes;
* - mbedtls_cipher_auth_encrypt_ext() or
* mbedtls_cipher_auth_decrypt_ext() for one-shot
* processing with AEAD modes or NIST_KW;
* - for multi-part processing, see the documentation of
* mbedtls_cipher_reset().
*
* \param ctx The context to prepare. This must be initialized by
* a call to mbedtls_cipher_init() first.
* \param cipher_info The cipher to use.
@ -684,7 +696,30 @@ int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx,
/**
* \brief This function resets the cipher state.
*
* \param ctx The generic cipher context. This must be initialized.
* \note With non-AEAD ciphers, the order of calls for each message
* is as follows:
* 1. mbedtls_cipher_set_iv() if the mode uses an IV/nonce.
* 2. mbedtls_cipher_reset()
* 3. mbedtls_cipher_update() one or more times
* 4. mbedtls_cipher_finish()
* .
* This sequence can be repeated to encrypt of decrypt multiple
* messages with the same key.
*
* \note With AEAD ciphers, the order of calls for each message
* is as follows:
* 1. mbedtls_cipher_set_iv() if the mode uses an IV/nonce.
* 2. mbedtls_cipher_reset()
* 3. mbedtls_cipher_update_ad()
* 4. mbedtls_cipher_update() one or more times
* 5. mbedtls_cipher_finish()
* 6. mbedtls_cipher_check_tag() (for decryption) or
* mbedtls_cipher_write_tag() (for encryption).
* .
* This sequence can be repeated to encrypt of decrypt multiple
* messages with the same key.
*
* \param ctx The generic cipher context. This must be bound to a key.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on