yuzu-emu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2024-11-26 04:15:41 +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
*
* \brief Public Key abstraction layer
* \brief Public Key cryptography abstraction layer
*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
@ -49,6 +49,9 @@
#define inline __inline
#endif
/** \name Error codes */
/**@{*/
#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_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_SIG_LEN_MISMATCH -0x3900 /**< The signature is valid but its length is less than expected. */
/**@}*/
#ifdef __cplusplus
extern "C" {
#endif
/** \name Asymmetric cryptography operation contexts */
/**@{*/
/**
* \brief Public key types
* \brief Asymmetric operation context types
*/
typedef enum {
MBEDTLS_PK_NONE=0,
MBEDTLS_PK_RSA,
MBEDTLS_PK_ECKEY,
MBEDTLS_PK_ECKEY_DH,
MBEDTLS_PK_ECDSA,
MBEDTLS_PK_RSA_ALT,
MBEDTLS_PK_RSASSA_PSS,
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, /**< ECC key pair with ECDSA context */
MBEDTLS_PK_ECKEY_DH, /**< ECC key pair with ECDH context */
MBEDTLS_PK_ECDSA, /**< ECC key pair with ECDSA context */
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_type_t;
/**
@ -116,17 +124,17 @@ typedef struct
#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;
/**
* \brief Public key container
* \brief Key pair container
*/
typedef struct
{
const mbedtls_pk_info_t * pk_info; /**< Public key informations */
void * pk_ctx; /**< Underlying public key context */
const mbedtls_pk_info_t * pk_info; /**< Algorithm information */
void * pk_ctx; /**< Underlying key pair context */
} mbedtls_pk_context;
#if defined(MBEDTLS_RSA_C)
@ -134,7 +142,8 @@ typedef struct
* Quick access to an RSA context inside a PK 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 )
{
@ -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.
*
* \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 )
{
@ -170,10 +180,17 @@ typedef size_t (*mbedtls_pk_rsa_alt_key_len_func)( void *ctx );
#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.
*
* \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.
*/
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_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.
*/
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
*
* \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 sign_func Signing function
* \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
* \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
*/
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 type Target type
*
* \return 0 if context can't do the operations,
* 1 otherwise.
* \return 1 if context can do the operations,
* 0 otherwise.
*/
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),
* MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if the signature is
* 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.
* 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,
* MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if the signature is
* 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
* 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 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.
* 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.
*
* \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,
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.
*
* \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,
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 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 );
@ -405,7 +443,11 @@ int mbedtls_pk_check_pair( const mbedtls_pk_context *pub, const mbedtls_pk_conte
* \param ctx Context to use
* \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 );
@ -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 );
/**@}*/
#if defined(MBEDTLS_PK_PARSE_C)
/** \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_PK_PARSE_C */
#if defined(MBEDTLS_PK_WRITE_C)
/** \name Key pair serialization */
/**@{*/
/**
* \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
@ -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 );
#endif /* MBEDTLS_PEM_WRITE_C */
/**@}*/
#endif /* MBEDTLS_PK_WRITE_C */
/*
* WARNING: Low-level functions. You probably do not want to use these unless
* you are certain you do ;)
/** \name Low-level functions */
/**@{*/
/**
* \warning You probably do not want to use these unless you are certain you do ;)
*/
#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 );
#endif
/**@}*/
#ifdef __cplusplus
}
#endif

4
include/mbedtls/pk_internal.h
View File

@ -1,7 +1,7 @@
/**
* \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
* SPDX-License-Identifier: Apache-2.0
@ -34,7 +34,7 @@
struct mbedtls_pk_info_t
{
/** Public key type */
/** Key pair type with indication of supported algorithms */
mbedtls_pk_type_t type;
/** Type name */