From c9474ebdbb4e42d2411220cf3a50306703be5e0d Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Tue, 27 Mar 2018 10:58:22 +0100 Subject: [PATCH 1/2] Update ctr_drbg.h Minor documentation improvements: *Standardized file brief description. *Separated return statements. *Reordered tags within documentation blocks so that params and returns are last in block. *Suggest to specify issue for each return code, where multiple failure return codes are listed. --- include/mbedtls/ctr_drbg.h | 53 +++++++++++++++++++++----------------- 1 file changed, 29 insertions(+), 24 deletions(-) diff --git a/include/mbedtls/ctr_drbg.h b/include/mbedtls/ctr_drbg.h index 121575a51..5f611dd01 100644 --- a/include/mbedtls/ctr_drbg.h +++ b/include/mbedtls/ctr_drbg.h @@ -1,9 +1,11 @@ /** * \file ctr_drbg.h * - * \brief CTR_DRBG is based on AES-256, as defined in NIST SP 800-90A: - * Recommendation for Random Number Generation Using Deterministic - * Random Bit Generators. + * \brief This file contains CTR_DRBG definitions and functions. + * + * CTR_DRBG is based on AES-256, as defined in NIST SP 800-90A: + * Recommendation for Random Number Generation Using Deterministic + * Random Bit Generators. * */ /* @@ -156,8 +158,8 @@ void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx ); identifiers. Can be NULL. * \param len The length of the personalization data. * - * \return \c 0 on success, or - * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure. */ int mbedtls_ctr_drbg_seed( mbedtls_ctr_drbg_context *ctx, int (*f_entropy)(void *, unsigned char *, size_t), @@ -216,22 +218,24 @@ void mbedtls_ctr_drbg_set_reseed_interval( mbedtls_ctr_drbg_context *ctx, * \param additional Additional data to add to the state. Can be NULL. * \param len The length of the additional data. * - * \return \c 0 on success, or - * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure. */ int mbedtls_ctr_drbg_reseed( mbedtls_ctr_drbg_context *ctx, const unsigned char *additional, size_t len ); /** - * \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 additional The data to update the state with. - * \param add_len Length of \p additional data. + * \note If \p add_len is greater than + * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT, only the first + * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT Bytes are used. + * The remaining Bytes are silently discarded. + * + * \param ctx The CTR_DRBG context. + * \param additional The data to update the state with. + * \param add_len Length of \p additional data. * - * \note If \p add_len is greater than #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT, - * only the first #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT Bytes are used. - * The remaining Bytes are silently discarded. */ void mbedtls_ctr_drbg_update( mbedtls_ctr_drbg_context *ctx, const unsigned char *additional, size_t add_len ); @@ -249,8 +253,8 @@ void mbedtls_ctr_drbg_update( mbedtls_ctr_drbg_context *ctx, * \param additional Additional data to update. Can be NULL. * \param add_len The length of the additional data. * - * \return \c 0 on success, or - * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or + * \return \c 0 on success. + * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure. */ int mbedtls_ctr_drbg_random_with_add( void *p_rng, @@ -267,8 +271,8 @@ int mbedtls_ctr_drbg_random_with_add( void *p_rng, * \param output The buffer to fill. * \param output_len The length of the buffer. * - * \return \c 0 on success, or - * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or + * \return \c 0 on success. + * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure. */ int mbedtls_ctr_drbg_random( void *p_rng, @@ -281,8 +285,8 @@ int mbedtls_ctr_drbg_random( void *p_rng, * \param ctx The CTR_DRBG context. * \param path The name of the file. * - * \return \c 0 on success, - * #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, or + * \return \c 0 on success. + * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, or * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on * failure. */ @@ -295,9 +299,9 @@ int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char * \param ctx The CTR_DRBG context. * \param path The name of the file. * - * \return \c 0 on success, - * #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, - * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or + * \return \c 0 on success. + * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error. + * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or * #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG on failure. */ int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path ); @@ -306,7 +310,8 @@ int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char /** * \brief The CTR_DRBG checkup routine. * - * \return \c 0 on success, or \c 1 on failure. + * \return \c 0 on success. + * \return \c 1 on failure. */ int mbedtls_ctr_drbg_self_test( int verbose ); From f25eb6eef6b53db98b6afa5f4b8463f27c200a48 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Mon, 16 Apr 2018 14:51:52 +0100 Subject: [PATCH 2/2] Update ctr_drbg.h minor changes based on comments --- include/mbedtls/ctr_drbg.h | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/include/mbedtls/ctr_drbg.h b/include/mbedtls/ctr_drbg.h index 5f611dd01..dcbc04792 100644 --- a/include/mbedtls/ctr_drbg.h +++ b/include/mbedtls/ctr_drbg.h @@ -3,10 +3,13 @@ * * \brief This file contains CTR_DRBG definitions and functions. * - * CTR_DRBG is based on AES-256, as defined in NIST SP 800-90A: - * Recommendation for Random Number Generation Using Deterministic - * Random Bit Generators. + * CTR_DRBG is a standardized way of building a PRNG from a block-cipher + * in counter mode operation, as defined in NIST SP 800-90A: + * Recommendation for Random Number Generation Using Deterministic Random + * Bit Generators. * + * The Mbed TLS implementation of CTR_DRBG uses AES-256 as the underlying + * block cipher. */ /* * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved @@ -286,8 +289,8 @@ int mbedtls_ctr_drbg_random( void *p_rng, * \param path The name of the file. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, or - * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on + * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error. + * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on * failure. */ int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );