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

CTR_DRBG documentation improvements

Browse Source 
* State explicit whether several numbers are in bits or bytes.
* Clarify whether buffer pointer parameters can be NULL.
* Clarify some terminology.
* Minor wording and formatting improvements.
This commit is contained in:
Gilles Peskine 2019-10-02 18:54:20 +02:00
parent d28b9b3c5d
commit 25e1945321
1 changed files with 70 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
include/mbedtls/ctr_drbg.h
View File

@ -1,13 +1,16 @@
/** /**
* \file ctr_drbg.h * \file ctr_drbg.h
* *
* \brief CTR_DRBG is based on AES-256, as defined in <em>NIST SP 800-90A: * \brief The CTR_DRBG pseudorandom generator.
* Recommendation for Random Number Generation Using Deterministic *
* Random Bit Generators</em>. * CTR_DRBG is a standardized way of building a PRNG from a block-cipher
* in counter mode operation, as defined in <em>NIST SP 800-90A:
* Recommendation for Random Number Generation Using Deterministic Random
* Bit Generators</em>.
* *
*/ */
/* /*
* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved * Copyright (C) 2006-2019, Arm Limited (or its affiliates), All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
* Licensed under the Apache License, Version 2.0 (the "License"); you may * Licensed under the Apache License, Version 2.0 (the "License"); you may
@ -92,7 +95,7 @@
#if !defined(MBEDTLS_CTR_DRBG_MAX_SEED_INPUT) #if !defined(MBEDTLS_CTR_DRBG_MAX_SEED_INPUT)
#define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384 #define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384
/**< The maximum size of seed or reseed buffer. */ /**< The maximum size of seed or reseed buffer in bytes. */
#endif #endif
/* \} name SECTION: Module settings */ /* \} name SECTION: Module settings */
@ -150,17 +153,21 @@ void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx );
* \brief This function seeds and sets up the CTR_DRBG * \brief This function seeds and sets up the CTR_DRBG
* entropy source for future reseeds. * entropy source for future reseeds.
* *
* \note Personalization data can be provided in addition to the more generic * You can provide a personalization string in addition to the
* entropy source, to make this instantiation as unique as possible. * entropy source, to make this instantiation as unique as possible.
* *
*
* \param ctx The CTR_DRBG context to seed. * \param ctx The CTR_DRBG context to seed.
* \param f_entropy The entropy callback, taking as arguments the * \param f_entropy The entropy callback, taking as arguments the
* \p p_entropy context, the buffer to fill, and the * \p p_entropy context, the buffer to fill, and the
length of the buffer. * length of the buffer.
* \param p_entropy The entropy context. * \param p_entropy The entropy context to pass to \p f_entropy.
* \param custom Personalization data, that is device-specific * \param custom The personalization string.
identifiers. Can be NULL. * This can be \c NULL, in which case the personalization
* \param len The length of the personalization data. * string is empty regardless of the value of \p len.
* \param len The length of the personalization string.
* This must be at most
* #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT / 2.
* *
* \return \c 0 on success, or * \return \c 0 on success, or
* #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure. * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
@ -183,7 +190,8 @@ void mbedtls_ctr_drbg_free( mbedtls_ctr_drbg_context *ctx );
* The default value is off. * The default value is off.
* *
* \note If enabled, entropy is gathered at the beginning of * \note If enabled, entropy is gathered at the beginning of
* every call to mbedtls_ctr_drbg_random_with_add(). * every call to mbedtls_ctr_drbg_random_with_add()
* or mbedtls_ctr_drbg_random().
* Only use this if your entropy source has sufficient * Only use this if your entropy source has sufficient
* throughput. * throughput.
* *
@ -199,13 +207,19 @@ void mbedtls_ctr_drbg_set_prediction_resistance( mbedtls_ctr_drbg_context *ctx,
* #MBEDTLS_CTR_DRBG_ENTROPY_LEN. * #MBEDTLS_CTR_DRBG_ENTROPY_LEN.
* *
* \param ctx The CTR_DRBG context. * \param ctx The CTR_DRBG context.
* \param len The amount of entropy to grab. * \param len The amount of entropy to grab, in bytes.
* This must be at most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
*/ */
void mbedtls_ctr_drbg_set_entropy_len( mbedtls_ctr_drbg_context *ctx, void mbedtls_ctr_drbg_set_entropy_len( mbedtls_ctr_drbg_context *ctx,
size_t len ); size_t len );
/** /**
* \brief This function sets the reseed interval. * \brief This function sets the reseed interval.
*
* The reseed interval is the number of calls to mbedtls_ctr_drbg_random()
* or mbedtls_ctr_drbg_random_with_add() after which the entropy function
* is called again.
*
* The default value is #MBEDTLS_CTR_DRBG_RESEED_INTERVAL. * The default value is #MBEDTLS_CTR_DRBG_RESEED_INTERVAL.
* *
* \param ctx The CTR_DRBG context. * \param ctx The CTR_DRBG context.
@ -219,8 +233,12 @@ void mbedtls_ctr_drbg_set_reseed_interval( mbedtls_ctr_drbg_context *ctx,
* extracts data from the entropy source. * extracts data from the entropy source.
* *
* \param ctx The CTR_DRBG context. * \param ctx The CTR_DRBG context.
* \param additional Additional data to add to the state. Can be NULL. * \param additional Additional data to add to the state. Can be \c NULL.
* \param len The length of the additional data. * \param len The length of the additional data.
* This must be less than
* #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT - \c entropy_len
* where \c entropy_len is the entropy length
* configured for the context.
* *
* \return \c 0 on success, or * \return \c 0 on success, or
* #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure. * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
@ -232,7 +250,8 @@ int mbedtls_ctr_drbg_reseed( mbedtls_ctr_drbg_context *ctx,
* \brief This function updates the state of the CTR_DRBG context. * \brief This function updates the state of the CTR_DRBG context.
* *
* \param ctx The CTR_DRBG context. * \param ctx The CTR_DRBG context.
* \param additional The data to update the state with. * \param additional The data to update the state with. This must not be
* \c NULL unless \p add_len is \c 0.
* \param add_len Length of \p additional in bytes. This must be at * \param add_len Length of \p additional in bytes. This must be at
* most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT. * most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
* *
@ -258,8 +277,10 @@ int mbedtls_ctr_drbg_update_ret( mbedtls_ctr_drbg_context *ctx,
* The remaining Bytes are silently discarded. * The remaining Bytes are silently discarded.
* *
* \param ctx The CTR_DRBG context. * \param ctx The CTR_DRBG context.
* \param additional The data to update the state with. * \param additional The data to update the state with. This must not be
* \param add_len Length of \p additional data. * \c NULL unless \p add_len is \c 0.
* \param add_len Length of \p additional data. This must be at
* most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
*/ */
void mbedtls_ctr_drbg_update( mbedtls_ctr_drbg_context *ctx, void mbedtls_ctr_drbg_update( mbedtls_ctr_drbg_context *ctx,
const unsigned char *additional, const unsigned char *additional,
@ -269,17 +290,26 @@ void mbedtls_ctr_drbg_update( mbedtls_ctr_drbg_context *ctx,
* \brief This function updates a CTR_DRBG instance with additional * \brief This function updates a CTR_DRBG instance with additional
* data and uses it to generate random data. * data and uses it to generate random data.
* *
* \note The function automatically reseeds if the reseed counter is exceeded. * This function automatically reseeds if the reseed counter is exceeded
* or prediction resistance is enabled.
* *
* \param p_rng The CTR_DRBG context. This must be a pointer to a * \param p_rng The CTR_DRBG context. This must be a pointer to a
* #mbedtls_ctr_drbg_context structure. * #mbedtls_ctr_drbg_context structure.
* \param output The buffer to fill. * \param output The buffer to fill.
* \param output_len The length of the buffer. * \param output_len The length of the buffer in bytes.
* \param additional Additional data to update. Can be NULL. * \param additional Additional data to update. Can be \c NULL, in which
* \param add_len The length of the additional data. * case the additional data is empty regardless of
* the value of \p add_len.
* \param add_len The length of the additional data
* if \p additional is not \c NULL.
* This must be less than #MBEDTLS_CTR_DRBG_MAX_INPUT
* and less than
* #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT - \c entropy_len
* where \c entropy_len is the entropy length
* configured for the context.
* *
* \return \c 0 on success, or * \return \c 0 on success.
* #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
* #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure. * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
*/ */
int mbedtls_ctr_drbg_random_with_add( void *p_rng, int mbedtls_ctr_drbg_random_with_add( void *p_rng,
@ -289,15 +319,17 @@ int mbedtls_ctr_drbg_random_with_add( void *p_rng,
/** /**
* \brief This function uses CTR_DRBG to generate random data. * \brief This function uses CTR_DRBG to generate random data.
* *
* \note The function automatically reseeds if the reseed counter is exceeded. * This function automatically reseeds if the reseed counter is exceeded
* or prediction resistance is enabled.
*
* *
* \param p_rng The CTR_DRBG context. This must be a pointer to a * \param p_rng The CTR_DRBG context. This must be a pointer to a
* #mbedtls_ctr_drbg_context structure. * #mbedtls_ctr_drbg_context structure.
* \param output The buffer to fill. * \param output The buffer to fill.
* \param output_len The length of the buffer. * \param output_len The length of the buffer in bytes.
* *
* \return \c 0 on success, or * \return \c 0 on success.
* #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
* #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure. * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
*/ */
int mbedtls_ctr_drbg_random( void *p_rng, int mbedtls_ctr_drbg_random( void *p_rng,
@ -310,9 +342,9 @@ int mbedtls_ctr_drbg_random( void *p_rng,
* \param ctx The CTR_DRBG context. * \param ctx The CTR_DRBG context.
* \param path The name of the file. * \param path The name of the file.
* *
* \return \c 0 on success, * \return \c 0 on success.
* #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, or * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
* #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on reseed
* failure. * failure.
*/ */
int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path ); int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
@ -324,10 +356,12 @@ int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char
* \param ctx The CTR_DRBG context. * \param ctx The CTR_DRBG context.
* \param path The name of the file. * \param path The name of the file.
* *
* \return \c 0 on success, * \return \c 0 on success.
* #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
* #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on
* #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG on failure. * reseed failure.
* \return #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if the existing
* seed file is too large.
*/ */
int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path ); int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
#endif /* MBEDTLS_FS_IO */ #endif /* MBEDTLS_FS_IO */