cuberite/polarssl
1
0
Fork 0
mirror of https://github.com/cuberite/polarssl.git synced 2025-10-30 19:20:40 -04:00
Code Issues Packages Projects Releases Wiki Activity

Improve documentation of the parameter validation in the Cipher module

Browse Source
This commit is contained in:
k-stachowiak 2018-12-18 14:59:16 +01:00
parent a539070f82
commit d5913bc115
1 changed files with 61 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

103
include/mbedtls/cipher.h
View File

@ -336,12 +336,12 @@ const int *mbedtls_cipher_list( void );
* \brief This function retrieves the cipher-information * \brief This function retrieves the cipher-information
* structure associated with the given cipher name. * structure associated with the given cipher name.
* *
* \param cipher_name Name of the cipher to search for. This can be \c NULL. * \param cipher_name Name of the cipher to search for. This must not be
* \c NULL.
* *
* \return The cipher information structure associated with the * \return The cipher information structure associated with the
* given \p cipher_name. * given \p cipher_name.
* \return \c NULL if the associated cipher information is not found * \return \c NULL if the associated cipher information is not found.
* or if \p cipher_name is \c NULL.
*/ */
const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string( const char *cipher_name ); const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string( const char *cipher_name );
@ -388,7 +388,8 @@ void mbedtls_cipher_init( mbedtls_cipher_context_t *ctx );
* responsibility of the caller. * responsibility of the caller.
* *
* \param ctx The context to be freed. If this is \c NULL, the * \param ctx The context to be freed. If this is \c NULL, the
* function has no effect. * function has no effect, otherwise this must point to an
* initialized context.
*/ */
void mbedtls_cipher_free( mbedtls_cipher_context_t *ctx ); void mbedtls_cipher_free( mbedtls_cipher_context_t *ctx );
@ -419,8 +420,8 @@ int mbedtls_cipher_setup( mbedtls_cipher_context_t *ctx,
* *
* \param ctx The context of the cipher. This must be initialized. * \param ctx The context of the cipher. This must be initialized.
* *
* \return The size of the blocks of the cipher. * \return The block size of the underlying cipher.
* \return 0 if \p ctx has not been initialized. * \return \c 0 if \p ctx has not been initialized.
*/ */
static inline unsigned int mbedtls_cipher_get_block_size( static inline unsigned int mbedtls_cipher_get_block_size(
const mbedtls_cipher_context_t *ctx ) const mbedtls_cipher_context_t *ctx )
@ -544,9 +545,8 @@ static inline mbedtls_operation_t mbedtls_cipher_get_operation(
/** /**
* \brief This function sets the key to use with the given context. * \brief This function sets the key to use with the given context.
* *
* \param ctx The generic cipher context. This must be initialized * \param ctx The generic cipher context. This must be initialized and
* using mbedtls_cipher_info_from_type() or * bound to a cipher information structure.
* mbedtls_cipher_info_from_string().
* \param key The key to use. This must be a readable buffer of at * \param key The key to use. This must be a readable buffer of at
* least \p key_bitlen Bits. * least \p key_bitlen Bits.
* \param key_bitlen The key length to use, in Bits. * \param key_bitlen The key length to use, in Bits.
@ -570,7 +570,8 @@ int mbedtls_cipher_setkey( mbedtls_cipher_context_t *ctx,
* *
* The default passing mode is PKCS7 padding. * The default passing mode is PKCS7 padding.
* *
* \param ctx The generic cipher context. This must be initialized. * \param ctx The generic cipher context. This must be initialized and
* bound to a cipher information structure.
* \param mode The padding mode. * \param mode The padding mode.
* *
* \return \c 0 on success. * \return \c 0 on success.
@ -590,9 +591,11 @@ int mbedtls_cipher_set_padding_mode( mbedtls_cipher_context_t *ctx,
* \note Some ciphers do not use IVs nor nonce. For these * \note Some ciphers do not use IVs nor nonce. For these
* ciphers, this function has no effect. * ciphers, this function has no effect.
* *
* \param ctx The generic cipher context. This must be initialized. * \param ctx The generic cipher context. This must be initialized and
* \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers. This * bound to a cipher information structure.
* must be a readable buffer of at least \p iv_len Bytes. * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers. If
* `iv_len > 0`, this may be \c NULL, otherwise 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. * \param iv_len The IV length for ciphers with variable-size IV.
* This parameter is discarded by ciphers with fixed-size IV. * This parameter is discarded by ciphers with fixed-size IV.
* *
@ -624,8 +627,9 @@ int mbedtls_cipher_reset( mbedtls_cipher_context_t *ctx );
* *
* \param ctx The generic cipher context. This must be initialized. * \param ctx The generic cipher context. This must be initialized.
* \param ad The additional data to use. If `ad_len > 0`, then this * \param ad The additional data to use. If `ad_len > 0`, then this
* must be a readable buffer of at least \p ad_len Bytes. * must be a readable buffer of at least \p ad_len Bytes,
* \param ad_len the Length of \p ad. * otherwise this may be \c NULL.
* \param ad_len the Length of \p ad Bytes.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return A specific error code on failure. * \return A specific error code on failure.
@ -649,12 +653,14 @@ int mbedtls_cipher_update_ad( mbedtls_cipher_context_t *ctx,
* mbedtls_cipher_finish(), must have \p ilen as a * mbedtls_cipher_finish(), must have \p ilen as a
* multiple of the block size of the cipher. * multiple of the block size of the cipher.
* *
* \param ctx The generic cipher context. This must be initialized. * \param ctx The generic cipher context. This must be initialized and
* bound to a key.
* \param input The buffer holding the input data. This must be a * \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. If
* `ilen == 0`, this may be \c NULL.
* \param ilen The length of the input data. * \param ilen The length of the input data.
* \param output The buffer for the output data. This must be able to * \param output The buffer for the output data. This must be able to
* hold at least \p ilen + block_size. This must not be the * hold at least `ilen + block_size`. This must not be the
* same buffer as \p input. * same buffer as \p input.
* \param olen The length of the output data, to be updated with the * \param olen The length of the output data, to be updated with the
* actual number of Bytes written. This must not be * actual number of Bytes written. This must not be
@ -676,7 +682,8 @@ int mbedtls_cipher_update( mbedtls_cipher_context_t *ctx, const unsigned char *i
* contained in it is padded to the size of * contained in it is padded to the size of
* the last block, and written to the \p output buffer. * the last block, and written to the \p output buffer.
* *
* \param ctx The generic cipher context. This must be initialized. * \param ctx The generic cipher context. This must be initialized and
* bound to a key.
* \param output The buffer to write data to. This needs to be a writable * \param output The buffer to write data to. This needs to be a writable
* buffer of at least \p block_size Bytes. * buffer of at least \p block_size Bytes.
* \param olen The length of the data written to the \p output buffer. * \param olen The length of the data written to the \p output buffer.
@ -700,9 +707,13 @@ int mbedtls_cipher_finish( mbedtls_cipher_context_t *ctx,
* Currently supported with GCM and ChaCha20+Poly1305. * Currently supported with GCM and ChaCha20+Poly1305.
* This must be called after mbedtls_cipher_finish(). * This must be called after mbedtls_cipher_finish().
* *
* \param ctx The generic cipher context. This must be initialized. * \param ctx The generic cipher context. This must be initialized,
* \param tag The buffer to write the tag to. This must be a readable * bound to a key, and have just completed a cipher
* boffer of at least \p tag_len Bytes. * operation through mbedtls_cipher_finish() the tag for
* which should be written.
* \param tag The buffer to write the tag to. This must be a writable
* buffer of at least \p tag_len Bytes. If `tag_len == 0`,
* this may be \c NULL.
* \param tag_len The length of the tag to write. * \param tag_len The length of the tag to write.
* *
* \return \c 0 on success. * \return \c 0 on success.
@ -717,8 +728,9 @@ int mbedtls_cipher_write_tag( mbedtls_cipher_context_t *ctx,
* This must be called after mbedtls_cipher_finish(). * This must be called after mbedtls_cipher_finish().
* *
* \param ctx The generic cipher context. This must be initialized. * \param ctx The generic cipher context. This must be initialized.
* \param tag The buffer holding the tag. This must be a readable * \param tag The buffer holding the tag. If `tag_len > 0`, then this
* buffer of at least \p tag_len Bytes. * must be a readable buffer of at least \p tag_len Bytes,
* otherwise this may be \c NULL.
* \param tag_len The length of the tag to check. * \param tag_len The length of the tag to check.
* *
* \return \c 0 on success. * \return \c 0 on success.
@ -735,15 +747,16 @@ int mbedtls_cipher_check_tag( mbedtls_cipher_context_t *ctx,
* \param ctx The generic cipher context. This must be initialized. * \param ctx The generic cipher context. This must be initialized.
* \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers. * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
* If `iv_len > 0`, this must be a readable buffer of at * If `iv_len > 0`, this must be a readable buffer of at
* least \p Bytes. * least \p iv_len Bytes, otherwise this may be \c NULL.
* \param iv_len The IV length for ciphers with variable-size IV. * \param iv_len The IV length for ciphers with variable-size IV.
* This parameter is discarded by ciphers with fixed-size * This parameter is discarded by ciphers with fixed-size
* IV. * IV.
* \param input The buffer holding the input data. This must be a * \param input The buffer holding the input data. If `ilen > 0`, then
* readable buffer of at least \p ilen Bytes. * this must be a readable buffer of at least \p ilen
* \param ilen The length of the input data. * Bytes, otherwise this may be \c NULL.
* \param ilen The length of the input data in Bytes.
* \param output The buffer for the output data. This must be able to * \param output The buffer for the output data. This must be able to
* hold at least \p ilen + block_size. This must not be the * hold at least `ilen + block_size`. This must not be the
* same buffer as \p input. * same buffer as \p input.
* \param olen The length of the output data, to be updated with the * \param olen The length of the output data, to be updated with the
* actual number of Bytes written. This must not be * actual number of Bytes written. This must not be
@ -770,7 +783,8 @@ int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx,
/** /**
* \brief The generic autenticated encryption (AEAD) function. * \brief The generic autenticated encryption (AEAD) function.
* *
* \param ctx The generic cipher context. This must be initialized. * \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. * \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 * This must be a readable buffer of at least \p iv_len
* Bytes. * Bytes.
@ -778,18 +792,20 @@ int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx,
* This parameter is discarded by ciphers with fixed-size IV. * This parameter is discarded by ciphers with fixed-size IV.
* \param ad The additional data to authenticate. If `ad_len > 0`, * \param ad The additional data to authenticate. If `ad_len > 0`,
* this must be a readable buffer of at least \p ad_len * this must be a readable buffer of at least \p ad_len
* Bytes. * Bytes, otherwise this may be \c NULL.
* \param ad_len The length of \p ad. * \param ad_len The length of \p ad.
* \param input The buffer holding the input data. This must be a * \param input The buffer holding the input data. If `ilen > 0`, then
* readable buffer of at least \p ilen Bytes. * this must be a readable buffer of at least \p ilen
* Bytes, otherwise this may be \c NULL.
* \param ilen The length of the input data. * \param ilen The length of the input data.
* \param output The buffer for the output data. This must be able to * \param output The buffer for the output data. This must be able to
* hold at least \p ilen. * hold at least \p ilen Bytes.
* \param olen The length of the output data, to be updated with the * \param olen The length of the output data, to be updated with the
* actual number of Bytes written. This must not be * actual number of Bytes written. This must not be
* \c NULL. * \c NULL.
* \param tag The buffer for the authentication tag. This must be a * \param tag The buffer for the authentication tag. If `tag_len > 0`,
* writable buffer of at least \p tag_len Bytes. * then this must be a writable buffer of at least
* \p tag_len Bytes, otherwise this may be \c NULL.
* \param tag_len The desired length of the authentication tag. * \param tag_len The desired length of the authentication tag.
* *
* \return \c 0 on success. * \return \c 0 on success.
@ -811,7 +827,8 @@ int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx,
* is zeroed out to prevent the unauthentic plaintext being * is zeroed out to prevent the unauthentic plaintext being
* used, making this interface safer. * used, making this interface safer.
* *
* \param ctx The generic cipher context. This must be initialized. * \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. * \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 * This must be a readable buffer of at least \p iv_len
* Bytes. * Bytes.
@ -819,18 +836,20 @@ int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx,
* This parameter is discarded by ciphers with fixed-size IV. * This parameter is discarded by ciphers with fixed-size IV.
* \param ad The additional data to be authenticated. If `ad_len > 0`, * \param ad The additional data to be authenticated. If `ad_len > 0`,
* this must be a readable buffer of at least \p ad_len * this must be a readable buffer of at least \p ad_len
* Bytes. * Bytes, otherwise this may be \c NULL.
* \param ad_len The length of \p ad. * \param ad_len The length of \p ad.
* \param input The buffer holding the input data. This must be a * \param input The buffer holding the input data. If `ilen > 0`, then
* readable buffer of at least \p ilen Bytes. * this must be a readable buffer of at least \p ilen
* Bytes, otherwise, this may be \c NULL.
* \param ilen The length of the input data. * \param ilen The length of the input data.
* \param output The buffer for the output data. * \param output The buffer for the output data.
* This must be able to hold at least \p ilen Bytes. * This must be able to hold at least \p ilen Bytes.
* \param olen The length of the output data, to be updated with the * \param olen The length of the output data, to be updated with the
* actual number of Bytes written. This must not be * actual number of Bytes written. This must not be
* \c NULL. * \c NULL.
* \param tag The buffer holding the authentication tag. This must be * \param tag The buffer holding the authentication tag. If
* a readable buffer of at least \p tag_len Bytes. * `tag_len > 0`, then this must be a readable buffer of at
* least \p tag_len Bytes, otherwise this can be \c NULL.
* \param tag_len The length of the authentication tag. * \param tag_len The length of the authentication tag.
* *
* \return \c 0 on success. * \return \c 0 on success.