yuzu-emu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2024-11-26 06:45:44 +01:00
Code Issues Packages Projects Releases Wiki Activity

Improved documentation a bit in the PK interface

Browse Source
This commit is contained in:
Gilles Peskine 2017-09-21 14:56:36 +02:00 committed by Andrzej Kurek
parent 297d7535fb
commit badc52993f
2 changed files with 87 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

116
include/mbedtls/pk.h
View File

@ -1,7 +1,7 @@
/** /**
* \file pk.h * \file pk.h
* *
* \brief Public Key abstraction layer * \brief Public Key cryptography abstraction layer
* *
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
@ -49,6 +49,9 @@
#define inline __inline #define inline __inline
#endif #endif
/** \name Error codes */
/**@{*/
#define MBEDTLS_ERR_PK_ALLOC_FAILED -0x3F80 /**< Memory allocation failed. */ #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_BAD_INPUT_DATA -0x3E80 /**< Bad input parameters to function. */
@ -64,21 +67,26 @@
#define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE -0x3980 /**< Unavailable feature, e.g. RSA disabled for RSA key. */ #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_SIG_LEN_MISMATCH -0x3900 /**< The signature is valid but its length is less than expected. */
/**@}*/
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif #endif
/** \name Asymmetric cryptography operation contexts */
/**@{*/
/** /**
* \brief Public key types * \brief Asymmetric operation context types
*/ */
typedef enum { typedef enum {
MBEDTLS_PK_NONE=0, MBEDTLS_PK_NONE=0, /**< Unused context object */
MBEDTLS_PK_RSA, MBEDTLS_PK_RSA, /**< RSA key pair (normal software implementation) with PKCS#1 v1.5 or PSS context */
MBEDTLS_PK_ECKEY, MBEDTLS_PK_ECKEY, /**< ECC key pair with ECDSA context */
MBEDTLS_PK_ECKEY_DH, MBEDTLS_PK_ECKEY_DH, /**< ECC key pair with ECDH context */
MBEDTLS_PK_ECDSA, MBEDTLS_PK_ECDSA, /**< ECC key pair with ECDSA context */
MBEDTLS_PK_RSA_ALT, MBEDTLS_PK_RSA_ALT, /**< RSA (alternative implementation) */
MBEDTLS_PK_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_type_t; } mbedtls_pk_type_t;
/** /**
@ -116,17 +124,17 @@ typedef struct
#define MBEDTLS_PK_DEBUG_MAX_ITEMS 3 #define MBEDTLS_PK_DEBUG_MAX_ITEMS 3
/** /**
* \brief Public key information and operations * \brief Key pair information and operations
*/ */
typedef struct mbedtls_pk_info_t mbedtls_pk_info_t; typedef struct mbedtls_pk_info_t mbedtls_pk_info_t;
/** /**
* \brief Public key container * \brief Key pair container
*/ */
typedef struct typedef struct
{ {
const mbedtls_pk_info_t * pk_info; /**< Public key informations */ const mbedtls_pk_info_t * pk_info; /**< Algorithm information */
void * pk_ctx; /**< Underlying public key context */ void * pk_ctx; /**< Underlying key pair context */
} mbedtls_pk_context; } mbedtls_pk_context;
#if defined(MBEDTLS_RSA_C) #if defined(MBEDTLS_RSA_C)
@ -134,7 +142,8 @@ typedef struct
* Quick access to an RSA context inside a PK context. * Quick access to an RSA context inside a PK context.
* *
* \warning You must make sure the PK context actually holds an RSA context * \warning You must make sure the PK context actually holds an RSA context
* before using this function! * before using this function! This function is only valid if
* `pk_can_do(&pk, MBEDTLS_PK_RSA)` is true.
*/ */
static inline mbedtls_rsa_context *mbedtls_pk_rsa( const mbedtls_pk_context pk ) static inline mbedtls_rsa_context *mbedtls_pk_rsa( const mbedtls_pk_context pk )
{ {
@ -147,7 +156,8 @@ static inline mbedtls_rsa_context *mbedtls_pk_rsa( const mbedtls_pk_context pk )
* Quick access to an EC context inside a PK context. * Quick access to an EC context inside a PK context.
* *
* \warning You must make sure the PK context actually holds an EC context * \warning You must make sure the PK context actually holds an EC context
* before using this function! * before using this function! This function is only valid if
* `pk_can_do(&pk, MBEDTLS_PK_ECKEY)` is true.
*/ */
static inline mbedtls_ecp_keypair *mbedtls_pk_ec( const mbedtls_pk_context pk ) static inline mbedtls_ecp_keypair *mbedtls_pk_ec( const mbedtls_pk_context pk )
{ {
@ -170,10 +180,17 @@ typedef size_t (*mbedtls_pk_rsa_alt_key_len_func)( void *ctx );
#endif /* MBEDTLS_PK_RSA_ALT_SUPPORT */ #endif /* MBEDTLS_PK_RSA_ALT_SUPPORT */
/** /**
* \brief Return information associated with the given PK type * \brief Return default information associated with the given PK type
* *
* \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
* information. This function returns the information needed
* to create a object with the default implementation
* 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.
*/ */
const mbedtls_pk_info_t *mbedtls_pk_info_from_type( mbedtls_pk_type_t pk_type ); const mbedtls_pk_info_t *mbedtls_pk_info_from_type( mbedtls_pk_type_t pk_type );
@ -199,7 +216,7 @@ void mbedtls_pk_free( mbedtls_pk_context *ctx );
* MBEDTLS_ERR_PK_BAD_INPUT_DATA on invalid input, * MBEDTLS_ERR_PK_BAD_INPUT_DATA on invalid input,
* MBEDTLS_ERR_PK_ALLOC_FAILED on allocation failure. * MBEDTLS_ERR_PK_ALLOC_FAILED on allocation failure.
* *
* \note For contexts holding an RSA-alt key, 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.
*/ */
int mbedtls_pk_setup( mbedtls_pk_context *ctx, const mbedtls_pk_info_t *info ); int mbedtls_pk_setup( mbedtls_pk_context *ctx, const mbedtls_pk_info_t *info );
@ -209,7 +226,7 @@ int mbedtls_pk_setup( mbedtls_pk_context *ctx, const mbedtls_pk_info_t *info );
* \brief Initialize an RSA-alt context * \brief Initialize an RSA-alt context
* *
* \param ctx Context to initialize. Must be empty (type NONE). * \param ctx Context to initialize. Must be empty (type NONE).
* \param key RSA key pointer * \param key RSA key pair pointer
* \param decrypt_func Decryption function * \param decrypt_func Decryption function
* \param sign_func Signing function * \param sign_func Signing function
* \param key_len_func Function returning key length in bytes * \param key_len_func Function returning key length in bytes
@ -238,6 +255,11 @@ size_t mbedtls_pk_get_bitlen( const mbedtls_pk_context *ctx );
* \brief Get the length in bytes of the underlying key * \brief Get the length in bytes of the underlying key
* \param ctx Context to use * \param ctx Context to use
* *
* \note This returns the minimum number of bytes required to
* store the part of the key that defines its size (modulus
* for RSA, coordinate for ECC). The way the key is stored
* in the context may have a different size.
*
* \return Key length in bytes, or 0 on error * \return Key length in bytes, or 0 on error
*/ */
static inline size_t mbedtls_pk_get_len( const mbedtls_pk_context *ctx ) static inline size_t mbedtls_pk_get_len( const mbedtls_pk_context *ctx )
@ -246,13 +268,24 @@ static inline size_t mbedtls_pk_get_len( const mbedtls_pk_context *ctx )
} }
/** /**
* \brief Tell if a context can do the operation given by type * \brief Tell if a context can do the operations given by type
*
* \note This function can be used to identify the type of key
* (e.g. RSA vs ECC), and a superset of permitted
* operations. It is possible that this function returns
* true but some operations are not allowed. For example
* this function always returns true if ctx is an RSA
* context and type is MBEDTLS_PK_RSA, but the key may
* be restricted to any subset of operations among signature,
* verification, encryption and decryption. To determine
* which operations a key allow, attempt the operation and
* check the return status.
* *
* \param ctx Context to test * \param ctx Context to test
* \param type Target type * \param type Target type
* *
* \return 0 if context can't do the operations, * \return 1 if context can do the operations,
* 1 otherwise. * 0 otherwise.
*/ */
int mbedtls_pk_can_do( const mbedtls_pk_context *ctx, mbedtls_pk_type_t type ); int mbedtls_pk_can_do( const mbedtls_pk_context *ctx, mbedtls_pk_type_t type );
@ -269,7 +302,7 @@ int mbedtls_pk_can_do( const mbedtls_pk_context *ctx, mbedtls_pk_type_t type );
* \return 0 on success (signature is valid), * \return 0 on success (signature is valid),
* MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if the signature is * MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if the signature is
* valid but its actual length is less than sig_len, * valid but its actual length is less than sig_len,
* or a specific error code. * or a type-specific error code.
* *
* \note For RSA keys, the default padding type is PKCS#1 v1.5. * \note For RSA keys, the default padding type is PKCS#1 v1.5.
* Use \c mbedtls_pk_verify_ext( MBEDTLS_PK_RSASSA_PSS, ... ) * Use \c mbedtls_pk_verify_ext( MBEDTLS_PK_RSASSA_PSS, ... )
@ -302,7 +335,7 @@ int mbedtls_pk_verify( mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
* used for this type of signatures, * used for this type of signatures,
* MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if the signature is * MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if the signature is
* valid but its actual length is less than sig_len, * valid but its actual length is less than sig_len,
* or a specific error code. * or a type-specific error code.
* *
* \note If hash_len is 0, then the length associated with md_alg * \note If hash_len is 0, then the length associated with md_alg
* is used instead, or an error returned if it is invalid. * is used instead, or an error returned if it is invalid.
@ -330,7 +363,7 @@ int mbedtls_pk_verify_ext( mbedtls_pk_type_t type, const void *options,
* \param f_rng RNG function * \param f_rng RNG function
* \param p_rng RNG parameter * \param p_rng RNG parameter
* *
* \return 0 on success, or a specific error code. * \return 0 on success, or a type-specific error code.
* *
* \note For RSA keys, the default padding type is PKCS#1 v1.5. * \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 * There is no interface in the PK module to make RSASSA-PSS
@ -361,7 +394,7 @@ int mbedtls_pk_sign( mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
* *
* \note For RSA keys, the default padding type is PKCS#1 v1.5. * \note For RSA keys, the default padding type is PKCS#1 v1.5.
* *
* \return 0 on success, or a specific error code. * \return 0 on success, or a type-specific error code.
*/ */
int mbedtls_pk_decrypt( mbedtls_pk_context *ctx, int mbedtls_pk_decrypt( mbedtls_pk_context *ctx,
const unsigned char *input, size_t ilen, const unsigned char *input, size_t ilen,
@ -382,7 +415,7 @@ int mbedtls_pk_decrypt( mbedtls_pk_context *ctx,
* *
* \note For RSA keys, the default padding type is PKCS#1 v1.5. * \note For RSA keys, the default padding type is PKCS#1 v1.5.
* *
* \return 0 on success, or a specific error code. * \return 0 on success, or a type-specific error code.
*/ */
int mbedtls_pk_encrypt( mbedtls_pk_context *ctx, int mbedtls_pk_encrypt( mbedtls_pk_context *ctx,
const unsigned char *input, size_t ilen, const unsigned char *input, size_t ilen,
@ -395,7 +428,12 @@ int mbedtls_pk_encrypt( mbedtls_pk_context *ctx,
* \param pub Context holding a public key. * \param pub Context holding a public key.
* \param prv Context holding a private (and public) key. * \param prv Context holding a private (and public) key.
* *
* \return 0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA * \return * 0 on success.
* * MBEDTLS_ERR_PK_BAD_INPUT_DATA if one of the contexts
* is ill-formed.
* * MBEDTLS_ERR_PK_TYPE_MISMATCH if the contexts cannot
* represent keys of the same type.
* * Or a type-specific error code.
*/ */
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 );
@ -405,7 +443,11 @@ int mbedtls_pk_check_pair( const mbedtls_pk_context *pub, const mbedtls_pk_conte
* \param ctx Context to use * \param ctx Context to use
* \param items Place to write debug items * \param items Place to write debug items
* *
* \return 0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA * \return * 0 on success.
* * MBEDTLS_ERR_PK_BAD_INPUT_DATA if the context is ill-formed.
* * MBEDTLS_ERR_PK_TYPE_MISMATCH if the context does not
* support exporting debug information.
* * Or a type-specific error code.
*/ */
int mbedtls_pk_debug( const mbedtls_pk_context *ctx, mbedtls_pk_debug_item *items ); int mbedtls_pk_debug( const mbedtls_pk_context *ctx, mbedtls_pk_debug_item *items );
@ -427,6 +469,9 @@ const char * mbedtls_pk_get_name( const mbedtls_pk_context *ctx );
*/ */
mbedtls_pk_type_t mbedtls_pk_get_type( const mbedtls_pk_context *ctx ); mbedtls_pk_type_t mbedtls_pk_get_type( const mbedtls_pk_context *ctx );
/**@}*/
#if defined(MBEDTLS_PK_PARSE_C) #if defined(MBEDTLS_PK_PARSE_C)
/** \ingroup pk_module */ /** \ingroup pk_module */
/** /**
@ -511,7 +556,12 @@ int mbedtls_pk_parse_public_keyfile( mbedtls_pk_context *ctx, const char *path )
#endif /* MBEDTLS_FS_IO */ #endif /* MBEDTLS_FS_IO */
#endif /* MBEDTLS_PK_PARSE_C */ #endif /* MBEDTLS_PK_PARSE_C */
#if defined(MBEDTLS_PK_WRITE_C) #if defined(MBEDTLS_PK_WRITE_C)
/** \name Key pair serialization */
/**@{*/
/** /**
* \brief Write a private key to a PKCS#1 or SEC1 DER structure * \brief Write a private key to a PKCS#1 or SEC1 DER structure
* Note: data is written at the end of the buffer! Use the * Note: data is written at the end of the buffer! Use the
@ -565,11 +615,13 @@ int mbedtls_pk_write_pubkey_pem( mbedtls_pk_context *ctx, unsigned char *buf, si
*/ */
int mbedtls_pk_write_key_pem( mbedtls_pk_context *ctx, unsigned char *buf, size_t size ); int mbedtls_pk_write_key_pem( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
#endif /* MBEDTLS_PEM_WRITE_C */ #endif /* MBEDTLS_PEM_WRITE_C */
/**@}*/
#endif /* MBEDTLS_PK_WRITE_C */ #endif /* MBEDTLS_PK_WRITE_C */
/* /** \name Low-level functions */
* WARNING: Low-level functions. You probably do not want to use these unless /**@{*/
* you are certain you do ;) /**
* \warning You probably do not want to use these unless you are certain you do ;)
*/ */
#if defined(MBEDTLS_PK_PARSE_C) #if defined(MBEDTLS_PK_PARSE_C)
@ -609,6 +661,8 @@ int mbedtls_pk_write_pubkey( unsigned char **p, unsigned char *start,
int mbedtls_pk_load_file( const char *path, unsigned char **buf, size_t *n ); int mbedtls_pk_load_file( const char *path, unsigned char **buf, size_t *n );
#endif #endif
/**@}*/
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif

4
include/mbedtls/pk_internal.h
View File

@ -1,7 +1,7 @@
/** /**
* \file pk.h * \file pk.h
* *
* \brief Public Key abstraction layer: wrapper functions * \brief Public Key cryptography abstraction layer: wrapper functions
* *
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
@ -34,7 +34,7 @@
struct mbedtls_pk_info_t struct mbedtls_pk_info_t
{ {
/** Public key type */ /** Key pair type with indication of supported algorithms */
mbedtls_pk_type_t type; mbedtls_pk_type_t type;
/** Type name */ /** Type name */