yuzu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2024-12-23 10:05:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improve documentation of cipher_auth_xxcrypt()

Browse source 
- Document constraints on buffers/pointers NULLability explicitly.
- Simplify terminology around IV/nonce: all AEADs implemented so far call that
  a nonce. Keep the parameter names (iv, iv_len) to avoid having to change the
code (or having different names in the header and C files).
- Align documentation to the code regarding parameter constraints: the
  documentation said the for ciphers with fixed nonce/tag length, the
iv_len/tag_len arguments were ignored, while the code enforced them to be the
expected value. This is more consistent with what's done with GCM/CCM, which
for tag_len for example accept more than one value, but from a relatively
small set, and will return errors for values outside that set. Accepting a
single value is a particular case of that (the set of acceptable value only
has one element).

Don't document behaviour with NIST KW as we're about to change that.

Note: this function is currently only defined if at least one of GCM, CCM or
ChachaPoly is enabled, even though it's supposed to handle NIST KW as well. No
need to fix this as the function will soon no longer support NIST KW.

Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
This commit is contained in:
Manuel Pégourié-Gonnard 2020-11-20 10:17:20 +01:00
parent 489c058b52
commit 3ba84d5bd6
1 changed files with 50 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

80
include/mbedtls/cipher.h
View file

@ -862,25 +862,35 @@ int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx,
*
* \param ctx The generic cipher context. This must be initialized and
* bound to a key.
* \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
* This must be a readable buffer of at least \p iv_len
* Bytes.
* \param iv_len The IV length for ciphers with variable-size IV.
* This parameter is discarded by ciphers with fixed-size IV.
* \param iv The nonce to use. This must be a readable buffer of
* at least \p iv_len Bytes and must not be \c NULL.
* \param iv_len The length of the nonce. This must satisfy the
* constraints imposed by the AEAD cipher used.
* \param ad The additional data to authenticate. This must be a
* readable buffer of at least \p ad_len Bytes.
* readable buffer of at least \p ad_len Bytes, and may
* be \c NULL is \p ad_len is \c 0.
* \param ad_len The length of \p ad.
* \param input The buffer holding the input data. This must be a
* readable buffer of at least \p ilen Bytes.
* readable buffer of at least \p ilen Bytes, and may be
* \c NULL if \p ilen is \c 0.
* \param ilen The length of the input data.
* \param output The buffer for the output data. This must be able to
* hold at least \p ilen Bytes.
* \param olen The length of the output data, to be updated with the
* actual number of Bytes written. This must not be
* \c NULL.
* \param output The buffer for the output data. This must be a
* writable buffer of at least \p ilen Bytes, and must
* not be \c NULL.
* \param olen This will be filled with the actual number of Bytes
* written to the \p output buffer. This must point to a
* writable object of type \c size_t.
* \param tag The buffer for the authentication tag. This must be a
* writable buffer of at least \p tag_len Bytes.
* \param tag_len The desired length of the authentication tag.
* writable buffer of at least \p tag_len Bytes. See note
* below regarding restrictions with PSA-based contexts.
* \param tag_len The desired length of the authentication tag. This
* must match the constraints imposed by the AEAD cipher
* used, and in particuler must not be \c 0.
*
* \note If the context is based on PSA (that is, it was set up
* with mbedtls_cipher_setup_psa()), then it is required
* that \c tag == output + ilen. That is, the tag must be
* appended to the ciphertext as recommended by RFC 5116.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
@ -903,25 +913,35 @@ int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx,
*
* \param ctx The generic cipher context. This must be initialized and
* and bound to a key.
* \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
* This must be a readable buffer of at least \p iv_len
* Bytes.
* \param iv_len The IV length for ciphers with variable-size IV.
* This parameter is discarded by ciphers with fixed-size IV.
* \param ad The additional data to be authenticated. This must be a
* readable buffer of at least \p ad_len Bytes.
* \param iv The nonce to use. This must be a readable buffer of
* at least \p iv_len Bytes and must not be \c NULL.
* \param iv_len The length of the nonce. This must satisfy the
* constraints imposed by the AEAD cipher used.
* \param ad The additional data to authenticate. This must be a
* readable buffer of at least \p ad_len Bytes, and may
* be \c NULL is \p ad_len is \c 0.
* \param ad_len The length of \p ad.
* \param input The buffer holding the input data. This must be a
* readable buffer of at least \p ilen Bytes.
* readable buffer of at least \p ilen Bytes, and may be
* \c NULL if \p ilen is \c 0.
* \param ilen The length of the input data.
* \param output The buffer for the output data.
* This must be able to hold at least \p ilen Bytes.
* \param olen The length of the output data, to be updated with the
* actual number of Bytes written. This must not be
* \c NULL.
* \param tag The buffer holding the authentication tag. This must be
* a readable buffer of at least \p tag_len Bytes.
* \param tag_len The length of the authentication tag.
* \param output The buffer for the output data. This must be a
* writable buffer of at least \p ilen Bytes, and must
* not be \c NULL.
* \param olen This will be filled with the actual number of Bytes
* written to the \p output buffer. This must point to a
* writable object of type \c size_t.
* \param tag The buffer for the authentication tag. This must be a
* readable buffer of at least \p tag_len Bytes. See note
* below regarding restrictions with PSA-based contexts.
* \param tag_len The length of the authentication tag. This must match
* the constraints imposed by the AEAD cipher used, and in
* particular must not be \c 0.
*
* \note If the context is based on PSA (that is, it was set up
* with mbedtls_cipher_setup_psa()), then it is required
* that \c tag == input + len. That is, the tag must be
* appended to the ciphertext as recommended by RFC 5116.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on