git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/mbedtls/include/mbedtls/pk.h

   1 /**\r
   2  * \file pk.h\r
   3  *\r
   4  * \brief Public Key abstraction layer\r
   5  */\r
   6 /*\r
   7  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved\r
   8  *  SPDX-License-Identifier: Apache-2.0\r
   9  *\r
  10  *  Licensed under the Apache License, Version 2.0 (the "License"); you may\r
  11  *  not use this file except in compliance with the License.\r
  12  *  You may obtain a copy of the License at\r
  13  *\r
  14  *  http://www.apache.org/licenses/LICENSE-2.0\r
  15  *\r
  16  *  Unless required by applicable law or agreed to in writing, software\r
  17  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT\r
  18  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  19  *  See the License for the specific language governing permissions and\r
  20  *  limitations under the License.\r
  21  *\r
  22  *  This file is part of mbed TLS (https://tls.mbed.org)\r
  23  */\r
  24 \r
  25 #ifndef MBEDTLS_PK_H\r
  26 #define MBEDTLS_PK_H\r
  27 \r
  28 #if !defined(MBEDTLS_CONFIG_FILE)\r
  29 #include "config.h"\r
  30 #else\r
  31 #include MBEDTLS_CONFIG_FILE\r
  32 #endif\r
  33 \r
  34 #include "md.h"\r
  35 \r
  36 #if defined(MBEDTLS_RSA_C)\r
  37 #include "rsa.h"\r
  38 #endif\r
  39 \r
  40 #if defined(MBEDTLS_ECP_C)\r
  41 #include "ecp.h"\r
  42 #endif\r
  43 \r
  44 #if defined(MBEDTLS_ECDSA_C)\r
  45 #include "ecdsa.h"\r
  46 #endif\r
  47 \r
  48 #if defined(MBEDTLS_USE_PSA_CRYPTO)\r
  49 #include "psa/crypto.h"\r
  50 #endif\r
  51 \r
  52 #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \\r
  53     !defined(inline) && !defined(__cplusplus)\r
  54 #define inline __inline\r
  55 #endif\r
  56 \r
  57 #define MBEDTLS_ERR_PK_ALLOC_FAILED        -0x3F80  /**< Memory allocation failed. */\r
  58 #define MBEDTLS_ERR_PK_TYPE_MISMATCH       -0x3F00  /**< Type mismatch, eg attempt to encrypt with an ECDSA key */\r
  59 #define MBEDTLS_ERR_PK_BAD_INPUT_DATA      -0x3E80  /**< Bad input parameters to function. */\r
  60 #define MBEDTLS_ERR_PK_FILE_IO_ERROR       -0x3E00  /**< Read/write of file failed. */\r
  61 #define MBEDTLS_ERR_PK_KEY_INVALID_VERSION -0x3D80  /**< Unsupported key version */\r
  62 #define MBEDTLS_ERR_PK_KEY_INVALID_FORMAT  -0x3D00  /**< Invalid key tag or value. */\r
  63 #define MBEDTLS_ERR_PK_UNKNOWN_PK_ALG      -0x3C80  /**< Key algorithm is unsupported (only RSA and EC are supported). */\r
  64 #define MBEDTLS_ERR_PK_PASSWORD_REQUIRED   -0x3C00  /**< Private key password can't be empty. */\r
  65 #define MBEDTLS_ERR_PK_PASSWORD_MISMATCH   -0x3B80  /**< Given private key password does not allow for correct decryption. */\r
  66 #define MBEDTLS_ERR_PK_INVALID_PUBKEY      -0x3B00  /**< The pubkey tag or value is invalid (only RSA and EC are supported). */\r
  67 #define MBEDTLS_ERR_PK_INVALID_ALG         -0x3A80  /**< The algorithm tag or value is invalid. */\r
  68 #define MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE -0x3A00  /**< Elliptic curve is unsupported (only NIST curves are supported). */\r
  69 #define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE -0x3980  /**< Unavailable feature, e.g. RSA disabled for RSA key. */\r
  70 #define MBEDTLS_ERR_PK_SIG_LEN_MISMATCH    -0x3900  /**< The buffer contains a valid signature followed by more data. */\r
  71 \r
  72 /* MBEDTLS_ERR_PK_HW_ACCEL_FAILED is deprecated and should not be used. */\r
  73 #define MBEDTLS_ERR_PK_HW_ACCEL_FAILED     -0x3880  /**< PK hardware accelerator failed. */\r
  74 \r
  75 #ifdef __cplusplus\r
  76 extern "C" {\r
  77 #endif\r
  78 \r
  79 /**\r
  80  * \brief          Public key types\r
  81  */\r
  82 typedef enum {\r
  83     MBEDTLS_PK_NONE=0,\r
  84     MBEDTLS_PK_RSA,\r
  85     MBEDTLS_PK_ECKEY,\r
  86     MBEDTLS_PK_ECKEY_DH,\r
  87     MBEDTLS_PK_ECDSA,\r
  88     MBEDTLS_PK_RSA_ALT,\r
  89     MBEDTLS_PK_RSASSA_PSS,\r
  90     MBEDTLS_PK_OPAQUE,\r
  91 } mbedtls_pk_type_t;\r
  92 \r
  93 /**\r
  94  * \brief           Options for RSASSA-PSS signature verification.\r
  95  *                  See \c mbedtls_rsa_rsassa_pss_verify_ext()\r
  96  */\r
  97 typedef struct mbedtls_pk_rsassa_pss_options\r
  98 {\r
  99     mbedtls_md_type_t mgf1_hash_id;\r
 100     int expected_salt_len;\r
 101 \r
 102 } mbedtls_pk_rsassa_pss_options;\r
 103 \r
 104 /**\r
 105  * \brief           Types for interfacing with the debug module\r
 106  */\r
 107 typedef enum\r
 108 {\r
 109     MBEDTLS_PK_DEBUG_NONE = 0,\r
 110     MBEDTLS_PK_DEBUG_MPI,\r
 111     MBEDTLS_PK_DEBUG_ECP,\r
 112 } mbedtls_pk_debug_type;\r
 113 \r
 114 /**\r
 115  * \brief           Item to send to the debug module\r
 116  */\r
 117 typedef struct mbedtls_pk_debug_item\r
 118 {\r
 119     mbedtls_pk_debug_type type;\r
 120     const char *name;\r
 121     void *value;\r
 122 } mbedtls_pk_debug_item;\r
 123 \r
 124 /** Maximum number of item send for debugging, plus 1 */\r
 125 #define MBEDTLS_PK_DEBUG_MAX_ITEMS 3\r
 126 \r
 127 /**\r
 128  * \brief           Public key information and operations\r
 129  */\r
 130 typedef struct mbedtls_pk_info_t mbedtls_pk_info_t;\r
 131 \r
 132 /**\r
 133  * \brief           Public key container\r
 134  */\r
 135 typedef struct mbedtls_pk_context\r
 136 {\r
 137     const mbedtls_pk_info_t *   pk_info; /**< Public key information         */\r
 138     void *                      pk_ctx;  /**< Underlying public key context  */\r
 139 } mbedtls_pk_context;\r
 140 \r
 141 #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)\r
 142 /**\r
 143  * \brief           Context for resuming operations\r
 144  */\r
 145 typedef struct\r
 146 {\r
 147     const mbedtls_pk_info_t *   pk_info; /**< Public key information         */\r
 148     void *                      rs_ctx;  /**< Underlying restart context     */\r
 149 } mbedtls_pk_restart_ctx;\r
 150 #else /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */\r
 151 /* Now we can declare functions that take a pointer to that */\r
 152 typedef void mbedtls_pk_restart_ctx;\r
 153 #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */\r
 154 \r
 155 #if defined(MBEDTLS_RSA_C)\r
 156 /**\r
 157  * Quick access to an RSA context inside a PK context.\r
 158  *\r
 159  * \warning You must make sure the PK context actually holds an RSA context\r
 160  * before using this function!\r
 161  */\r
 162 static inline mbedtls_rsa_context *mbedtls_pk_rsa( const mbedtls_pk_context pk )\r
 163 {\r
 164     return( (mbedtls_rsa_context *) (pk).pk_ctx );\r
 165 }\r
 166 #endif /* MBEDTLS_RSA_C */\r
 167 \r
 168 #if defined(MBEDTLS_ECP_C)\r
 169 /**\r
 170  * Quick access to an EC context inside a PK context.\r
 171  *\r
 172  * \warning You must make sure the PK context actually holds an EC context\r
 173  * before using this function!\r
 174  */\r
 175 static inline mbedtls_ecp_keypair *mbedtls_pk_ec( const mbedtls_pk_context pk )\r
 176 {\r
 177     return( (mbedtls_ecp_keypair *) (pk).pk_ctx );\r
 178 }\r
 179 #endif /* MBEDTLS_ECP_C */\r
 180 \r
 181 #if defined(MBEDTLS_PK_RSA_ALT_SUPPORT)\r
 182 /**\r
 183  * \brief           Types for RSA-alt abstraction\r
 184  */\r
 185 typedef int (*mbedtls_pk_rsa_alt_decrypt_func)( void *ctx, int mode, size_t *olen,\r
 186                     const unsigned char *input, unsigned char *output,\r
 187                     size_t output_max_len );\r
 188 typedef int (*mbedtls_pk_rsa_alt_sign_func)( void *ctx,\r
 189                     int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,\r
 190                     int mode, mbedtls_md_type_t md_alg, unsigned int hashlen,\r
 191                     const unsigned char *hash, unsigned char *sig );\r
 192 typedef size_t (*mbedtls_pk_rsa_alt_key_len_func)( void *ctx );\r
 193 #endif /* MBEDTLS_PK_RSA_ALT_SUPPORT */\r
 194 \r
 195 /**\r
 196  * \brief           Return information associated with the given PK type\r
 197  *\r
 198  * \param pk_type   PK type to search for.\r
 199  *\r
 200  * \return          The PK info associated with the type or NULL if not found.\r
 201  */\r
 202 const mbedtls_pk_info_t *mbedtls_pk_info_from_type( mbedtls_pk_type_t pk_type );\r
 203 \r
 204 /**\r
 205  * \brief           Initialize a #mbedtls_pk_context (as NONE).\r
 206  *\r
 207  * \param ctx       The context to initialize.\r
 208  *                  This must not be \c NULL.\r
 209  */\r
 210 void mbedtls_pk_init( mbedtls_pk_context *ctx );\r
 211 \r
 212 /**\r
 213  * \brief           Free the components of a #mbedtls_pk_context.\r
 214  *\r
 215  * \param ctx       The context to clear. It must have been initialized.\r
 216  *                  If this is \c NULL, this function does nothing.\r
 217  *\r
 218  * \note            For contexts that have been set up with\r
 219  *                  mbedtls_pk_setup_opaque(), this does not free the underlying\r
 220  *                  key slot and you still need to call psa_destroy_key()\r
 221  *                  independently if you want to destroy that key.\r
 222  */\r
 223 void mbedtls_pk_free( mbedtls_pk_context *ctx );\r
 224 \r
 225 #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)\r
 226 /**\r
 227  * \brief           Initialize a restart context\r
 228  *\r
 229  * \param ctx       The context to initialize.\r
 230  *                  This must not be \c NULL.\r
 231  */\r
 232 void mbedtls_pk_restart_init( mbedtls_pk_restart_ctx *ctx );\r
 233 \r
 234 /**\r
 235  * \brief           Free the components of a restart context\r
 236  *\r
 237  * \param ctx       The context to clear. It must have been initialized.\r
 238  *                  If this is \c NULL, this function does nothing.\r
 239  */\r
 240 void mbedtls_pk_restart_free( mbedtls_pk_restart_ctx *ctx );\r
 241 #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */\r
 242 \r
 243 /**\r
 244  * \brief           Initialize a PK context with the information given\r
 245  *                  and allocates the type-specific PK subcontext.\r
 246  *\r
 247  * \param ctx       Context to initialize. It must not have been set\r
 248  *                  up yet (type #MBEDTLS_PK_NONE).\r
 249  * \param info      Information to use\r
 250  *\r
 251  * \return          0 on success,\r
 252  *                  MBEDTLS_ERR_PK_BAD_INPUT_DATA on invalid input,\r
 253  *                  MBEDTLS_ERR_PK_ALLOC_FAILED on allocation failure.\r
 254  *\r
 255  * \note            For contexts holding an RSA-alt key, use\r
 256  *                  \c mbedtls_pk_setup_rsa_alt() instead.\r
 257  */\r
 258 int mbedtls_pk_setup( mbedtls_pk_context *ctx, const mbedtls_pk_info_t *info );\r
 259 \r
 260 #if defined(MBEDTLS_USE_PSA_CRYPTO)\r
 261 /**\r
 262  * \brief           Initialize a PK context to wrap a PSA key slot.\r
 263  *\r
 264  * \note            This function replaces mbedtls_pk_setup() for contexts\r
 265  *                  that wrap a (possibly opaque) PSA key slot instead of\r
 266  *                  storing and manipulating the key material directly.\r
 267  *\r
 268  * \param ctx       The context to initialize. It must be empty (type NONE).\r
 269  * \param key       The PSA key slot to wrap, which must hold an ECC key pair\r
 270  *                  (see notes below).\r
 271  *\r
 272  * \note            The wrapped key slot must remain valid as long as the\r
 273  *                  wrapping PK context is in use, that is at least between\r
 274  *                  the point this function is called and the point\r
 275  *                  mbedtls_pk_free() is called on this context. The wrapped\r
 276  *                  key slot might then be independently used or destroyed.\r
 277  *\r
 278  * \note            This function is currently only available for ECC key\r
 279  *                  pairs (that is, ECC keys containing private key material).\r
 280  *                  Support for other key types may be added later.\r
 281  *\r
 282  * \return          \c 0 on success.\r
 283  * \return          #MBEDTLS_ERR_PK_BAD_INPUT_DATA on invalid input\r
 284  *                  (context already used, invalid key slot).\r
 285  * \return          #MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE if the key is not an\r
 286  *                  ECC key pair.\r
 287  * \return          #MBEDTLS_ERR_PK_ALLOC_FAILED on allocation failure.\r
 288  */\r
 289 int mbedtls_pk_setup_opaque( mbedtls_pk_context *ctx, const psa_key_handle_t key );\r
 290 #endif /* MBEDTLS_USE_PSA_CRYPTO */\r
 291 \r
 292 #if defined(MBEDTLS_PK_RSA_ALT_SUPPORT)\r
 293 /**\r
 294  * \brief           Initialize an RSA-alt context\r
 295  *\r
 296  * \param ctx       Context to initialize. It must not have been set\r
 297  *                  up yet (type #MBEDTLS_PK_NONE).\r
 298  * \param key       RSA key pointer\r
 299  * \param decrypt_func  Decryption function\r
 300  * \param sign_func     Signing function\r
 301  * \param key_len_func  Function returning key length in bytes\r
 302  *\r
 303  * \return          0 on success, or MBEDTLS_ERR_PK_BAD_INPUT_DATA if the\r
 304  *                  context wasn't already initialized as RSA_ALT.\r
 305  *\r
 306  * \note            This function replaces \c mbedtls_pk_setup() for RSA-alt.\r
 307  */\r
 308 int mbedtls_pk_setup_rsa_alt( mbedtls_pk_context *ctx, void * key,\r
 309                          mbedtls_pk_rsa_alt_decrypt_func decrypt_func,\r
 310                          mbedtls_pk_rsa_alt_sign_func sign_func,\r
 311                          mbedtls_pk_rsa_alt_key_len_func key_len_func );\r
 312 #endif /* MBEDTLS_PK_RSA_ALT_SUPPORT */\r
 313 \r
 314 /**\r
 315  * \brief           Get the size in bits of the underlying key\r
 316  *\r
 317  * \param ctx       The context to query. It must have been initialized.\r
 318  *\r
 319  * \return          Key size in bits, or 0 on error\r
 320  */\r
 321 size_t mbedtls_pk_get_bitlen( const mbedtls_pk_context *ctx );\r
 322 \r
 323 /**\r
 324  * \brief           Get the length in bytes of the underlying key\r
 325  *\r
 326  * \param ctx       The context to query. It must have been initialized.\r
 327  *\r
 328  * \return          Key length in bytes, or 0 on error\r
 329  */\r
 330 static inline size_t mbedtls_pk_get_len( const mbedtls_pk_context *ctx )\r
 331 {\r
 332     return( ( mbedtls_pk_get_bitlen( ctx ) + 7 ) / 8 );\r
 333 }\r
 334 \r
 335 /**\r
 336  * \brief           Tell if a context can do the operation given by type\r
 337  *\r
 338  * \param ctx       The context to query. It must have been initialized.\r
 339  * \param type      The desired type.\r
 340  *\r
 341  * \return          1 if the context can do operations on the given type.\r
 342  * \return          0 if the context cannot do the operations on the given\r
 343  *                  type. This is always the case for a context that has\r
 344  *                  been initialized but not set up, or that has been\r
 345  *                  cleared with mbedtls_pk_free().\r
 346  */\r
 347 int mbedtls_pk_can_do( const mbedtls_pk_context *ctx, mbedtls_pk_type_t type );\r
 348 \r
 349 /**\r
 350  * \brief           Verify signature (including padding if relevant).\r
 351  *\r
 352  * \param ctx       The PK context to use. It must have been set up.\r
 353  * \param md_alg    Hash algorithm used (see notes)\r
 354  * \param hash      Hash of the message to sign\r
 355  * \param hash_len  Hash length or 0 (see notes)\r
 356  * \param sig       Signature to verify\r
 357  * \param sig_len   Signature length\r
 358  *\r
 359  * \return          0 on success (signature is valid),\r
 360  *                  #MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if there is a valid\r
 361  *                  signature in sig but its length is less than \p siglen,\r
 362  *                  or a specific error code.\r
 363  *\r
 364  * \note            For RSA keys, the default padding type is PKCS#1 v1.5.\r
 365  *                  Use \c mbedtls_pk_verify_ext( MBEDTLS_PK_RSASSA_PSS, ... )\r
 366  *                  to verify RSASSA_PSS signatures.\r
 367  *\r
 368  * \note            If hash_len is 0, then the length associated with md_alg\r
 369  *                  is used instead, or an error returned if it is invalid.\r
 370  *\r
 371  * \note            md_alg may be MBEDTLS_MD_NONE, only if hash_len != 0\r
 372  */\r
 373 int mbedtls_pk_verify( mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,\r
 374                const unsigned char *hash, size_t hash_len,\r
 375                const unsigned char *sig, size_t sig_len );\r
 376 \r
 377 /**\r
 378  * \brief           Restartable version of \c mbedtls_pk_verify()\r
 379  *\r
 380  * \note            Performs the same job as \c mbedtls_pk_verify(), but can\r
 381  *                  return early and restart according to the limit set with\r
 382  *                  \c mbedtls_ecp_set_max_ops() to reduce blocking for ECC\r
 383  *                  operations. For RSA, same as \c mbedtls_pk_verify().\r
 384  *\r
 385  * \param ctx       The PK context to use. It must have been set up.\r
 386  * \param md_alg    Hash algorithm used (see notes)\r
 387  * \param hash      Hash of the message to sign\r
 388  * \param hash_len  Hash length or 0 (see notes)\r
 389  * \param sig       Signature to verify\r
 390  * \param sig_len   Signature length\r
 391  * \param rs_ctx    Restart context (NULL to disable restart)\r
 392  *\r
 393  * \return          See \c mbedtls_pk_verify(), or\r
 394  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of\r
 395  *                  operations was reached: see \c mbedtls_ecp_set_max_ops().\r
 396  */\r
 397 int mbedtls_pk_verify_restartable( mbedtls_pk_context *ctx,\r
 398                mbedtls_md_type_t md_alg,\r
 399                const unsigned char *hash, size_t hash_len,\r
 400                const unsigned char *sig, size_t sig_len,\r
 401                mbedtls_pk_restart_ctx *rs_ctx );\r
 402 \r
 403 /**\r
 404  * \brief           Verify signature, with options.\r
 405  *                  (Includes verification of the padding depending on type.)\r
 406  *\r
 407  * \param type      Signature type (inc. possible padding type) to verify\r
 408  * \param options   Pointer to type-specific options, or NULL\r
 409  * \param ctx       The PK context to use. It must have been set up.\r
 410  * \param md_alg    Hash algorithm used (see notes)\r
 411  * \param hash      Hash of the message to sign\r
 412  * \param hash_len  Hash length or 0 (see notes)\r
 413  * \param sig       Signature to verify\r
 414  * \param sig_len   Signature length\r
 415  *\r
 416  * \return          0 on success (signature is valid),\r
 417  *                  #MBEDTLS_ERR_PK_TYPE_MISMATCH if the PK context can't be\r
 418  *                  used for this type of signatures,\r
 419  *                  #MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if there is a valid\r
 420  *                  signature in sig but its length is less than \p siglen,\r
 421  *                  or a specific error code.\r
 422  *\r
 423  * \note            If hash_len is 0, then the length associated with md_alg\r
 424  *                  is used instead, or an error returned if it is invalid.\r
 425  *\r
 426  * \note            md_alg may be MBEDTLS_MD_NONE, only if hash_len != 0\r
 427  *\r
 428  * \note            If type is MBEDTLS_PK_RSASSA_PSS, then options must point\r
 429  *                  to a mbedtls_pk_rsassa_pss_options structure,\r
 430  *                  otherwise it must be NULL.\r
 431  */\r
 432 int mbedtls_pk_verify_ext( mbedtls_pk_type_t type, const void *options,\r
 433                    mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,\r
 434                    const unsigned char *hash, size_t hash_len,\r
 435                    const unsigned char *sig, size_t sig_len );\r
 436 \r
 437 /**\r
 438  * \brief           Make signature, including padding if relevant.\r
 439  *\r
 440  * \param ctx       The PK context to use. It must have been set up\r
 441  *                  with a private key.\r
 442  * \param md_alg    Hash algorithm used (see notes)\r
 443  * \param hash      Hash of the message to sign\r
 444  * \param hash_len  Hash length or 0 (see notes)\r
 445  * \param sig       Place to write the signature\r
 446  * \param sig_len   Number of bytes written\r
 447  * \param f_rng     RNG function\r
 448  * \param p_rng     RNG parameter\r
 449  *\r
 450  * \return          0 on success, or a specific error code.\r
 451  *\r
 452  * \note            For RSA keys, the default padding type is PKCS#1 v1.5.\r
 453  *                  There is no interface in the PK module to make RSASSA-PSS\r
 454  *                  signatures yet.\r
 455  *\r
 456  * \note            If hash_len is 0, then the length associated with md_alg\r
 457  *                  is used instead, or an error returned if it is invalid.\r
 458  *\r
 459  * \note            For RSA, md_alg may be MBEDTLS_MD_NONE if hash_len != 0.\r
 460  *                  For ECDSA, md_alg may never be MBEDTLS_MD_NONE.\r
 461  */\r
 462 int mbedtls_pk_sign( mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,\r
 463              const unsigned char *hash, size_t hash_len,\r
 464              unsigned char *sig, size_t *sig_len,\r
 465              int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );\r
 466 \r
 467 /**\r
 468  * \brief           Restartable version of \c mbedtls_pk_sign()\r
 469  *\r
 470  * \note            Performs the same job as \c mbedtls_pk_sign(), but can\r
 471  *                  return early and restart according to the limit set with\r
 472  *                  \c mbedtls_ecp_set_max_ops() to reduce blocking for ECC\r
 473  *                  operations. For RSA, same as \c mbedtls_pk_sign().\r
 474  *\r
 475  * \param ctx       The PK context to use. It must have been set up\r
 476  *                  with a private key.\r
 477  * \param md_alg    Hash algorithm used (see notes)\r
 478  * \param hash      Hash of the message to sign\r
 479  * \param hash_len  Hash length or 0 (see notes)\r
 480  * \param sig       Place to write the signature\r
 481  * \param sig_len   Number of bytes written\r
 482  * \param f_rng     RNG function\r
 483  * \param p_rng     RNG parameter\r
 484  * \param rs_ctx    Restart context (NULL to disable restart)\r
 485  *\r
 486  * \return          See \c mbedtls_pk_sign(), or\r
 487  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of\r
 488  *                  operations was reached: see \c mbedtls_ecp_set_max_ops().\r
 489  */\r
 490 int mbedtls_pk_sign_restartable( mbedtls_pk_context *ctx,\r
 491              mbedtls_md_type_t md_alg,\r
 492              const unsigned char *hash, size_t hash_len,\r
 493              unsigned char *sig, size_t *sig_len,\r
 494              int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,\r
 495              mbedtls_pk_restart_ctx *rs_ctx );\r
 496 \r
 497 /**\r
 498  * \brief           Decrypt message (including padding if relevant).\r
 499  *\r
 500  * \param ctx       The PK context to use. It must have been set up\r
 501  *                  with a private key.\r
 502  * \param input     Input to decrypt\r
 503  * \param ilen      Input size\r
 504  * \param output    Decrypted output\r
 505  * \param olen      Decrypted message length\r
 506  * \param osize     Size of the output buffer\r
 507  * \param f_rng     RNG function\r
 508  * \param p_rng     RNG parameter\r
 509  *\r
 510  * \note            For RSA keys, the default padding type is PKCS#1 v1.5.\r
 511  *\r
 512  * \return          0 on success, or a specific error code.\r
 513  */\r
 514 int mbedtls_pk_decrypt( mbedtls_pk_context *ctx,\r
 515                 const unsigned char *input, size_t ilen,\r
 516                 unsigned char *output, size_t *olen, size_t osize,\r
 517                 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );\r
 518 \r
 519 /**\r
 520  * \brief           Encrypt message (including padding if relevant).\r
 521  *\r
 522  * \param ctx       The PK context to use. It must have been set up.\r
 523  * \param input     Message to encrypt\r
 524  * \param ilen      Message size\r
 525  * \param output    Encrypted output\r
 526  * \param olen      Encrypted output length\r
 527  * \param osize     Size of the output buffer\r
 528  * \param f_rng     RNG function\r
 529  * \param p_rng     RNG parameter\r
 530  *\r
 531  * \note            For RSA keys, the default padding type is PKCS#1 v1.5.\r
 532  *\r
 533  * \return          0 on success, or a specific error code.\r
 534  */\r
 535 int mbedtls_pk_encrypt( mbedtls_pk_context *ctx,\r
 536                 const unsigned char *input, size_t ilen,\r
 537                 unsigned char *output, size_t *olen, size_t osize,\r
 538                 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );\r
 539 \r
 540 /**\r
 541  * \brief           Check if a public-private pair of keys matches.\r
 542  *\r
 543  * \param pub       Context holding a public key.\r
 544  * \param prv       Context holding a private (and public) key.\r
 545  *\r
 546  * \return          \c 0 on success (keys were checked and match each other).\r
 547  * \return          #MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE if the keys could not\r
 548  *                  be checked - in that case they may or may not match.\r
 549  * \return          #MBEDTLS_ERR_PK_BAD_INPUT_DATA if a context is invalid.\r
 550  * \return          Another non-zero value if the keys do not match.\r
 551  */\r
 552 int mbedtls_pk_check_pair( const mbedtls_pk_context *pub, const mbedtls_pk_context *prv );\r
 553 \r
 554 /**\r
 555  * \brief           Export debug information\r
 556  *\r
 557  * \param ctx       The PK context to use. It must have been initialized.\r
 558  * \param items     Place to write debug items\r
 559  *\r
 560  * \return          0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA\r
 561  */\r
 562 int mbedtls_pk_debug( const mbedtls_pk_context *ctx, mbedtls_pk_debug_item *items );\r
 563 \r
 564 /**\r
 565  * \brief           Access the type name\r
 566  *\r
 567  * \param ctx       The PK context to use. It must have been initialized.\r
 568  *\r
 569  * \return          Type name on success, or "invalid PK"\r
 570  */\r
 571 const char * mbedtls_pk_get_name( const mbedtls_pk_context *ctx );\r
 572 \r
 573 /**\r
 574  * \brief           Get the key type\r
 575  *\r
 576  * \param ctx       The PK context to use. It must have been initialized.\r
 577  *\r
 578  * \return          Type on success.\r
 579  * \return          #MBEDTLS_PK_NONE for a context that has not been set up.\r
 580  */\r
 581 mbedtls_pk_type_t mbedtls_pk_get_type( const mbedtls_pk_context *ctx );\r
 582 \r
 583 #if defined(MBEDTLS_PK_PARSE_C)\r
 584 /** \ingroup pk_module */\r
 585 /**\r
 586  * \brief           Parse a private key in PEM or DER format\r
 587  *\r
 588  * \param ctx       The PK context to fill. It must have been initialized\r
 589  *                  but not set up.\r
 590  * \param key       Input buffer to parse.\r
 591  *                  The buffer must contain the input exactly, with no\r
 592  *                  extra trailing material. For PEM, the buffer must\r
 593  *                  contain a null-terminated string.\r
 594  * \param keylen    Size of \b key in bytes.\r
 595  *                  For PEM data, this includes the terminating null byte,\r
 596  *                  so \p keylen must be equal to `strlen(key) + 1`.\r
 597  * \param pwd       Optional password for decryption.\r
 598  *                  Pass \c NULL if expecting a non-encrypted key.\r
 599  *                  Pass a string of \p pwdlen bytes if expecting an encrypted\r
 600  *                  key; a non-encrypted key will also be accepted.\r
 601  *                  The empty password is not supported.\r
 602  * \param pwdlen    Size of the password in bytes.\r
 603  *                  Ignored if \p pwd is \c NULL.\r
 604  *\r
 605  * \note            On entry, ctx must be empty, either freshly initialised\r
 606  *                  with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a\r
 607  *                  specific key type, check the result with mbedtls_pk_can_do().\r
 608  *\r
 609  * \note            The key is also checked for correctness.\r
 610  *\r
 611  * \return          0 if successful, or a specific PK or PEM error code\r
 612  */\r
 613 int mbedtls_pk_parse_key( mbedtls_pk_context *ctx,\r
 614                   const unsigned char *key, size_t keylen,\r
 615                   const unsigned char *pwd, size_t pwdlen );\r
 616 \r
 617 /** \ingroup pk_module */\r
 618 /**\r
 619  * \brief           Parse a public key in PEM or DER format\r
 620  *\r
 621  * \param ctx       The PK context to fill. It must have been initialized\r
 622  *                  but not set up.\r
 623  * \param key       Input buffer to parse.\r
 624  *                  The buffer must contain the input exactly, with no\r
 625  *                  extra trailing material. For PEM, the buffer must\r
 626  *                  contain a null-terminated string.\r
 627  * \param keylen    Size of \b key in bytes.\r
 628  *                  For PEM data, this includes the terminating null byte,\r
 629  *                  so \p keylen must be equal to `strlen(key) + 1`.\r
 630  *\r
 631  * \note            On entry, ctx must be empty, either freshly initialised\r
 632  *                  with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a\r
 633  *                  specific key type, check the result with mbedtls_pk_can_do().\r
 634  *\r
 635  * \note            The key is also checked for correctness.\r
 636  *\r
 637  * \return          0 if successful, or a specific PK or PEM error code\r
 638  */\r
 639 int mbedtls_pk_parse_public_key( mbedtls_pk_context *ctx,\r
 640                          const unsigned char *key, size_t keylen );\r
 641 \r
 642 #if defined(MBEDTLS_FS_IO)\r
 643 /** \ingroup pk_module */\r
 644 /**\r
 645  * \brief           Load and parse a private key\r
 646  *\r
 647  * \param ctx       The PK context to fill. It must have been initialized\r
 648  *                  but not set up.\r
 649  * \param path      filename to read the private key from\r
 650  * \param password  Optional password to decrypt the file.\r
 651  *                  Pass \c NULL if expecting a non-encrypted key.\r
 652  *                  Pass a null-terminated string if expecting an encrypted\r
 653  *                  key; a non-encrypted key will also be accepted.\r
 654  *                  The empty password is not supported.\r
 655  *\r
 656  * \note            On entry, ctx must be empty, either freshly initialised\r
 657  *                  with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a\r
 658  *                  specific key type, check the result with mbedtls_pk_can_do().\r
 659  *\r
 660  * \note            The key is also checked for correctness.\r
 661  *\r
 662  * \return          0 if successful, or a specific PK or PEM error code\r
 663  */\r
 664 int mbedtls_pk_parse_keyfile( mbedtls_pk_context *ctx,\r
 665                       const char *path, const char *password );\r
 666 \r
 667 /** \ingroup pk_module */\r
 668 /**\r
 669  * \brief           Load and parse a public key\r
 670  *\r
 671  * \param ctx       The PK context to fill. It must have been initialized\r
 672  *                  but not set up.\r
 673  * \param path      filename to read the public key from\r
 674  *\r
 675  * \note            On entry, ctx must be empty, either freshly initialised\r
 676  *                  with mbedtls_pk_init() or reset with mbedtls_pk_free(). If\r
 677  *                  you need a specific key type, check the result with\r
 678  *                  mbedtls_pk_can_do().\r
 679  *\r
 680  * \note            The key is also checked for correctness.\r
 681  *\r
 682  * \return          0 if successful, or a specific PK or PEM error code\r
 683  */\r
 684 int mbedtls_pk_parse_public_keyfile( mbedtls_pk_context *ctx, const char *path );\r
 685 #endif /* MBEDTLS_FS_IO */\r
 686 #endif /* MBEDTLS_PK_PARSE_C */\r
 687 \r
 688 #if defined(MBEDTLS_PK_WRITE_C)\r
 689 /**\r
 690  * \brief           Write a private key to a PKCS#1 or SEC1 DER structure\r
 691  *                  Note: data is written at the end of the buffer! Use the\r
 692  *                        return value to determine where you should start\r
 693  *                        using the buffer\r
 694  *\r
 695  * \param ctx       PK context which must contain a valid private key.\r
 696  * \param buf       buffer to write to\r
 697  * \param size      size of the buffer\r
 698  *\r
 699  * \return          length of data written if successful, or a specific\r
 700  *                  error code\r
 701  */\r
 702 int mbedtls_pk_write_key_der( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );\r
 703 \r
 704 /**\r
 705  * \brief           Write a public key to a SubjectPublicKeyInfo DER structure\r
 706  *                  Note: data is written at the end of the buffer! Use the\r
 707  *                        return value to determine where you should start\r
 708  *                        using the buffer\r
 709  *\r
 710  * \param ctx       PK context which must contain a valid public or private key.\r
 711  * \param buf       buffer to write to\r
 712  * \param size      size of the buffer\r
 713  *\r
 714  * \return          length of data written if successful, or a specific\r
 715  *                  error code\r
 716  */\r
 717 int mbedtls_pk_write_pubkey_der( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );\r
 718 \r
 719 #if defined(MBEDTLS_PEM_WRITE_C)\r
 720 /**\r
 721  * \brief           Write a public key to a PEM string\r
 722  *\r
 723  * \param ctx       PK context which must contain a valid public or private key.\r
 724  * \param buf       Buffer to write to. The output includes a\r
 725  *                  terminating null byte.\r
 726  * \param size      Size of the buffer in bytes.\r
 727  *\r
 728  * \return          0 if successful, or a specific error code\r
 729  */\r
 730 int mbedtls_pk_write_pubkey_pem( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );\r
 731 \r
 732 /**\r
 733  * \brief           Write a private key to a PKCS#1 or SEC1 PEM string\r
 734  *\r
 735  * \param ctx       PK context which must contain a valid private key.\r
 736  * \param buf       Buffer to write to. The output includes a\r
 737  *                  terminating null byte.\r
 738  * \param size      Size of the buffer in bytes.\r
 739  *\r
 740  * \return          0 if successful, or a specific error code\r
 741  */\r
 742 int mbedtls_pk_write_key_pem( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );\r
 743 #endif /* MBEDTLS_PEM_WRITE_C */\r
 744 #endif /* MBEDTLS_PK_WRITE_C */\r
 745 \r
 746 /*\r
 747  * WARNING: Low-level functions. You probably do not want to use these unless\r
 748  *          you are certain you do ;)\r
 749  */\r
 750 \r
 751 #if defined(MBEDTLS_PK_PARSE_C)\r
 752 /**\r
 753  * \brief           Parse a SubjectPublicKeyInfo DER structure\r
 754  *\r
 755  * \param p         the position in the ASN.1 data\r
 756  * \param end       end of the buffer\r
 757  * \param pk        The PK context to fill. It must have been initialized\r
 758  *                  but not set up.\r
 759  *\r
 760  * \return          0 if successful, or a specific PK error code\r
 761  */\r
 762 int mbedtls_pk_parse_subpubkey( unsigned char **p, const unsigned char *end,\r
 763                         mbedtls_pk_context *pk );\r
 764 #endif /* MBEDTLS_PK_PARSE_C */\r
 765 \r
 766 #if defined(MBEDTLS_PK_WRITE_C)\r
 767 /**\r
 768  * \brief           Write a subjectPublicKey to ASN.1 data\r
 769  *                  Note: function works backwards in data buffer\r
 770  *\r
 771  * \param p         reference to current position pointer\r
 772  * \param start     start of the buffer (for bounds-checking)\r
 773  * \param key       PK context which must contain a valid public or private key.\r
 774  *\r
 775  * \return          the length written or a negative error code\r
 776  */\r
 777 int mbedtls_pk_write_pubkey( unsigned char **p, unsigned char *start,\r
 778                      const mbedtls_pk_context *key );\r
 779 #endif /* MBEDTLS_PK_WRITE_C */\r
 780 \r
 781 /*\r
 782  * Internal module functions. You probably do not want to use these unless you\r
 783  * know you do.\r
 784  */\r
 785 #if defined(MBEDTLS_FS_IO)\r
 786 int mbedtls_pk_load_file( const char *path, unsigned char **buf, size_t *n );\r
 787 #endif\r
 788 \r
 789 #if defined(MBEDTLS_USE_PSA_CRYPTO)\r
 790 /**\r
 791  * \brief           Turn an EC key into an Opaque one\r
 792  *\r
 793  * \warning         This is a temporary utility function for tests. It might\r
 794  *                  change or be removed at any time without notice.\r
 795  *\r
 796  * \note            Only ECDSA keys are supported so far. Signing with the\r
 797  *                  specified hash is the only allowed use of that key.\r
 798  *\r
 799  * \param pk        Input: the EC key to transfer to a PSA key slot.\r
 800  *                  Output: a PK context wrapping that PSA key slot.\r
 801  * \param slot      Output: the chosen slot for storing the key.\r
 802  *                  It's the caller's responsibility to destroy that slot\r
 803  *                  after calling mbedtls_pk_free() on the PK context.\r
 804  * \param hash_alg  The hash algorithm to allow for use with that key.\r
 805  *\r
 806  * \return          \c 0 if successful.\r
 807  * \return          An Mbed TLS error code otherwise.\r
 808  */\r
 809 int mbedtls_pk_wrap_as_opaque( mbedtls_pk_context *pk,\r
 810                                psa_key_handle_t *slot,\r
 811                                psa_algorithm_t hash_alg );\r
 812 #endif /* MBEDTLS_USE_PSA_CRYPTO */\r
 813 \r
 814 #ifdef __cplusplus\r
 815 }\r
 816 #endif\r
 817 \r
 818 #endif /* MBEDTLS_PK_H */\r