From 0044ab12b7099457a24930aa80bd85d9724431dc Mon Sep 17 00:00:00 2001 From: Andrzej Kurek Date: Tue, 20 Feb 2018 11:18:21 -0500 Subject: [PATCH] Documentation fixes Correct indentation, brackets, and comments. --- include/mbedtls/ecdsa.h | 2 +- include/mbedtls/pk.h | 30 +++++++++--------- include/mbedtls/pk_info.h | 24 ++++++--------- library/ecdsa.c | 8 +++-- tests/suites/test_suite_ecp.function | 5 +-- tests/suites/test_suite_pk.data | 2 +- tests/suites/test_suite_pk.function | 46 ++++++++++++++-------------- 7 files changed, 58 insertions(+), 59 deletions(-) diff --git a/include/mbedtls/ecdsa.h b/include/mbedtls/ecdsa.h index ba7aba1e3..f99147034 100644 --- a/include/mbedtls/ecdsa.h +++ b/include/mbedtls/ecdsa.h @@ -213,7 +213,7 @@ int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp, * \param f_rng The RNG function. * \param p_rng The RNG parameter. * - * \note The signature \p sig is expected to be ASN.1 SEQUENCE + * \note The signature \p sig is expected to in be ASN.1 SEQUENCE * format, as described in Standards for Efficient * Cryptography Group (SECG): SEC1 Elliptic Curve * Cryptography, section C.5. diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h index d712e7750..0e923779f 100644 --- a/include/mbedtls/pk.h +++ b/include/mbedtls/pk.h @@ -54,10 +54,10 @@ /**@{*/ #define MBEDTLS_ERR_PK_ALLOC_FAILED -0x3F80 /**< Memory allocation failed. */ -#define MBEDTLS_ERR_PK_TYPE_MISMATCH -0x3F00 /**< Type mismatch, eg attempt to encrypt with an ECDSA key */ +#define MBEDTLS_ERR_PK_TYPE_MISMATCH -0x3F00 /**< Type mismatch, eg attempt to encrypt with an ECDSA key. */ #define MBEDTLS_ERR_PK_BAD_INPUT_DATA -0x3E80 /**< Bad input parameters to function. */ #define MBEDTLS_ERR_PK_FILE_IO_ERROR -0x3E00 /**< Read/write of file failed. */ -#define MBEDTLS_ERR_PK_KEY_INVALID_VERSION -0x3D80 /**< Unsupported key version */ +#define MBEDTLS_ERR_PK_KEY_INVALID_VERSION -0x3D80 /**< Unsupported key version. */ #define MBEDTLS_ERR_PK_KEY_INVALID_FORMAT -0x3D00 /**< Invalid key tag or value. */ #define MBEDTLS_ERR_PK_UNKNOWN_PK_ALG -0x3C80 /**< Key algorithm is unsupported (only RSA and EC are supported). */ #define MBEDTLS_ERR_PK_PASSWORD_REQUIRED -0x3C00 /**< Private key password can't be empty. */ @@ -68,9 +68,9 @@ #define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE -0x3980 /**< Unavailable feature, e.g. RSA disabled for RSA key. */ #define MBEDTLS_ERR_PK_SIG_LEN_MISMATCH -0x3900 /**< The signature is valid but its length is less than expected. */ #define MBEDTLS_ERR_PK_HW_ACCEL_FAILED -0x3880 /**< PK hardware accelerator failed. */ -#define MBEDTLS_ERR_PK_INVALID_SIGNATURE -0x3800 /**< Invalid signature */ -#define MBEDTLS_ERR_PK_BUFFER_TOO_SMALL -0x3780 /**< Output buffer too small */ -#define MBEDTLS_ERR_PK_NOT_PERMITTED -0x3700 /**< Operation not permitted */ +#define MBEDTLS_ERR_PK_INVALID_SIGNATURE -0x3800 /**< Invalid signature. */ +#define MBEDTLS_ERR_PK_BUFFER_TOO_SMALL -0x3780 /**< Output buffer too small. */ +#define MBEDTLS_ERR_PK_NOT_PERMITTED -0x3700 /**< Operation not permitted. */ /**@}*/ @@ -88,14 +88,14 @@ extern "C" { * unrecognized type. Call \c mbedtls_pk_can_do() to check * whether a key is of a recognized type. */ typedef enum { - MBEDTLS_PK_NONE=0, /**< Unused context object */ - MBEDTLS_PK_RSA, /**< RSA key pair (normal software implementation) with PKCS#1 v1.5 or PSS context */ - MBEDTLS_PK_ECKEY, /**< Generic ECC key pair */ - MBEDTLS_PK_ECKEY_DH, /**< ECC key pair restricted to key exchanges */ - MBEDTLS_PK_ECDSA, /**< ECC key pair restricted to signature/verification */ - MBEDTLS_PK_RSA_ALT, /**< RSA (alternative implementation) */ - MBEDTLS_PK_RSASSA_PSS, /**< RSA key pair; same context as MBEDTLS_PK_RSA, but used to represent keys with the algorithm identifier id-RSASSA-PSS */ - MBEDTLS_PK_OPAQUE, /**< Opaque key pair (cryptographic material held in an external module).*/ + MBEDTLS_PK_NONE=0, /**< Unused context object. */ + MBEDTLS_PK_RSA, /**< RSA key pair (normal software implementation) with PKCS#1 v1.5 or PSS context. */ + MBEDTLS_PK_ECKEY, /**< Generic ECC key pair. */ + MBEDTLS_PK_ECKEY_DH, /**< ECC key pair restricted to key exchanges. */ + MBEDTLS_PK_ECDSA, /**< ECC key pair restricted to signature/verification. */ + MBEDTLS_PK_RSA_ALT, /**< RSA (alternative implementation). */ + MBEDTLS_PK_RSASSA_PSS, /**< RSA key pair; same context as MBEDTLS_PK_RSA, but used to represent keys with the algorithm identifier id-RSASSA-PSS. */ + MBEDTLS_PK_OPAQUE, /**< Opaque key pair (cryptographic material held in an external module). */ } mbedtls_pk_type_t; /** @@ -154,7 +154,7 @@ typedef struct } mbedtls_pk_context; /** - * \brief Access the type name + * \brief Get the key type name of a PK context. * * \param ctx Context to use * @@ -163,7 +163,7 @@ typedef struct const char * mbedtls_pk_get_name( const mbedtls_pk_context *ctx ); /** - * \brief Get the key type + * \brief Get the key type of a PK context. * * \param ctx Context to use * diff --git a/include/mbedtls/pk_info.h b/include/mbedtls/pk_info.h index 6ee47d866..6e6fd4720 100644 --- a/include/mbedtls/pk_info.h +++ b/include/mbedtls/pk_info.h @@ -3,7 +3,7 @@ * * \brief Public Key cryptography abstraction layer: engine interface * - * This file defines the interface the public-key cryptography engines + * This file defines the interface which public-key cryptography engines * (PK engines) must implement. A PK engine defines how a public-private * key pair is represented and how to perform cryptographic operations * with it. Mbed TLS contains built-in PK engines implemented either @@ -135,7 +135,7 @@ struct mbedtls_pk_info_t * In case of an error, or an unsupported key type, 0 should be returned. * * Opaque implementations may omit this method if they do not support - * signature. */ + * signing. */ size_t (*signature_size_func)( const void *ctx ); /** Verify signature @@ -239,8 +239,7 @@ struct mbedtls_pk_info_t * #MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE. * * Alternatively, check_pair_func may return another PK, RSA or ECP error - * code if applicable. - * */ + * code if applicable. */ int (*check_pair_func)( const mbedtls_pk_context *pub, const mbedtls_pk_context *prv ); /** Allocate a new context @@ -248,7 +247,7 @@ struct mbedtls_pk_info_t * mbedtls_pk_setup() calls this function. * * If this function returns NULL, the allocation is considered to - * have failed and the the object remains uninitialized. + * have failed and the object remains uninitialized. * * Opaque implementations may omit this method. In this case, * mbedtls_pk_setup() will set the \c pk_ctx field of the @@ -261,9 +260,8 @@ struct mbedtls_pk_info_t /** Free the given context * * mbedtls_pk_free() calls this function. It must free the data allocated - * by \b ctx_alloc_func as well as any other resource that belongs to - * the object. - * */ + * by \c ctx_alloc_func as well as any other resource that belongs to + * the object. */ void (*ctx_free_func)( void *ctx ); /** Interface with the debug module @@ -276,10 +274,10 @@ struct mbedtls_pk_info_t }; /** - * Methods that opaque key pair objects must implement. - * * \brief Initializer for opaque key engines * + * Methods that opaque key pair objects must implement. + * * The value of this macro is a suitable initializer for an object of type * mbedtls_pk_info_t. It is guaranteed to remain so in future versions of the * library, even if the type mbedtls_pk_info_t changes. @@ -288,7 +286,7 @@ struct mbedtls_pk_info_t * parameters are constant. * * \param name For transparent keys, this reflects the key type. For opaque - * keys, this reflects the cryptographic module driver. + * keys, this reflects the cryptographic module driver. * \param get_bitlen \ref mbedtls_pk_info_t.get_bitlen method * \param can_do \ref mbedtls_pk_info_t.can_do method * \param signature_size_func \ref mbedtls_pk_info_t.signature_size_func method @@ -302,9 +300,7 @@ struct mbedtls_pk_info_t * \param debug_func \ref mbedtls_pk_info_t.debug_func method * * \return Initializer for an object of type mbedtls_pk_info_t with the - * specified field values - * - * */ + * specified field values */ #define MBEDTLS_PK_OPAQUE_INFO_1( \ name \ , get_bitlen \ diff --git a/library/ecdsa.c b/library/ecdsa.c index 53011d450..ed4268dde 100644 --- a/library/ecdsa.c +++ b/library/ecdsa.c @@ -288,8 +288,8 @@ cleanup: /* * Convert a signature (given by context) to ASN.1. - * This function may leave a half-written upon encountering an error, and - * is for internal use only. + * This function is for internal use only. Upon an error, it may leave + * the signature buffer partially written. */ static int internal_ecdsa_signature_to_asn1( const mbedtls_mpi *r, const mbedtls_mpi *s, unsigned char *sig, @@ -314,7 +314,8 @@ static int internal_ecdsa_signature_to_asn1( const mbedtls_mpi *r, } /* - * Convert a signature (given by context) to ASN.1, zeroize the buffer on error + * Convert a signature from number pair format to ASN.1. + * Zeroize the buffer on error. */ int mbedtls_ecdsa_signature_to_asn1( const mbedtls_mpi *r, const mbedtls_mpi *s, unsigned char *sig, size_t *slen, size_t ssize ) @@ -327,6 +328,7 @@ int mbedtls_ecdsa_signature_to_asn1( const mbedtls_mpi *r, const mbedtls_mpi *s, /* * Compute and write signature. This function assumes that sig is large enough. + * Refer to MBEDTLS_ECDSA_MAX_SIG_LEN for the signature size. */ int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hlen, diff --git a/tests/suites/test_suite_ecp.function b/tests/suites/test_suite_ecp.function index 120025f1c..feab0f7de 100644 --- a/tests/suites/test_suite_ecp.function +++ b/tests/suites/test_suite_ecp.function @@ -467,10 +467,11 @@ void ecp_ansi_write_point( char *key_file, int format, char *good_hex ) MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL ); exit: - if( ret >= 0 ) { + if( ret >= 0 ) + { unsigned char out[999] = {0}; hexify( out, tested_buf, ret ); - printf("== %s ==\n", out); + printf( "== %s ==\n", out ); } mbedtls_pk_free( &pk ); } diff --git a/tests/suites/test_suite_pk.data b/tests/suites/test_suite_pk.data index 67b44194c..657fdf210 100644 --- a/tests/suites/test_suite_pk.data +++ b/tests/suites/test_suite_pk.data @@ -169,4 +169,4 @@ pk_opaque_minimal: #PK opaque wrapper (RSA) #depends_on:MBEDTLS_RSA_C #pk_opaque_wrapper: -# \ No newline at end of file +# diff --git a/tests/suites/test_suite_pk.function b/tests/suites/test_suite_pk.function index 25c46b217..c190b12ab 100644 --- a/tests/suites/test_suite_pk.function +++ b/tests/suites/test_suite_pk.function @@ -86,11 +86,11 @@ static void pk_rsa_match( mbedtls_rsa_context *raw, unsigned char msg[50], ciph[1000], test[1000]; size_t sig_len, ciph_len, test_len; - memset( hash, 0x2a, sizeof hash ); - memset( sig, 0, sizeof sig ); - memset( msg, 0x2a, sizeof msg ); - memset( ciph, 0, sizeof ciph ); - memset( test, 0, sizeof test ); + memset( hash, 0x2a, sizeof( hash ) ); + memset( sig, 0, sizeof( sig ) ); + memset( msg, 0x2a, sizeof( msg ) ); + memset( ciph, 0, sizeof( ciph ) ); + memset( test, 0, sizeof( test ) ); /* Initialize basic PK RSA context with raw key */ mbedtls_pk_init( &basic_ctx ); @@ -105,7 +105,7 @@ static void pk_rsa_match( mbedtls_rsa_context *raw, TEST_ASSERT( mbedtls_pk_get_signature_size( tested_ctx ) == RSA_KEY_LEN ); /* Test signature */ - TEST_ASSERT( mbedtls_pk_sign( tested_ctx, MBEDTLS_MD_NONE, hash, sizeof hash, + TEST_ASSERT( mbedtls_pk_sign( tested_ctx, MBEDTLS_MD_NONE, hash, sizeof( hash ), sig, &sig_len, rnd_std_rand, NULL ) == sign_ret ); if( sign_ret == 0 ) { @@ -116,46 +116,46 @@ static void pk_rsa_match( mbedtls_rsa_context *raw, #endif /* MBEDTLS_HAVE_INT64 */ TEST_ASSERT( sig_len == RSA_KEY_LEN ); TEST_ASSERT( mbedtls_pk_verify( &basic_ctx, MBEDTLS_MD_NONE, - hash, sizeof hash, sig, sig_len ) == 0 ); + hash, sizeof( hash ), sig, sig_len ) == 0 ); } /* Test verification */ - TEST_ASSERT( mbedtls_pk_sign( &basic_ctx, MBEDTLS_MD_NONE, hash, sizeof hash, + TEST_ASSERT( mbedtls_pk_sign( &basic_ctx, MBEDTLS_MD_NONE, hash, sizeof( hash ), sig, &sig_len, rnd_std_rand, NULL ) == 0 ); TEST_ASSERT( mbedtls_pk_verify( tested_ctx, MBEDTLS_MD_NONE, - hash, sizeof hash, sig, sig_len ) == verify_ret ); + hash, sizeof( hash ), sig, sig_len ) == verify_ret ); if( verify_ret == 0 ) { TEST_ASSERT( mbedtls_pk_verify( tested_ctx, MBEDTLS_MD_NONE, - hash, sizeof hash, sig, sig_len - 1 ) == MBEDTLS_ERR_RSA_VERIFY_FAILED ); + hash, sizeof( hash ), sig, sig_len - 1 ) == MBEDTLS_ERR_RSA_VERIFY_FAILED ); sig[sig_len-1] ^= 1; TEST_ASSERT( mbedtls_pk_verify( tested_ctx, MBEDTLS_MD_NONE, - hash, sizeof hash, sig, sig_len ) == MBEDTLS_ERR_RSA_INVALID_PADDING ); + hash, sizeof( hash ), sig, sig_len ) == MBEDTLS_ERR_RSA_INVALID_PADDING ); } /* Test encryption */ - TEST_ASSERT( mbedtls_pk_encrypt( tested_ctx, msg, sizeof msg, - ciph, &ciph_len, sizeof ciph, + TEST_ASSERT( mbedtls_pk_encrypt( tested_ctx, msg, sizeof( msg ), + ciph, &ciph_len, sizeof( ciph ), rnd_std_rand, NULL ) == encrypt_ret ); if( encrypt_ret == 0 ) { TEST_ASSERT( mbedtls_pk_decrypt( &basic_ctx, ciph, ciph_len, - test, &test_len, sizeof test, + test, &test_len, sizeof( test ), rnd_std_rand, NULL ) == 0 ); - TEST_ASSERT( test_len == sizeof msg ); + TEST_ASSERT( test_len == sizeof( msg ) ); TEST_ASSERT( memcmp( test, msg, test_len ) == 0 ); } /* Test decryption */ - TEST_ASSERT( mbedtls_pk_encrypt( &basic_ctx, msg, sizeof msg, - ciph, &ciph_len, sizeof ciph, + TEST_ASSERT( mbedtls_pk_encrypt( &basic_ctx, msg, sizeof( msg ), + ciph, &ciph_len, sizeof( ciph ), rnd_std_rand, NULL ) == 0 ); TEST_ASSERT( mbedtls_pk_decrypt( tested_ctx, ciph, ciph_len, - test, &test_len, sizeof test, + test, &test_len, sizeof( test ), rnd_std_rand, NULL ) == decrypt_ret ); if( decrypt_ret == 0 ) { - TEST_ASSERT( test_len == sizeof msg ); + TEST_ASSERT( test_len == sizeof( msg ) ); TEST_ASSERT( memcmp( test, msg, test_len ) == 0 ); } @@ -525,19 +525,19 @@ void pk_sign_verify( int type, int sign_ret, int verify_ret ) mbedtls_pk_init( &pk ); - memset( hash, 0x2a, sizeof hash ); - memset( sig, 0, sizeof sig ); + memset( hash, 0x2a, sizeof( hash ) ); + memset( sig, 0, sizeof( sig ) ); TEST_ASSERT( mbedtls_pk_setup( &pk, mbedtls_pk_info_from_type( type ) ) == 0 ); TEST_ASSERT( pk_genkey( &pk ) == 0 ); - TEST_ASSERT( mbedtls_pk_sign( &pk, MBEDTLS_MD_SHA256, hash, sizeof hash, + TEST_ASSERT( mbedtls_pk_sign( &pk, MBEDTLS_MD_SHA256, hash, sizeof( hash ), sig, &sig_len, rnd_std_rand, NULL ) == sign_ret ); if( sign_ret == 0 ) TEST_ASSERT( sig_len <= mbedtls_pk_get_signature_size( &pk ) ); TEST_ASSERT( mbedtls_pk_verify( &pk, MBEDTLS_MD_SHA256, - hash, sizeof hash, sig, sig_len ) == verify_ret ); + hash, sizeof( hash ), sig, sig_len ) == verify_ret ); exit: mbedtls_pk_free( &pk );