yuzu-emu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2024-12-02 00:34:22 +01:00
Code Issues Packages Projects Releases Wiki Activity

Documentation fixes

Browse Source 
Fix spacing, comments, and links in doxygen documentation.
This commit is contained in:
Andrzej Kurek 2018-02-14 07:16:27 -05:00
parent 024ab067cd
commit bba0927586
7 changed files with 145 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
include/mbedtls/ecdsa.h
View File

@ -83,8 +83,8 @@ static inline size_t mbedtls_ecdsa_max_sig_len( size_t bits )
} }
/** The maximal size of an ECDSA signature in Bytes. */ /** The maximal size of an ECDSA signature in Bytes. */
#define MBEDTLS_ECDSA_MAX_LEN (MBEDTLS_ECDSA_MAX_SIG_LEN( \ #define MBEDTLS_ECDSA_MAX_LEN \
8 * MBEDTLS_ECP_MAX_BYTES ) ) ( MBEDTLS_ECDSA_MAX_SIG_LEN( 8 * MBEDTLS_ECP_MAX_BYTES ) )
/** /**
* \brief The ECDSA context structure. * \brief The ECDSA context structure.
@ -97,7 +97,10 @@ extern "C" {
/** /**
* \brief This function computes the ECDSA signature of a * \brief This function computes the ECDSA signature of a
* previously-hashed message. * previously-hashed message. The signature is in
* ASN.1 SEQUENCE format, as described in <em>Standards
* for Efficient Cryptography Group (SECG): SEC1 Elliptic
* Curve Cryptography</em>, section C.5.
* *
* \note The deterministic version is usually preferred. * \note The deterministic version is usually preferred.
* *
@ -210,10 +213,13 @@ int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
* \param f_rng The RNG function. * \param f_rng The RNG function.
* \param p_rng The RNG parameter. * \param p_rng The RNG parameter.
* *
* \note The \p sig buffer must be at least twice as large as the * \note The signature \p sig is expected to be ASN.1 SEQUENCE
* size of the curve used, plus 9. For example, 73 Bytes if * format, as described in <em>Standards for Efficient
* a 256-bit curve is used. A buffer length of * Cryptography Group (SECG): SEC1 Elliptic Curve
* #MBEDTLS_ECDSA_MAX_LEN is always safe. * Cryptography</em>, section C.5.
*
* \note A \p sig buffer length of #MBEDTLS_ECDSA_MAX_LEN is
* always safe.
* *
* \note If the bitlength of the message hash is larger than the * \note If the bitlength of the message hash is larger than the
* bitlength of the group order, then the hash is truncated as * bitlength of the group order, then the hash is truncated as
@ -297,14 +303,16 @@ int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx,
* \param ssize Size of the sig buffer * \param ssize Size of the sig buffer
* *
* \note The size of the buffer \c ssize should be at least * \note The size of the buffer \c ssize should be at least
* `MBEDTLS_ECDSA_MAX_SIG_LEN(grp->pbits)` bytes long if * `MBEDTLS_ECDSA_MAX_SIG_LEN(grp->pbits)` bytes long if the
* the signature was produced from curve \c grp, * signature was produced from curve \c grp, otherwise
* otherwise this function will return an error. * this function may fail with the error
* MBEDTLS_ERR_ASN1_BUF_TOO_SMALL.
* The output ASN.1 SEQUENCE format is as follows: * The output ASN.1 SEQUENCE format is as follows:
* Ecdsa-Sig-Value ::= SEQUENCE { * Ecdsa-Sig-Value ::= SEQUENCE {
* r INTEGER, * r INTEGER,
* s INTEGER * s INTEGER
* } * }
* This format is expected by \c mbedtls_ecdsa_verify.
* *
* \return 0 if successful, * \return 0 if successful,
* or a MBEDTLS_ERR_MPI_XXX or MBEDTLS_ERR_ASN1_XXX error code * or a MBEDTLS_ERR_MPI_XXX or MBEDTLS_ERR_ASN1_XXX error code

3
include/mbedtls/ecp.h
View File

@ -542,7 +542,8 @@ int mbedtls_ecp_ansi_write_group( const mbedtls_ecp_group *grp,
* \param format Point format, should be a MBEDTLS_ECP_PF_XXX macro * \param format Point format, should be a MBEDTLS_ECP_PF_XXX macro
* \param p Buffer to write to * \param p Buffer to write to
* \param size Buffer size * \param size Buffer size
* \param olen Number of bytes written to \c buf * \param olen Number of bytes written to \c buf on success,
* unspecified on failure.
* *
* \return 0 on success * \return 0 on success
* or \c MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL * or \c MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL

43
include/mbedtls/pk.h
View File

@ -2,7 +2,8 @@
* \file pk.h * \file pk.h
* *
* \brief Public Key cryptography abstraction layer * \brief Public Key cryptography abstraction layer
* */
/*
* Copyright (C) 2006-2018, ARM Limited, All Rights Reserved * Copyright (C) 2006-2018, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
@ -89,9 +90,9 @@ extern "C" {
typedef enum { typedef enum {
MBEDTLS_PK_NONE=0, /**< Unused context object */ 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_RSA, /**< RSA key pair (normal software implementation) with PKCS#1 v1.5 or PSS context */
MBEDTLS_PK_ECKEY, /**< ECC key pair with ECDSA context */ MBEDTLS_PK_ECKEY, /**< Generic ECC key pair */
MBEDTLS_PK_ECKEY_DH, /**< ECC key pair with ECDH context */ MBEDTLS_PK_ECKEY_DH, /**< ECC key pair restricted to key exchanges */
MBEDTLS_PK_ECDSA, /**< ECC key pair with ECDSA context */ MBEDTLS_PK_ECDSA, /**< ECC key pair restricted to signature/verification */
MBEDTLS_PK_RSA_ALT, /**< RSA (alternative implementation) */ 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_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_OPAQUE, /**< Opaque key pair (cryptographic material held in an external module).*/
@ -137,7 +138,14 @@ typedef struct
typedef struct mbedtls_pk_info_t mbedtls_pk_info_t; typedef struct mbedtls_pk_info_t mbedtls_pk_info_t;
/** /**
* \brief Key pair container * \brief Context structure for public-key cryptographic operations.
*
* \note This structure contains all the information needed for
* performing a public-key cryptography operation. Depending
* on the operation and the cryptographic algorithm it can
* represent either the public key or a pair of matching
* public and private keys. Also it may contain other
* implementation specific data.
*/ */
typedef struct typedef struct
{ {
@ -256,12 +264,9 @@ typedef size_t (*mbedtls_pk_rsa_alt_key_len_func)( void *ctx );
* *
* \param pk_type PK type to search for. * \param pk_type PK type to search for.
* *
* \note Different PK objects with the same type may have different * \note This function returns NULL if pk_type indicates an opaque
* information. This function returns the information needed * key, since the type does not provide enough information to
* to create a object with the default implementation * build an opaque key.
* for the given PK operation type (rsa module for an RSA
* context, ecdh module for an ECDH context, ecdsa module for
* an ECDSA context).
* *
* \return The PK info associated with the type or NULL if not found. * \return The PK info associated with the type or NULL if not found.
*/ */
@ -290,13 +295,13 @@ void mbedtls_pk_free( mbedtls_pk_context *ctx );
* *
* \note Engines that implement opaque keys may offer an * \note Engines that implement opaque keys may offer an
* alternative setup function that take engine-dependent * alternative setup function that take engine-dependent
* parameters. If such a function exists, call it * parameters. If the documentation of the engine lists such a
* instead of mbedtls_pk_setup. A standard way of providing * function, call it instead of mbedtls_pk_setup. A standard
* such function is by first calling the generic * way of providing such function is by first calling the
* mbedtls_pk_setup function (in particular taking care of * generic mbedtls_pk_setup function (in particular taking
* context allocation through ctx_alloc) and afterwards * care of context allocation through ctx_alloc) and
* proceeding to initialize the implementation-specific * afterwards proceeding to initialize the
* context structure. * implementation-specific context structure.
* *
* \note For contexts holding an RSA-alt key pair, use * \note For contexts holding an RSA-alt key pair, use
* \c mbedtls_pk_setup_rsa_alt() instead. * \c mbedtls_pk_setup_rsa_alt() instead.
@ -539,7 +544,7 @@ int mbedtls_pk_encrypt( mbedtls_pk_context *ctx,
* *
* \note Opaque key types may omit implementing this function * \note Opaque key types may omit implementing this function
* by providing a NULL pointer in the mbedtls_pk_info_t structure. * by providing a NULL pointer in the mbedtls_pk_info_t structure.
* An opaque \c pub never matches a transparent \c prv. * Currently, 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 ); int mbedtls_pk_check_pair( const mbedtls_pk_context *pub, const mbedtls_pk_context *prv );

100
include/mbedtls/pk_info.h
View File

@ -1,12 +1,19 @@
/** /**
* \file pk_info.h * \file pk_info.h
* *
* \brief Public Key cryptography abstraction layer: object interface * \brief Public Key cryptography abstraction layer: engine interface
*
* This file contains the info structure interface used by developers to
* provide target-specific implementations of opaque key handling functions
* (called engines in the following).
* *
* This file defines the interface the 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
* purely in software or with hardware acceleration support, depending
* on the target platform. In addition, it is possible to define custom
* opaque key engines that forward operation requests to cryptographic
* modules outside Mbed TLS, such as external cryptoprocessors or general
* PKCS#11 tokens.
*/
/*
* Copyright (C) 2006-2018, ARM Limited, All Rights Reserved * Copyright (C) 2006-2018, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
@ -76,11 +83,11 @@ extern "C" {
* Some methods are optional; this is clearly indicated in their description. * Some methods are optional; this is clearly indicated in their description.
* If a method is optional, then an opaque key implementation may put NULL * If a method is optional, then an opaque key implementation may put NULL
* in the corresponding field. The corresponding function in pk.h will * in the corresponding field. The corresponding function in pk.h will
* return MBEDTLS_ERR_PK_TYPE_MISMATCH in this case. * return #MBEDTLS_ERR_PK_TYPE_MISMATCH in this case.
* *
* *
* \warning: Do not declare this structure directly! It may be extended in * \warning: Do not declare this structure directly! It may be extended in
* future* versions of Mbed TLS. Call the macro * future versions of Mbed TLS. Call the macro
* MBEDTLS_PK_OPAQUE_INFO_1() instead. * MBEDTLS_PK_OPAQUE_INFO_1() instead.
* This macro is guaranteed to take parameters with the same type * This macro is guaranteed to take parameters with the same type
* and semantics as previous versions and fill any new field of the * and semantics as previous versions and fill any new field of the
@ -93,7 +100,7 @@ struct mbedtls_pk_info_t
* mbedtls_pk_get_type() returns this value. * mbedtls_pk_get_type() returns this value.
* *
* For transparent keys, this contains an indication of supported * For transparent keys, this contains an indication of supported
* algorithms. For opaque keys, this is \c MBEDTLS_PK_OPAQUE. */ * algorithms. For opaque keys, this is #MBEDTLS_PK_OPAQUE. */
mbedtls_pk_type_t type; mbedtls_pk_type_t type;
/** Type name. /** Type name.
@ -155,7 +162,8 @@ struct mbedtls_pk_info_t
* return #MBEDTLS_ERR_PK_BAD_INPUT_DATA otherwise. * return #MBEDTLS_ERR_PK_BAD_INPUT_DATA otherwise.
* *
* Opaque implementations may omit this method if they do not support * Opaque implementations may omit this method if they do not support
* signing. */ * signing. If this method is provided, so must be
* \ref mbedtls_pk_info_t.signature_size_func. */
int (*sign_func)( void *ctx, mbedtls_md_type_t md_alg, int (*sign_func)( void *ctx, mbedtls_md_type_t md_alg,
const unsigned char *hash, size_t hash_len, const unsigned char *hash, size_t hash_len,
unsigned char *sig, size_t *sig_len, unsigned char *sig, size_t *sig_len,
@ -200,9 +208,39 @@ struct mbedtls_pk_info_t
* *
* mbedtls_pk_check_pair() calls this function on the private key pair * mbedtls_pk_check_pair() calls this function on the private key pair
* object \c prv. The other argument \c pub may be of any type, but it * object \c prv. The other argument \c pub may be of any type, but it
* is guaranteed to be initialized. * is guaranteed to be initialized. The implementation is allowed to do
* a probabilistic and computationally expensive check.
* *
* Opaque implementations may omit this method. */ * If \c prv is an RSA key and \c pub is a transparent RSA key
* (i.e. \c pub has the type #MBEDTLS_PK_RSA or #MBEDTLS_PK_RSASSA_PSS),
* then \c check_pair_func must return 0 if the public key is
* mathematically equivalent to the public part of \c prv, and
* #MBEDTLS_ERR_RSA_KEY_CHECK_FAILED otherwise.
*
* If \c pub is an ECC key and \c pub is a transparent ECC key that can
* be used for ECDSA (i.e. \c pub has the type #MBEDTLS_PK_ECKEY or
* #MBEDTLS_PK_ECDSA), then check_pair_func must return 0 if the public
* key is mathematically equivalent to the public part of prv, and
* #MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise.
*
* If \c pub is a transparent key (key of type #MBEDTLS_PK_RSA,
* #MBEDTLS_PK_RSASSA_PSS, #MBEDTLS_PK_ECKEY or #MBEDTLS_PK_ECDSA) whose
* type does not match the semantic type of \c prv (RSA, ECC or other),
* then check_pair_func must return #MBEDTLS_ERR_PK_TYPE_MISMATCH.
*
* If \c pub and \c prv are opaque keys from the same engines (i.e. ``),
* then check_pair_func must return 0, `#MBEDTLS_ERR_PK_TYPE_MISMATCH`, or
* `#MBEDTLS_ERR_RSA_KEY_CHECK_FAILED` or `#MBEDTLS_ERR_ECP_BAD_INPUT_DATA`
* as in the case of transparent keys.
*
* If \c pub is an opaque key which is not from the same engine as \c prv,
* then check_pair_func may either return a semantically correct status as
* in the case of transparent keys, or it may return
* #MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE.
*
* Alternatively, check_pair_func may return another PK, RSA or ECP error
* code if applicable.
* */
int (*check_pair_func)( const mbedtls_pk_context *pub, const mbedtls_pk_context *prv ); int (*check_pair_func)( const mbedtls_pk_context *pub, const mbedtls_pk_context *prv );
/** Allocate a new context /** Allocate a new context
@ -213,11 +251,11 @@ struct mbedtls_pk_info_t
* have failed and the the object remains uninitialized. * have failed and the the object remains uninitialized.
* *
* Opaque implementations may omit this method. In this case, * Opaque implementations may omit this method. In this case,
* mbedtls_pk_setup will set the \c pk_ctx field of the mbedtls_pk_context * mbedtls_pk_setup() will set the \c pk_ctx field of the
* object to NULL, and it is up to an engine-specific setup function to * mbedtls_pk_context object to NULL, and it is up to an engine-specific
* initialize the \c pk_ctx field. This is useful if the size of the * setup function to initialize the \c pk_ctx field. This is useful if
* memory depends on extra parameters passed to the engine-specific setup * the size of the memory depends on extra parameters passed to the
* function. */ * engine-specific setup function. */
void * (*ctx_alloc_func)( void ); void * (*ctx_alloc_func)( void );
/** Free the given context /** Free the given context
@ -237,6 +275,36 @@ struct mbedtls_pk_info_t
}; };
/**
* Methods that opaque key pair objects must implement.
*
* \brief Initializer for opaque key engines
*
* 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.
*
* This macro is suitable for static initializers provided that all of its
* parameters are constant.
*
* \param name For transparent keys, this reflects the key type. For opaque
* 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
* \param verify_func \ref mbedtls_pk_info_t.verify_func method
* \param sign_func \ref mbedtls_pk_info_t.sign_func method
* \param decrypt_func \ref mbedtls_pk_info_t.decrypt_func method
* \param encrypt_func \ref mbedtls_pk_info_t.encrypt_func method
* \param check_pair_func \ref mbedtls_pk_info_t.check_pair_func method
* \param ctx_alloc_func \ref mbedtls_pk_info_t.ctx_alloc_func method
* \param ctx_free_func \ref mbedtls_pk_info_t.ctx_free_func method
* \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
*
* */
#define MBEDTLS_PK_OPAQUE_INFO_1( \ #define MBEDTLS_PK_OPAQUE_INFO_1( \
name \ name \
, get_bitlen \ , get_bitlen \

11
include/mbedtls/pk_internal.h
View File

@ -1,11 +1,16 @@
/** /**
* \file pk_internal.h * \file pk_internal.h
* *
* \brief Public Key cryptography abstraction layer: built-in key types * \brief Public Key cryptography abstraction layer: internal definitions
* *
* This file contains built-in types for handling various key types using * This file contains built-in types for handling natively supported key types
* the interface defined in pk_info.h. * using the interface defined in pk_info.h.
* *
* \warning This file contains internal definitions for the library.
* The interfaces in this file may change in future versions of the
* library without notice.
*/
/*
* Copyright (C) 2006-2018, ARM Limited, All Rights Reserved * Copyright (C) 2006-2018, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *

2
library/ecdsa.c
View File

@ -311,7 +311,7 @@ int mbedtls_ecdsa_signature_to_asn1( const mbedtls_mpi *r, const mbedtls_mpi *s,
} }
/* /*
* Compute and write signature * Compute and write signature. This function assumes that sig is large enough.
*/ */
int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg, int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg,
const unsigned char *hash, size_t hlen, const unsigned char *hash, size_t hlen,

16
tests/suites/test_suite_pk.data
View File

@ -138,14 +138,14 @@ Check pair #2 (EC, bad)
depends_on:MBEDTLS_ECP_C:MBEDTLS_ECP_DP_SECP256R1_ENABLED depends_on:MBEDTLS_ECP_C:MBEDTLS_ECP_DP_SECP256R1_ENABLED
mbedtls_pk_check_pair:"data_files/ec_256_pub.pem":"data_files/server5.key":MBEDTLS_ERR_ECP_BAD_INPUT_DATA mbedtls_pk_check_pair:"data_files/ec_256_pub.pem":"data_files/server5.key":MBEDTLS_ERR_ECP_BAD_INPUT_DATA
#Check pair #3 (RSA, OK) Check pair #3 (RSA, OK)
#depends_on:MBEDTLS_RSA_C depends_on:MBEDTLS_RSA_C
#mbedtls_pk_check_pair:"data_files/server1.pubkey":"data_files/server1.key":0 mbedtls_pk_check_pair:"data_files/server1.pubkey":"data_files/server1.key":0
#
#Check pair #4 (RSA, bad) Check pair #4 (RSA, bad)
#depends_on:MBEDTLS_RSA_C depends_on:MBEDTLS_RSA_C
#mbedtls_pk_check_pair:"data_files/server1.pubkey":"data_files/server2.key":MBEDTLS_ERR_RSA_KEY_CHECK_FAILED mbedtls_pk_check_pair:"data_files/server1.pubkey":"data_files/server2.key":MBEDTLS_ERR_RSA_KEY_CHECK_FAILED
#
Check pair #5 (RSA vs EC) Check pair #5 (RSA vs EC)
depends_on:MBEDTLS_ECP_C:MBEDTLS_ECP_DP_SECP256R1_ENABLED:MBEDTLS_RSA_C depends_on:MBEDTLS_ECP_C:MBEDTLS_ECP_DP_SECP256R1_ENABLED:MBEDTLS_RSA_C
mbedtls_pk_check_pair:"data_files/ec_256_pub.pem":"data_files/server1.key":MBEDTLS_ERR_PK_TYPE_MISMATCH mbedtls_pk_check_pair:"data_files/ec_256_pub.pem":"data_files/server1.key":MBEDTLS_ERR_PK_TYPE_MISMATCH