yuzu-emu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2024-11-23 00:25:39 +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

164
include/mbedtls/camellia.h
View File

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