From 60b25f05294d773d8c1f6cc22bda684a4f78b69f Mon Sep 17 00:00:00 2001 From: Unknown Date: Tue, 6 Feb 2018 03:17:59 -0500 Subject: [PATCH] Documentation fixes Added more elaborate comments and descriptions --- include/mbedtls/ecdsa.h | 14 ++++++----- include/mbedtls/pk.h | 44 ++++++++++++++++++++--------------- include/mbedtls/pk_info.h | 29 ++++++++++++++--------- include/mbedtls/pk_internal.h | 5 +++- 4 files changed, 55 insertions(+), 37 deletions(-) diff --git a/include/mbedtls/ecdsa.h b/include/mbedtls/ecdsa.h index c0088db5e..7490c6596 100644 --- a/include/mbedtls/ecdsa.h +++ b/include/mbedtls/ecdsa.h @@ -52,6 +52,10 @@ * this is a problem, call the function * mbedtls_ecdsa_max_sig_len instead. */ +#if MBEDTLS_ECP_MAX_BYTES > 124 +#error "MBEDTLS_ECP_MAX_BYTES bigger than expected, please fix MBEDTLS_ECDSA_MAX_LEN" +#endif + #define MBEDTLS_ECDSA_MAX_SIG_LEN( bits ) \ ( /*T,L of SEQUENCE*/ ( ( bits ) >= 61 * 8 ? 3 : 2 ) + \ /*T,L of r,s*/ 2 * ( ( ( bits ) >= 127 * 8 ? 3 : 2 ) + \ @@ -71,12 +75,9 @@ static inline size_t mbedtls_ecdsa_max_sig_len( size_t bits ) return( MBEDTLS_ECDSA_MAX_SIG_LEN( bits ) ); } -#if MBEDTLS_ECP_MAX_BYTES > 124 -#error "MBEDTLS_ECP_MAX_BYTES bigger than expected, please fix MBEDTLS_ECDSA_MAX_LEN" -#endif /** Maximum size of an ECDSA signature in bytes */ -#define MBEDTLS_ECDSA_MAX_LEN ( 3 + 2 * ( 3 + MBEDTLS_ECP_MAX_BYTES ) ) - +#define MBEDTLS_ECDSA_MAX_LEN (MBEDTLS_ECDSA_MAX_SIG_LEN( \ + 8 * MBEDTLS_ECP_MAX_BYTES ) ) /** * \brief ECDSA context structure */ @@ -236,7 +237,8 @@ int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx, #endif /* MBEDTLS_ECDSA_DETERMINISTIC */ /** - * \brief Convert a signature from numbers to ASN.1 + * \brief Convert a signature from numbers to ASN.1 INTEGER's, + * then both packed together as parts of an ASN.1 SEQUENCE * * \param r First number of the signature * \param s Second number of the signature diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h index c6bb7c490..f7fa4d31a 100644 --- a/include/mbedtls/pk.h +++ b/include/mbedtls/pk.h @@ -3,7 +3,7 @@ * * \brief Public Key cryptography abstraction layer * - * Copyright (C) 2006-2017, ARM Limited, All Rights Reserved + * Copyright (C) 2006-2018, ARM Limited, All Rights Reserved * SPDX-License-Identifier: Apache-2.0 * * Licensed under the Apache License, Version 2.0 (the "License"); you may @@ -169,7 +169,7 @@ const char * mbedtls_pk_get_name( const mbedtls_pk_context *ctx ); mbedtls_pk_type_t mbedtls_pk_get_type( const mbedtls_pk_context *ctx ); /** - * \brief Merge key types with the same representation + * \brief Get the representation type associated with a given type * * \param type Any key type * \return A canonical representative among the types with the @@ -200,10 +200,10 @@ static inline mbedtls_pk_type_t mbedtls_pk_representation_type( mbedtls_pk_type_ /** * Quick access to an RSA context inside a PK context. * - * \warning You must make sure the PK context actually holds a transparent - * RSA context before using this function! This function is only valid if - * `mbedtls_pk_get_type(&pk)` is one of \c MBEDTLS_PK_RSA or - * \c MBEDTLS_PK_RSASSA_PSS. + * \warning You must either make sure the PK context actually holds a + * transparent RSA context by checking + * \c mbedtls_pk_representation_type( mbedtls_pk_get_type( &pk ) ) before using + * this function, or check that the return value is not NULL before using it. */ static inline mbedtls_rsa_context *mbedtls_pk_rsa( const mbedtls_pk_context pk ) { @@ -220,10 +220,10 @@ static inline mbedtls_rsa_context *mbedtls_pk_rsa( const mbedtls_pk_context pk ) /** * Quick access to an EC context inside a PK context. * - * \warning You must make sure the PK context actually holds a transparent - * EC context before using this function! This function is only valid if - * `mbedtls_pk_get_type(&pk)` is one of \c MBEDTLS_PK_ECKEY, - * \c MBEDTLS_PK_ECKEY_DH or \c MBEDTLS_PK_ECDSA. + * \warning You must either make sure the PK context actually holds a + * transparent RSA context by checking + * \c mbedtls_pk_representation_type( mbedtls_pk_get_type( &pk ) ) before using + * this function, or check that the return value is not NULL before using it. */ static inline mbedtls_ecp_keypair *mbedtls_pk_ec( const mbedtls_pk_context pk ) { @@ -287,11 +287,15 @@ void mbedtls_pk_free( mbedtls_pk_context *ctx ); * MBEDTLS_ERR_PK_BAD_INPUT_DATA on invalid input, * MBEDTLS_ERR_PK_ALLOC_FAILED on allocation failure. * - * \note Engines that implement of opaque keys may offer an + * \note Engines that implement opaque keys may offer an * alternative setup function that take engine-dependent * parameters. If such a function exists, call it - * instead of mbedtls_pk_setup. The implementation-specific - * setup function should call mbedtls_pk_setup internally. + * instead of mbedtls_pk_setup. A standard way of providing + * such function is by first calling the generic + * mbedtls_pk_setup function (in particular taking care of + * context allocation through ctx_alloc) and afterwards + * proceeding to initialize the implementation-specific + * context structure. * * \note For contexts holding an RSA-alt key pair, use * \c mbedtls_pk_setup_rsa_alt() instead. @@ -436,17 +440,18 @@ int mbedtls_pk_verify_ext( mbedtls_pk_type_t type, const void *options, * \param hash Hash of the message to sign * \param hash_len Hash length or 0 (see notes) * \param sig Place to write the signature - * \param sig_len Number of bytes written to sig + * \param sig_len Actual length in bytes of the created signature * \param f_rng RNG function * \param p_rng RNG parameter * * \return 0 on success, or a type-specific error code. * * \note The signature buffer \c sig must be of appropriate size - * which can be calculated with \c mbedtls_pk_signature_size. + * which can be calculated with + * \c mbedtls_pk_get_signature_size. * Depending on the algorithm, the value returned in * \c sig_len may be less or equal to the value returned by - * \c mbedtls_pk_signature_size. + * \c mbedtls_pk_get_signature_size. * * \note For RSA keys, the default padding type is PKCS#1 v1.5. * There is no interface in the PK module to make RSASSA-PSS @@ -526,11 +531,12 @@ int mbedtls_pk_encrypt( mbedtls_pk_context *ctx, * * MBEDTLS_ERR_PK_TYPE_MISMATCH if the contexts cannot * represent keys of the same type. * * MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE if it is impossible - * to determine whether the keys match. This is guaranteed - * not to happen if \c prv is a transparent key pair. + * to determine whether the keys match. This can only happen + * if \c prv is an opaque key. * * Or a type-specific error code. * - * \note Opaque key types may not implement this function. + * \note Opaque key types may omit implementing this function + * by providing a NULL pointer in the mbedtls_pk_info_t structure. * An opaque \c pub never matches a transparent \c prv. */ int mbedtls_pk_check_pair( const mbedtls_pk_context *pub, const mbedtls_pk_context *prv ); diff --git a/include/mbedtls/pk_info.h b/include/mbedtls/pk_info.h index a808c2cab..d1d95ef4f 100644 --- a/include/mbedtls/pk_info.h +++ b/include/mbedtls/pk_info.h @@ -3,7 +3,10 @@ * * \brief Public Key cryptography abstraction layer: object interface * - * Copyright (C) 2006-2017, ARM Limited, All Rights Reserved + * This file contains the info structure interface used by developers to + * provide engine-specific implementations of opaque key handling functions. + * + * Copyright (C) 2006-2018, ARM Limited, All Rights Reserved * SPDX-License-Identifier: Apache-2.0 * * Licensed under the Apache License, Version 2.0 (the "License"); you may @@ -40,10 +43,16 @@ extern "C" { * Methods that opaque key pair objects must implement. * * Engines that interface with external cryptographic processors must - * implement this interface. Platform-specific hardware accelerators - * that can be used for all keys of a given type should use alternative - * ("xxx_alt") interfaces instead. This interface allows using different - * engines for each key. + * implement this interface. It allows using different engines for each key. + * Platform-specific hardware accelerators that can be used for all keys of + * a given type should not use this interface, but rather provide an + * alternative implementation of the respective cryptographic module - for + * example to use an RSA accelerator you can define MBEDTLS_RSA_ALT, and + * provide your own implementation of the RSA module. + * + * \warning: If you are using the PK interface to perform operations on + * keys, call the functions in pk.h. The interface in this file should only + * be used by implementers of opaque key engines. * * An engine for asymmetric cryptography must implement the interface * described in this structure. The interface for the engine may be @@ -68,14 +77,11 @@ extern "C" { * in the corresponding field. The corresponding function in pk.h will * return MBEDTLS_ERR_PK_TYPE_MISMATCH in this case. * - * \note If you are using the PK interface to perform operations on - * keys, call the functions in pk.h. The interface in this file should only - * be used by implementers of opaque key engines. * * \warning: Do not declare this structure directly! It may be extended in * future* versions of Mbed TLS. Call the macro - * MBEDTLS_PK_OPAQUE_INFO_1() or MBEDTLS_PK_OPAQUE_INFO_ASYNC_1() instead. - * These macros are guaranteed to take parameters with the same type + * MBEDTLS_PK_OPAQUE_INFO_1() instead. + * This macro is guaranteed to take parameters with the same type * and semantics as previous versions and fill any new field of the * structure with sensible values. */ @@ -105,7 +111,8 @@ struct mbedtls_pk_info_t * This function cannot fail. */ size_t (*get_bitlen)( const void *ctx ); - /** Tell if the context implements this type (e.g.\ ECKEY can do ECDSA). + /** Tell if the context implements the algorithm specified by + * the provided type (e.g.\ ECKEY can do ECDSA). * * mbedtls_pk_can_do() calls this function. * diff --git a/include/mbedtls/pk_internal.h b/include/mbedtls/pk_internal.h index 06475e948..0a330876e 100644 --- a/include/mbedtls/pk_internal.h +++ b/include/mbedtls/pk_internal.h @@ -3,7 +3,10 @@ * * \brief Public Key cryptography abstraction layer: built-in key types * - * Copyright (C) 2006-2017, ARM Limited, All Rights Reserved + * This file contains built-in types for handling various key types using + * the interface defined in pk_info.h. + * + * Copyright (C) 2006-2018, ARM Limited, All Rights Reserved * SPDX-License-Identifier: Apache-2.0 * * Licensed under the Apache License, Version 2.0 (the "License"); you may