yuzu-emu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2024-11-22 13:25:41 +01:00
Code Issues Packages Projects Releases Wiki Activity

Document parameter preconditions in CAMELLIA module

Browse Source
This commit is contained in:
Hanno Becker 2018-12-12 14:54:16 +00:00
parent 54b789aa74
commit 7a16aaddba
1 changed files with 107 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

170
include/mbedtls/camellia.h
View File

@ -72,52 +72,68 @@ mbedtls_camellia_context;
#endif /* MBEDTLS_CAMELLIA_ALT */
/**
* \brief Initialize CAMELLIA context
* \brief Initialize a CAMELLIA context.
*
* \param ctx CAMELLIA context to be initialized
* \param ctx The CAMELLIA context to be initialized.
* This must not be \c NULL.
*/
void mbedtls_camellia_init( mbedtls_camellia_context *ctx );
/**
* \brief Clear CAMELLIA context
* \brief Clear a CAMELLIA context.
*
* \param ctx CAMELLIA context to be cleared
* \param ctx The CAMELLIA context to be cleared. May be \c NULL,
* in which case this function is a no-op. If it is not
* \c NULL, it must be initialized.
*/
void mbedtls_camellia_free( mbedtls_camellia_context *ctx );
/**
* \brief CAMELLIA key schedule (encryption)
* \brief Perform a CAMELLIA key schedule (encryption).
*
* \param ctx CAMELLIA context to be initialized
* \param key encryption key
* \param keybits must be 128, 192 or 256
* \param ctx The CAMELLIA context to use. This must be initialized.
* \param key The encryption key to use. Must be a readable buffer
* of size \p keybits bits.
* \param keybits The length of \p key in Bits. Must be either \c 128,
* \c 192 or \c 256.
*
* \return 0 if successful, or MBEDTLS_ERR_CAMELLIA_BAD_INPUT_DATA
* \return \c 0 if successful.
* \return A negative error code on failure.
*/
int mbedtls_camellia_setkey_enc( mbedtls_camellia_context *ctx, const unsigned char *key,
unsigned int keybits );
int mbedtls_camellia_setkey_enc( mbedtls_camellia_context *ctx,
const unsigned char *key,
unsigned int keybits );
/**
* \brief CAMELLIA key schedule (decryption)
* \brief Perform a CAMELLIA key schedule (decryption).
*
* \param ctx CAMELLIA context to be initialized
* \param key decryption key
* \param keybits must be 128, 192 or 256
* \param ctx The CAMELLIA context to use. This must be initialized.
* \param key The decryption key. Must be a readable buffer
* of size \p keybits bits.
* \param keybits The length of \p key in Bits. Must be either \c 128,
* \c 192 or \c 256.
*
* \return 0 if successful, or MBEDTLS_ERR_CAMELLIA_BAD_INPUT_DATA
* \return \c 0 if successful.
* \return A negative error code on failure.
*/
int mbedtls_camellia_setkey_dec( mbedtls_camellia_context *ctx, const unsigned char *key,
unsigned int keybits );
int mbedtls_camellia_setkey_dec( mbedtls_camellia_context *ctx,
const unsigned char *key,
unsigned int keybits );
/**
* \brief CAMELLIA-ECB block encryption/decryption
* \brief Perform a CAMELLIA-ECB block encryption/decryption.
*
* \param ctx CAMELLIA context
* \param mode MBEDTLS_CAMELLIA_ENCRYPT or MBEDTLS_CAMELLIA_DECRYPT
* \param input 16-byte input block
* \param output 16-byte output block
* \param ctx The CAMELLIA context to use. Must be initialized
* and bound to a key.
* \param mode The mode of operation. Must be either
* #MBEDTLS_CAMELLIA_ENCRYPT or #MBEDTLS_CAMELLIA_DECRYPT.
* \param input The input block. Must be a readable buffer
* of size \c 16 Bytes.
* \param output The output block. Must be a writable buffer
* of size \c 16 Bytes.
*
* \return 0 if successful
* \return \c 0 if successful.
* \return A negative error code on failure.
*/
int mbedtls_camellia_crypt_ecb( mbedtls_camellia_context *ctx,
int mode,
@ -126,9 +142,7 @@ int mbedtls_camellia_crypt_ecb( mbedtls_camellia_context *ctx,
#if defined(MBEDTLS_CIPHER_MODE_CBC)
/**
* \brief CAMELLIA-CBC buffer encryption/decryption
* Length should be a multiple of the block
* size (16 bytes)
* \brief Perform a CAMELLIA-CBC buffer encryption/decryption.
*
* \note Upon exit, the content of the IV is updated so that you can
* call the function same function again on the following
@ -138,15 +152,24 @@ int mbedtls_camellia_crypt_ecb( mbedtls_camellia_context *ctx,
* IV, you should either save it manually or use the cipher
* module instead.
*
* \param ctx CAMELLIA context
* \param mode MBEDTLS_CAMELLIA_ENCRYPT or MBEDTLS_CAMELLIA_DECRYPT
* \param length length of the input data
* \param iv initialization vector (updated after use)
* \param input buffer holding the input data
* \param output buffer holding the output data
* \param ctx The CAMELLIA context to use. Must be initialized
* and bound to a key.
* \param mode The mode of operation. Possible values are
* #MBEDTLS_CAMELLIA_ENCRYPT or #MBEDTLS_CAMELLIA_DECRYPT.
* \param length The length in Bytes of the input data.
* Must be a multiple of \c 16.
* \param iv The initialization vector. This must be RW buffer
* of length \c 16 Bytes. It is updated to allow streaming
* use as explained above.
* \param input The buffer holding the input data. Must point to a readable
* buffer of length \p length Bytes. May be \c NULL if
* `length == 0`.
* \param input The buffer holding the output data. Must point to a writable
* buffer of length \p length Bytes. May be \c NULL if
* `length == 0`.
*
* \return 0 if successful, or
* MBEDTLS_ERR_CAMELLIA_INVALID_INPUT_LENGTH
* \return \c 0 if successful.
* \return A negative error code on failure.
*/
int mbedtls_camellia_crypt_cbc( mbedtls_camellia_context *ctx,
int mode,
@ -158,11 +181,13 @@ int mbedtls_camellia_crypt_cbc( mbedtls_camellia_context *ctx,
#if defined(MBEDTLS_CIPHER_MODE_CFB)
/**
* \brief CAMELLIA-CFB128 buffer encryption/decryption
* \brief Perform a CAMELLIA-CFB128 buffer encryption/decryption.
*
* Note: Due to the nature of CFB you should use the same key schedule for
* both encryption and decryption. So a context initialized with
* mbedtls_camellia_setkey_enc() for both MBEDTLS_CAMELLIA_ENCRYPT and CAMELLIE_DECRYPT.
* \note Due to the nature of CFB you should use the same key
* schedule for both encryption and decryption. So a
* context initialized with mbedtls_camellia_setkey_enc()
* for both #MBEDTLS_CAMELLIA_ENCRYPT and
* #MBEDTLS_CAMELLIA_DECRYPT.
*
* \note Upon exit, the content of the IV is updated so that you can
* call the function same function again on the following
@ -172,16 +197,26 @@ int mbedtls_camellia_crypt_cbc( mbedtls_camellia_context *ctx,
* IV, you should either save it manually or use the cipher
* module instead.
*
* \param ctx CAMELLIA context
* \param mode MBEDTLS_CAMELLIA_ENCRYPT or MBEDTLS_CAMELLIA_DECRYPT
* \param length length of the input data
* \param iv_off offset in IV (updated after use)
* \param iv initialization vector (updated after use)
* \param input buffer holding the input data
* \param output buffer holding the output data
* \param ctx The CAMELLIA context to use. Must be initialized
* and bound to a key.
* \param mode The mode of operation. Possible values are
* #MBEDTLS_CAMELLIA_ENCRYPT or #MBEDTLS_CAMELLIA_DECRYPT.
* \param length The length of the input data. Any value is allowed.
* \param iv_off The current offset in the IV. This must be smaller
* than \c 16. It is updated after this call to allow
* the aforementioned streaming usage.
* \param iv The initialization vector. Must be an RW buffer of
* length \c 16 Bytes. It is updated after this call to
* allow the aforementioned streaming usage.
* \param input The buffer holding the input data. Must be a readable
* buffer of size \p length Bytes. May be \c NULL if
* \p length is \c 0.
* \param output The buffer to hold the output data. Must be a writable
* buffer of length \p length Bytes. May be \c NULL if
* \p length is \c 0.
*
* \return 0 if successful, or
* MBEDTLS_ERR_CAMELLIA_BAD_INPUT_DATA.
* \return \c 0 if successful.
* \return A negative error code on failure.
*/
int mbedtls_camellia_crypt_cfb128( mbedtls_camellia_context *ctx,
int mode,
@ -194,11 +229,13 @@ int mbedtls_camellia_crypt_cfb128( mbedtls_camellia_context *ctx,
#if defined(MBEDTLS_CIPHER_MODE_CTR)
/**
* \brief CAMELLIA-CTR buffer encryption/decryption
* \brief CAMELLIA-CTR buffer encryption/decryption
*
* Note: Due to the nature of CTR you should use the same key schedule for
* both encryption and decryption. So a context initialized with
* mbedtls_camellia_setkey_enc() for both MBEDTLS_CAMELLIA_ENCRYPT and MBEDTLS_CAMELLIA_DECRYPT.
* \note Due to the nature of CTR you should use the same key
* schedule for both encryption and decryption. So a
* context initialized with mbedtls_camellia_setkey_enc()
* for both #MBEDTLS_CAMELLIA_ENCRYPT and
* #MBEDTLS_CAMELLIA_DECRYPT.
*
* \warning You must never reuse a nonce value with the same key. Doing so
* would void the encryption for the two messages encrypted with
@ -238,24 +275,31 @@ int mbedtls_camellia_crypt_cfb128( mbedtls_camellia_context *ctx,
* more than 2**32 messages with the same key.
*
* Note that for both stategies, sizes are measured in blocks and
* that a CAMELLIA block is 16 bytes.
* that a CAMELLIA block is \c 16 bytes.
*
* \warning Upon return, \p stream_block contains sensitive data. Its
* content must not be written to insecure storage and should be
* securely discarded as soon as it's no longer needed.
*
* \param ctx CAMELLIA context
* \param length The length of the data
* \param nc_off The offset in the current stream_block (for resuming
* \param ctx The CAMELLIA context to use.
* \param length The length of the input data. Any value is allowed.
* \param nc_off The offset in the current \p stream_block (for resuming
* within current cipher stream). The offset pointer to
* should be 0 at the start of a stream.
* \param nonce_counter The 128-bit nonce and counter.
* \param stream_block The saved stream-block for resuming. Is overwritten
* by the function.
* \param input The input data stream
* \param output The output data stream
* should be \c 0 at the start of a stream. It is updated
* at the end of this call.
* \param nonce_counter The 128-bit nonce and counter. Must be an RW buffer of
* length \c 16 Bytes.
* \param stream_block The saved stream-block for resuming. Must be an
* RW buffer of length \c 16 Bytes.
* \param input The input data stream. Must be a readable buffer of
* size \p length Bytes. This may be \c NULL if \p length
* is \c 0.
* \param output The output data stream. Must be a writable buffer of
* size \p length Bytes. This may be \c NULL if \p length
* is \c 0.
*
* \return 0 if successful
* \return \c 0 if successful.
* \return A negative error code on failure.
*/
int mbedtls_camellia_crypt_ctr( mbedtls_camellia_context *ctx,
size_t length,