Improved documentation a bit in the PK interface
diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h
index f9f9b9b..e208da2 100644
--- a/include/mbedtls/pk.h
+++ b/include/mbedtls/pk.h
@@ -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 @@
#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 @@
* 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 @@
* 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 @@
#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 @@
* 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 @@
* \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 @@
* \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 @@
}
/**
- * \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 @@
* \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 @@
* 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 @@
* \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 @@
*
* \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 @@
*
* \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 @@
* \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 @@
* \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 @@
*/
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 @@
#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_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_load_file( const char *path, unsigned char **buf, size_t *n );
#endif
+/**@}*/
+
#ifdef __cplusplus
}
#endif