yuzu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2025-11-04 15:05:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation fixes

Browse source 
Added more elaborate comments and descriptions
This commit is contained in:
Unknown 2018-02-06 03:17:59 -05:00
parent e735310551
commit 60b25f0529
4 changed files with 55 additions and 37 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
include/mbedtls/ecdsa.h
View file

@ -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

44
include/mbedtls/pk.h
View file

@ -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 );

29
include/mbedtls/pk_info.h
View file

@ -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.
*

5
include/mbedtls/pk_internal.h
View file

@ -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