third_party/mbedtls/repo/include/mbedtls/pk.h

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