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

Document parameter preconditions for Blowfish module

Browse source
This commit is contained in:
Hanno Becker 2018-12-12 18:14:08 +00:00
parent 54b789aa74
commit 3b4d6c6925
1 changed files with 76 additions and 43 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

119
include/mbedtls/blowfish.h
View file

@ -76,40 +76,51 @@ mbedtls_blowfish_context;
#endif /* MBEDTLS_BLOWFISH_ALT */ #endif /* MBEDTLS_BLOWFISH_ALT */
/** /**
* \brief Initialize Blowfish context * \brief Initialize a Blowfish context.
* *
* \param ctx Blowfish context to be initialized * \param ctx The Blowfish context to be initialized.
* Must not be \c NULL.
*/ */
void mbedtls_blowfish_init( mbedtls_blowfish_context *ctx ); void mbedtls_blowfish_init( mbedtls_blowfish_context *ctx );
/** /**
* \brief Clear Blowfish context * \brief Clear a Blowfish context.
* *
* \param ctx Blowfish context to be cleared * \param ctx The Blowfish context to be cleared.
* This may be \c NULL, in which case this function
* is a no-op. If it is not \c NULL, it must point
* to an initialized Blowfish context.
*/ */
void mbedtls_blowfish_free( mbedtls_blowfish_context *ctx ); void mbedtls_blowfish_free( mbedtls_blowfish_context *ctx );
/** /**
* \brief Blowfish key schedule * \brief Perform a Blowfish key schedule.
* *
* \param ctx Blowfish context to be initialized * \param ctx The Blowfish context to perform the key schedule on.
* \param key encryption key * \param key The encryption key. Must be a readable buffer of
* \param keybits must be between 32 and 448 bits * length \p keybits Bits.
* \param keybits The length of \p key in Bits. Must be between
* \c 32 and \c 448 and a multiple of \c 8.
* *
* \return 0 if successful, or MBEDTLS_ERR_BLOWFISH_BAD_INPUT_DATA * \return \c 0 if successful.
* \return A negative error code on failure.
*/ */
int mbedtls_blowfish_setkey( mbedtls_blowfish_context *ctx, const unsigned char *key, int mbedtls_blowfish_setkey( mbedtls_blowfish_context *ctx, const unsigned char *key,
unsigned int keybits ); unsigned int keybits );
/** /**
* \brief Blowfish-ECB block encryption/decryption * \brief Perform a Blowfish-ECB block encryption/decryption.
* *
* \param ctx Blowfish context * \param ctx The Blowfish context to use. This must be initialized
* \param mode MBEDTLS_BLOWFISH_ENCRYPT or MBEDTLS_BLOWFISH_DECRYPT * and bound to a key.
* \param input 8-byte input block * \param mode The mode of operation. Possible values are
* \param output 8-byte output block * #MBEDTLS_BLOWFISH_ENCRYPT for encryption, or
* #MBEDTLS_BLOWFISH_DECRYPT for decryption.
* \param input The input block. Must be a readable buffer of size 8 Bytes.
* \param input The output block. Must be a writable buffer of size 8 Bytes.
* *
* \return 0 if successful * \return \c 0 if successful.
* \return A negative error code on failure.
*/ */
int mbedtls_blowfish_crypt_ecb( mbedtls_blowfish_context *ctx, int mbedtls_blowfish_crypt_ecb( mbedtls_blowfish_context *ctx,
int mode, int mode,
@ -118,7 +129,7 @@ int mbedtls_blowfish_crypt_ecb( mbedtls_blowfish_context *ctx,
#if defined(MBEDTLS_CIPHER_MODE_CBC) #if defined(MBEDTLS_CIPHER_MODE_CBC)
/** /**
* \brief Blowfish-CBC buffer encryption/decryption * \brief Perform a Blowfish-CBC buffer encryption/decryption
* Length should be a multiple of the block * Length should be a multiple of the block
* size (8 bytes) * size (8 bytes)
* *
@ -130,15 +141,21 @@ int mbedtls_blowfish_crypt_ecb( mbedtls_blowfish_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 Blowfish context * \param ctx The Blowfish context to use. This must be initialized
* \param mode MBEDTLS_BLOWFISH_ENCRYPT or MBEDTLS_BLOWFISH_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_BLOWFISH_ENCRYPT for encryption, or
* \param input buffer holding the input data * #MBEDTLS_BLOWFISH_DECRYPT for decryption.
* \param output buffer holding the output data * \param length The length of the input data in Bytes.
* \param iv The initialization vector. This must be an RW buffer
* of length \c 8 Bytes. It is updated by this function.
* \param input The input data. Must be a readable buffer of length
* \p length Bytes. If \p length if \c 0, it may be \c NULL.
* \param output The output data. Must be a writable buffer of length
* \p length Bytes. If \p length if \c 0, it may be \c NULL.
* *
* \return 0 if successful, or * \return \c 0 if successful.
* MBEDTLS_ERR_BLOWFISH_INVALID_INPUT_LENGTH * \return A negative error code on failure.
*/ */
int mbedtls_blowfish_crypt_cbc( mbedtls_blowfish_context *ctx, int mbedtls_blowfish_crypt_cbc( mbedtls_blowfish_context *ctx,
int mode, int mode,
@ -150,7 +167,7 @@ int mbedtls_blowfish_crypt_cbc( mbedtls_blowfish_context *ctx,
#if defined(MBEDTLS_CIPHER_MODE_CFB) #if defined(MBEDTLS_CIPHER_MODE_CFB)
/** /**
* \brief Blowfish CFB buffer encryption/decryption. * \brief Perform a Blowfish CFB buffer encryption/decryption.
* *
* \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
@ -160,15 +177,25 @@ int mbedtls_blowfish_crypt_cbc( mbedtls_blowfish_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 Blowfish context * \param ctx The Blowfish context to use. This must be initialized
* \param mode MBEDTLS_BLOWFISH_ENCRYPT or MBEDTLS_BLOWFISH_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_BLOWFISH_ENCRYPT for encryption, or
* \param iv initialization vector (updated after use) * #MBEDTLS_BLOWFISH_DECRYPT for decryption.
* \param input buffer holding the input data * \param length The length of the input data in Bytes.
* \param output buffer holding the output data * \param iv_off The offset in the initialiation vector.
* The value pointed to must be smaller than \c 8.
* It is updated by this function to support the aforementioned
* streaming usage.
* \param iv The initialization vector. Must be an RW buffer of
* size \c 8 Bytes. It is updated after use.
* \param input The input data. Must be a readable buffer of length
* \p length Bytes. If \p length if \c 0, it may be \c NULL.
* \param output The output data. Must be a writable buffer of length
* \p length Bytes. If \p length if \c 0, it may be \c NULL.
* *
* \return 0 if successful * \return \c 0 if successful.
* \return A negative error code on failure.
*/ */
int mbedtls_blowfish_crypt_cfb64( mbedtls_blowfish_context *ctx, int mbedtls_blowfish_crypt_cfb64( mbedtls_blowfish_context *ctx,
int mode, int mode,
@ -181,7 +208,7 @@ int mbedtls_blowfish_crypt_cfb64( mbedtls_blowfish_context *ctx,
#if defined(MBEDTLS_CIPHER_MODE_CTR) #if defined(MBEDTLS_CIPHER_MODE_CTR)
/** /**
* \brief Blowfish-CTR buffer encryption/decryption * \brief Perform a Blowfish-CTR buffer encryption/decryption.
* *
* \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
@ -224,18 +251,24 @@ int mbedtls_blowfish_crypt_cfb64( mbedtls_blowfish_context *ctx,
* 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 Blowfish context * \param ctx The Blowfish context to use. This must be initialized
* \param length The length of the data * and bound to a key.
* \param length The length of the input data in Bytes.
* \param nc_off The offset in the current stream_block (for resuming * \param nc_off The offset in the current 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 and must be
* \param nonce_counter The 64-bit nonce and counter. * smaller than \c 8. It is updated by this function.
* \param stream_block The saved stream-block for resuming. Is overwritten * \param nonce_counter The 64-bit nonce and counter. This must point to an RW
* by the function. * buffer of length \c 8 Bytes.
* \param input The input data stream * \param stream_block The saved stream-block for resuming. This must point to
* \param output The output data stream * an RW buffer of length \c 8 Bytes.
* \param input The input data. Must be a readable buffer of length
* \p length Bytes. If \p length if \c 0, it may be \c NULL.
* \param output The output data. Must be a writable buffer of length
* \p length Bytes. If \p length if \c 0, it may be \c NULL.
* *
* \return 0 if successful * \return \c 0 if successful.
* \return A negative error code on failure.
*/ */
int mbedtls_blowfish_crypt_ctr( mbedtls_blowfish_context *ctx, int mbedtls_blowfish_crypt_ctr( mbedtls_blowfish_context *ctx,
size_t length, size_t length,