pk.h

00001 /**
00002  * \file pk.h
00003  *
00004  * \brief Public Key abstraction layer
00005  */
00006 /*
00007  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
00008  *  SPDX-License-Identifier: Apache-2.0
00009  *
00010  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00011  *  not use this file except in compliance with the License.
00012  *  You may obtain a copy of the License at
00013  *
00014  *  http://www.apache.org/licenses/LICENSE-2.0
00015  *
00016  *  Unless required by applicable law or agreed to in writing, software
00017  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00018  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00019  *  See the License for the specific language governing permissions and
00020  *  limitations under the License.
00021  *
00022  *  This file is part of mbed TLS (https://tls.mbed.org)
00023  */
00024 
00025 #ifndef MBEDTLS_PK_H
00026 #define MBEDTLS_PK_H
00027 
00028 #if !defined(MBEDTLS_CONFIG_FILE)
00029 #include "mbedtls/config.h"
00030 #else
00031 #include MBEDTLS_CONFIG_FILE
00032 #endif
00033 
00034 #include "mbedtls/md.h"
00035 
00036 #if defined(MBEDTLS_RSA_C)
00037 #include "mbedtls/rsa.h"
00038 #endif
00039 
00040 #if defined(MBEDTLS_ECP_C)
00041 #include "mbedtls/ecp.h"
00042 #endif
00043 
00044 #if defined(MBEDTLS_ECDSA_C)
00045 #include "mbedtls/ecdsa.h"
00046 #endif
00047 
00048 #if defined(MBEDTLS_USE_PSA_CRYPTO)
00049 #include "psa/crypto.h"
00050 #endif
00051 
00052 #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
00053     !defined(inline) && !defined(__cplusplus)
00054 #define inline __inline
00055 #endif
00056 
00057 #define MBEDTLS_ERR_PK_ALLOC_FAILED        -0x3F80  /**< Memory allocation failed. */
00058 #define MBEDTLS_ERR_PK_TYPE_MISMATCH       -0x3F00  /**< Type mismatch, eg attempt to encrypt with an ECDSA key */
00059 #define MBEDTLS_ERR_PK_BAD_INPUT_DATA      -0x3E80  /**< Bad input parameters to function. */
00060 #define MBEDTLS_ERR_PK_FILE_IO_ERROR       -0x3E00  /**< Read/write of file failed. */
00061 #define MBEDTLS_ERR_PK_KEY_INVALID_VERSION -0x3D80  /**< Unsupported key version */
00062 #define MBEDTLS_ERR_PK_KEY_INVALID_FORMAT  -0x3D00  /**< Invalid key tag or value. */
00063 #define MBEDTLS_ERR_PK_UNKNOWN_PK_ALG      -0x3C80  /**< Key algorithm is unsupported (only RSA and EC are supported). */
00064 #define MBEDTLS_ERR_PK_PASSWORD_REQUIRED   -0x3C00  /**< Private key password can't be empty. */
00065 #define MBEDTLS_ERR_PK_PASSWORD_MISMATCH   -0x3B80  /**< Given private key password does not allow for correct decryption. */
00066 #define MBEDTLS_ERR_PK_INVALID_PUBKEY      -0x3B00  /**< The pubkey tag or value is invalid (only RSA and EC are supported). */
00067 #define MBEDTLS_ERR_PK_INVALID_ALG         -0x3A80  /**< The algorithm tag or value is invalid. */
00068 #define MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE -0x3A00  /**< Elliptic curve is unsupported (only NIST curves are supported). */
00069 #define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE -0x3980  /**< Unavailable feature, e.g. RSA disabled for RSA key. */
00070 #define MBEDTLS_ERR_PK_SIG_LEN_MISMATCH    -0x3900  /**< The buffer contains a valid signature followed by more data. */
00071 
00072 /* MBEDTLS_ERR_PK_HW_ACCEL_FAILED is deprecated and should not be used. */
00073 #define MBEDTLS_ERR_PK_HW_ACCEL_FAILED     -0x3880  /**< PK hardware accelerator failed. */
00074 
00075 #ifdef __cplusplus
00076 extern "C" {
00077 #endif
00078 
00079 /**
00080  * \brief          Public key types
00081  */
00082 typedef enum {
00083     MBEDTLS_PK_NONE=0,
00084     MBEDTLS_PK_RSA,
00085     MBEDTLS_PK_ECKEY,
00086     MBEDTLS_PK_ECKEY_DH,
00087     MBEDTLS_PK_ECDSA,
00088     MBEDTLS_PK_RSA_ALT,
00089     MBEDTLS_PK_RSASSA_PSS,
00090     MBEDTLS_PK_OPAQUE,
00091 } mbedtls_pk_type_t;
00092 
00093 /**
00094  * \brief           Options for RSASSA-PSS signature verification.
00095  *                  See \c mbedtls_rsa_rsassa_pss_verify_ext()
00096  */
00097 typedef struct mbedtls_pk_rsassa_pss_options
00098 {
00099     mbedtls_md_type_t mgf1_hash_id;
00100     int expected_salt_len;
00101 
00102 } mbedtls_pk_rsassa_pss_options;
00103 
00104 /**
00105  * \brief           Types for interfacing with the debug module
00106  */
00107 typedef enum
00108 {
00109     MBEDTLS_PK_DEBUG_NONE = 0,
00110     MBEDTLS_PK_DEBUG_MPI,
00111     MBEDTLS_PK_DEBUG_ECP,
00112 } mbedtls_pk_debug_type;
00113 
00114 /**
00115  * \brief           Item to send to the debug module
00116  */
00117 typedef struct mbedtls_pk_debug_item
00118 {
00119     mbedtls_pk_debug_type type;
00120     const char *name;
00121     void *value;
00122 } mbedtls_pk_debug_item;
00123 
00124 /** Maximum number of item send for debugging, plus 1 */
00125 #define MBEDTLS_PK_DEBUG_MAX_ITEMS 3
00126 
00127 /**
00128  * \brief           Public key information and operations
00129  */
00130 typedef struct mbedtls_pk_info_t mbedtls_pk_info_t;
00131 
00132 /**
00133  * \brief           Public key container
00134  */
00135 typedef struct mbedtls_pk_context
00136 {
00137     const mbedtls_pk_info_t *   pk_info; /**< Public key information         */
00138     void *                      pk_ctx;  /**< Underlying public key context  */
00139 } mbedtls_pk_context;
00140 
00141 #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
00142 /**
00143  * \brief           Context for resuming operations
00144  */
00145 typedef struct
00146 {
00147     const mbedtls_pk_info_t *   pk_info; /**< Public key information         */
00148     void *                      rs_ctx;  /**< Underlying restart context     */
00149 } mbedtls_pk_restart_ctx;
00150 #else /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
00151 /* Now we can declare functions that take a pointer to that */
00152 typedef void mbedtls_pk_restart_ctx;
00153 #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
00154 
00155 #if defined(MBEDTLS_RSA_C)
00156 /**
00157  * Quick access to an RSA context inside a PK context.
00158  *
00159  * \warning You must make sure the PK context actually holds an RSA context
00160  * before using this function!
00161  */
00162 static inline mbedtls_rsa_context *mbedtls_pk_rsa( const mbedtls_pk_context pk )
00163 {
00164     return( (mbedtls_rsa_context *) (pk).pk_ctx );
00165 }
00166 #endif /* MBEDTLS_RSA_C */
00167 
00168 #if defined(MBEDTLS_ECP_C)
00169 /**
00170  * Quick access to an EC context inside a PK context.
00171  *
00172  * \warning You must make sure the PK context actually holds an EC context
00173  * before using this function!
00174  */
00175 static inline mbedtls_ecp_keypair *mbedtls_pk_ec( const mbedtls_pk_context pk )
00176 {
00177     return( (mbedtls_ecp_keypair *) (pk).pk_ctx );
00178 }
00179 #endif /* MBEDTLS_ECP_C */
00180 
00181 #if defined(MBEDTLS_PK_RSA_ALT_SUPPORT)
00182 /**
00183  * \brief           Types for RSA-alt abstraction
00184  */
00185 typedef int (*mbedtls_pk_rsa_alt_decrypt_func)( void *ctx, int mode, size_t *olen,
00186                     const unsigned char *input, unsigned char *output,
00187                     size_t output_max_len );
00188 typedef int (*mbedtls_pk_rsa_alt_sign_func)( void *ctx,
00189                     int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
00190                     int mode, mbedtls_md_type_t md_alg, unsigned int hashlen,
00191                     const unsigned char *hash, unsigned char *sig );
00192 typedef size_t (*mbedtls_pk_rsa_alt_key_len_func)( void *ctx );
00193 #endif /* MBEDTLS_PK_RSA_ALT_SUPPORT */
00194 
00195 /**
00196  * \brief           Return information associated with the given PK type
00197  *
00198  * \param pk_type   PK type to search for.
00199  *
00200  * \return          The PK info associated with the type or NULL if not found.
00201  */
00202 const mbedtls_pk_info_t *mbedtls_pk_info_from_type( mbedtls_pk_type_t pk_type );
00203 
00204 /**
00205  * \brief           Initialize a #mbedtls_pk_context (as NONE).
00206  *
00207  * \param ctx       The context to initialize.
00208  *                  This must not be \c NULL.
00209  */
00210 void mbedtls_pk_init( mbedtls_pk_context *ctx );
00211 
00212 /**
00213  * \brief           Free the components of a #mbedtls_pk_context.
00214  *
00215  * \param ctx       The context to clear. It must have been initialized.
00216  *                  If this is \c NULL, this function does nothing.
00217  *
00218  * \note            For contexts that have been set up with
00219  *                  mbedtls_pk_setup_opaque(), this does not free the underlying
00220  *                  PSA key and you still need to call psa_destroy_key()
00221  *                  independently if you want to destroy that key.
00222  */
00223 void mbedtls_pk_free( mbedtls_pk_context *ctx );
00224 
00225 #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
00226 /**
00227  * \brief           Initialize a restart context
00228  *
00229  * \param ctx       The context to initialize.
00230  *                  This must not be \c NULL.
00231  */
00232 void mbedtls_pk_restart_init( mbedtls_pk_restart_ctx *ctx );
00233 
00234 /**
00235  * \brief           Free the components of a restart context
00236  *
00237  * \param ctx       The context to clear. It must have been initialized.
00238  *                  If this is \c NULL, this function does nothing.
00239  */
00240 void mbedtls_pk_restart_free( mbedtls_pk_restart_ctx *ctx );
00241 #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
00242 
00243 /**
00244  * \brief           Initialize a PK context with the information given
00245  *                  and allocates the type-specific PK subcontext.
00246  *
00247  * \param ctx       Context to initialize. It must not have been set
00248  *                  up yet (type #MBEDTLS_PK_NONE).
00249  * \param info      Information to use
00250  *
00251  * \return          0 on success,
00252  *                  MBEDTLS_ERR_PK_BAD_INPUT_DATA on invalid input,
00253  *                  MBEDTLS_ERR_PK_ALLOC_FAILED on allocation failure.
00254  *
00255  * \note            For contexts holding an RSA-alt key, use
00256  *                  \c mbedtls_pk_setup_rsa_alt() instead.
00257  */
00258 int mbedtls_pk_setup( mbedtls_pk_context *ctx, const mbedtls_pk_info_t *info );
00259 
00260 #if defined(MBEDTLS_USE_PSA_CRYPTO)
00261 /**
00262  * \brief           Initialize a PK context to wrap a PSA key.
00263  *
00264  * \note            This function replaces mbedtls_pk_setup() for contexts
00265  *                  that wrap a (possibly opaque) PSA key instead of
00266  *                  storing and manipulating the key material directly.
00267  *
00268  * \param ctx       The context to initialize. It must be empty (type NONE).
00269  * \param key       The PSA key to wrap, which must hold an ECC key pair
00270  *                  (see notes below).
00271  *
00272  * \note            The wrapped key must remain valid as long as the
00273  *                  wrapping PK context is in use, that is at least between
00274  *                  the point this function is called and the point
00275  *                  mbedtls_pk_free() is called on this context. The wrapped
00276  *                  key might then be independently used or destroyed.
00277  *
00278  * \note            This function is currently only available for ECC key
00279  *                  pairs (that is, ECC keys containing private key material).
00280  *                  Support for other key types may be added later.
00281  *
00282  * \return          \c 0 on success.
00283  * \return          #MBEDTLS_ERR_PK_BAD_INPUT_DATA on invalid input
00284  *                  (context already used, invalid key handle).
00285  * \return          #MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE if the key is not an
00286  *                  ECC key pair.
00287  * \return          #MBEDTLS_ERR_PK_ALLOC_FAILED on allocation failure.
00288  */
00289 int mbedtls_pk_setup_opaque( mbedtls_pk_context *ctx, const psa_key_handle_t key );
00290 #endif /* MBEDTLS_USE_PSA_CRYPTO */
00291 
00292 #if defined(MBEDTLS_PK_RSA_ALT_SUPPORT)
00293 /**
00294  * \brief           Initialize an RSA-alt context
00295  *
00296  * \param ctx       Context to initialize. It must not have been set
00297  *                  up yet (type #MBEDTLS_PK_NONE).
00298  * \param key       RSA key pointer
00299  * \param decrypt_func  Decryption function
00300  * \param sign_func     Signing function
00301  * \param key_len_func  Function returning key length in bytes
00302  *
00303  * \return          0 on success, or MBEDTLS_ERR_PK_BAD_INPUT_DATA if the
00304  *                  context wasn't already initialized as RSA_ALT.
00305  *
00306  * \note            This function replaces \c mbedtls_pk_setup() for RSA-alt.
00307  */
00308 int mbedtls_pk_setup_rsa_alt( mbedtls_pk_context *ctx, void * key,
00309                          mbedtls_pk_rsa_alt_decrypt_func decrypt_func,
00310                          mbedtls_pk_rsa_alt_sign_func sign_func,
00311                          mbedtls_pk_rsa_alt_key_len_func key_len_func );
00312 #endif /* MBEDTLS_PK_RSA_ALT_SUPPORT */
00313 
00314 /**
00315  * \brief           Get the size in bits of the underlying key
00316  *
00317  * \param ctx       The context to query. It must have been initialized.
00318  *
00319  * \return          Key size in bits, or 0 on error
00320  */
00321 size_t mbedtls_pk_get_bitlen( const mbedtls_pk_context *ctx );
00322 
00323 /**
00324  * \brief           Get the length in bytes of the underlying key
00325  *
00326  * \param ctx       The context to query. It must have been initialized.
00327  *
00328  * \return          Key length in bytes, or 0 on error
00329  */
00330 static inline size_t mbedtls_pk_get_len( const mbedtls_pk_context *ctx )
00331 {
00332     return( ( mbedtls_pk_get_bitlen( ctx ) + 7 ) / 8 );
00333 }
00334 
00335 /**
00336  * \brief           Tell if a context can do the operation given by type
00337  *
00338  * \param ctx       The context to query. It must have been initialized.
00339  * \param type      The desired type.
00340  *
00341  * \return          1 if the context can do operations on the given type.
00342  * \return          0 if the context cannot do the operations on the given
00343  *                  type. This is always the case for a context that has
00344  *                  been initialized but not set up, or that has been
00345  *                  cleared with mbedtls_pk_free().
00346  */
00347 int mbedtls_pk_can_do( const mbedtls_pk_context *ctx, mbedtls_pk_type_t type );
00348 
00349 /**
00350  * \brief           Verify signature (including padding if relevant).
00351  *
00352  * \param ctx       The PK context to use. It must have been set up.
00353  * \param md_alg    Hash algorithm used (see notes)
00354  * \param hash      Hash of the message to sign
00355  * \param hash_len  Hash length or 0 (see notes)
00356  * \param sig       Signature to verify
00357  * \param sig_len   Signature length
00358  *
00359  * \return          0 on success (signature is valid),
00360  *                  #MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if there is a valid
00361  *                  signature in sig but its length is less than \p siglen,
00362  *                  or a specific error code.
00363  *
00364  * \note            For RSA keys, the default padding type is PKCS#1 v1.5.
00365  *                  Use \c mbedtls_pk_verify_ext( MBEDTLS_PK_RSASSA_PSS, ... )
00366  *                  to verify RSASSA_PSS signatures.
00367  *
00368  * \note            If hash_len is 0, then the length associated with md_alg
00369  *                  is used instead, or an error returned if it is invalid.
00370  *
00371  * \note            md_alg may be MBEDTLS_MD_NONE, only if hash_len != 0
00372  */
00373 int mbedtls_pk_verify( mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
00374                const unsigned char *hash, size_t hash_len,
00375                const unsigned char *sig, size_t sig_len );
00376 
00377 /**
00378  * \brief           Restartable version of \c mbedtls_pk_verify()
00379  *
00380  * \note            Performs the same job as \c mbedtls_pk_verify(), but can
00381  *                  return early and restart according to the limit set with
00382  *                  \c mbedtls_ecp_set_max_ops() to reduce blocking for ECC
00383  *                  operations. For RSA, same as \c mbedtls_pk_verify().
00384  *
00385  * \param ctx       The PK context to use. It must have been set up.
00386  * \param md_alg    Hash algorithm used (see notes)
00387  * \param hash      Hash of the message to sign
00388  * \param hash_len  Hash length or 0 (see notes)
00389  * \param sig       Signature to verify
00390  * \param sig_len   Signature length
00391  * \param rs_ctx    Restart context (NULL to disable restart)
00392  *
00393  * \return          See \c mbedtls_pk_verify(), or
00394  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
00395  *                  operations was reached: see \c mbedtls_ecp_set_max_ops().
00396  */
00397 int mbedtls_pk_verify_restartable( mbedtls_pk_context *ctx,
00398                mbedtls_md_type_t md_alg,
00399                const unsigned char *hash, size_t hash_len,
00400                const unsigned char *sig, size_t sig_len,
00401                mbedtls_pk_restart_ctx *rs_ctx );
00402 
00403 /**
00404  * \brief           Verify signature, with options.
00405  *                  (Includes verification of the padding depending on type.)
00406  *
00407  * \param type      Signature type (inc. possible padding type) to verify
00408  * \param options   Pointer to type-specific options, or NULL
00409  * \param ctx       The PK context to use. It must have been set up.
00410  * \param md_alg    Hash algorithm used (see notes)
00411  * \param hash      Hash of the message to sign
00412  * \param hash_len  Hash length or 0 (see notes)
00413  * \param sig       Signature to verify
00414  * \param sig_len   Signature length
00415  *
00416  * \return          0 on success (signature is valid),
00417  *                  #MBEDTLS_ERR_PK_TYPE_MISMATCH if the PK context can't be
00418  *                  used for this type of signatures,
00419  *                  #MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if there is a valid
00420  *                  signature in sig but its length is less than \p siglen,
00421  *                  or a specific error code.
00422  *
00423  * \note            If hash_len is 0, then the length associated with md_alg
00424  *                  is used instead, or an error returned if it is invalid.
00425  *
00426  * \note            md_alg may be MBEDTLS_MD_NONE, only if hash_len != 0
00427  *
00428  * \note            If type is MBEDTLS_PK_RSASSA_PSS, then options must point
00429  *                  to a mbedtls_pk_rsassa_pss_options structure,
00430  *                  otherwise it must be NULL.
00431  */
00432 int mbedtls_pk_verify_ext( mbedtls_pk_type_t type, const void *options,
00433                    mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
00434                    const unsigned char *hash, size_t hash_len,
00435                    const unsigned char *sig, size_t sig_len );
00436 
00437 /**
00438  * \brief           Make signature, including padding if relevant.
00439  *
00440  * \param ctx       The PK context to use. It must have been set up
00441  *                  with a private key.
00442  * \param md_alg    Hash algorithm used (see notes)
00443  * \param hash      Hash of the message to sign
00444  * \param hash_len  Hash length or 0 (see notes)
00445  * \param sig       Place to write the signature
00446  * \param sig_len   Number of bytes written
00447  * \param f_rng     RNG function
00448  * \param p_rng     RNG parameter
00449  *
00450  * \return          0 on success, or a specific error code.
00451  *
00452  * \note            For RSA keys, the default padding type is PKCS#1 v1.5.
00453  *                  There is no interface in the PK module to make RSASSA-PSS
00454  *                  signatures yet.
00455  *
00456  * \note            If hash_len is 0, then the length associated with md_alg
00457  *                  is used instead, or an error returned if it is invalid.
00458  *
00459  * \note            For RSA, md_alg may be MBEDTLS_MD_NONE if hash_len != 0.
00460  *                  For ECDSA, md_alg may never be MBEDTLS_MD_NONE.
00461  */
00462 int mbedtls_pk_sign( mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
00463              const unsigned char *hash, size_t hash_len,
00464              unsigned char *sig, size_t *sig_len,
00465              int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
00466 
00467 /**
00468  * \brief           Restartable version of \c mbedtls_pk_sign()
00469  *
00470  * \note            Performs the same job as \c mbedtls_pk_sign(), but can
00471  *                  return early and restart according to the limit set with
00472  *                  \c mbedtls_ecp_set_max_ops() to reduce blocking for ECC
00473  *                  operations. For RSA, same as \c mbedtls_pk_sign().
00474  *
00475  * \param ctx       The PK context to use. It must have been set up
00476  *                  with a private key.
00477  * \param md_alg    Hash algorithm used (see notes)
00478  * \param hash      Hash of the message to sign
00479  * \param hash_len  Hash length or 0 (see notes)
00480  * \param sig       Place to write the signature
00481  * \param sig_len   Number of bytes written
00482  * \param f_rng     RNG function
00483  * \param p_rng     RNG parameter
00484  * \param rs_ctx    Restart context (NULL to disable restart)
00485  *
00486  * \return          See \c mbedtls_pk_sign(), or
00487  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
00488  *                  operations was reached: see \c mbedtls_ecp_set_max_ops().
00489  */
00490 int mbedtls_pk_sign_restartable( mbedtls_pk_context *ctx,
00491              mbedtls_md_type_t md_alg,
00492              const unsigned char *hash, size_t hash_len,
00493              unsigned char *sig, size_t *sig_len,
00494              int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
00495              mbedtls_pk_restart_ctx *rs_ctx );
00496 
00497 /**
00498  * \brief           Decrypt message (including padding if relevant).
00499  *
00500  * \param ctx       The PK context to use. It must have been set up
00501  *                  with a private key.
00502  * \param input     Input to decrypt
00503  * \param ilen      Input size
00504  * \param output    Decrypted output
00505  * \param olen      Decrypted message length
00506  * \param osize     Size of the output buffer
00507  * \param f_rng     RNG function
00508  * \param p_rng     RNG parameter
00509  *
00510  * \note            For RSA keys, the default padding type is PKCS#1 v1.5.
00511  *
00512  * \return          0 on success, or a specific error code.
00513  */
00514 int mbedtls_pk_decrypt( mbedtls_pk_context *ctx,
00515                 const unsigned char *input, size_t ilen,
00516                 unsigned char *output, size_t *olen, size_t osize,
00517                 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
00518 
00519 /**
00520  * \brief           Encrypt message (including padding if relevant).
00521  *
00522  * \param ctx       The PK context to use. It must have been set up.
00523  * \param input     Message to encrypt
00524  * \param ilen      Message size
00525  * \param output    Encrypted output
00526  * \param olen      Encrypted output length
00527  * \param osize     Size of the output buffer
00528  * \param f_rng     RNG function
00529  * \param p_rng     RNG parameter
00530  *
00531  * \note            For RSA keys, the default padding type is PKCS#1 v1.5.
00532  *
00533  * \return          0 on success, or a specific error code.
00534  */
00535 int mbedtls_pk_encrypt( mbedtls_pk_context *ctx,
00536                 const unsigned char *input, size_t ilen,
00537                 unsigned char *output, size_t *olen, size_t osize,
00538                 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
00539 
00540 /**
00541  * \brief           Check if a public-private pair of keys matches.
00542  *
00543  * \param pub       Context holding a public key.
00544  * \param prv       Context holding a private (and public) key.
00545  *
00546  * \return          \c 0 on success (keys were checked and match each other).
00547  * \return          #MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE if the keys could not
00548  *                  be checked - in that case they may or may not match.
00549  * \return          #MBEDTLS_ERR_PK_BAD_INPUT_DATA if a context is invalid.
00550  * \return          Another non-zero value if the keys do not match.
00551  */
00552 int mbedtls_pk_check_pair( const mbedtls_pk_context *pub, const mbedtls_pk_context *prv );
00553 
00554 /**
00555  * \brief           Export debug information
00556  *
00557  * \param ctx       The PK context to use. It must have been initialized.
00558  * \param items     Place to write debug items
00559  *
00560  * \return          0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA
00561  */
00562 int mbedtls_pk_debug( const mbedtls_pk_context *ctx, mbedtls_pk_debug_item *items );
00563 
00564 /**
00565  * \brief           Access the type name
00566  *
00567  * \param ctx       The PK context to use. It must have been initialized.
00568  *
00569  * \return          Type name on success, or "invalid PK"
00570  */
00571 const char * mbedtls_pk_get_name( const mbedtls_pk_context *ctx );
00572 
00573 /**
00574  * \brief           Get the key type
00575  *
00576  * \param ctx       The PK context to use. It must have been initialized.
00577  *
00578  * \return          Type on success.
00579  * \return          #MBEDTLS_PK_NONE for a context that has not been set up.
00580  */
00581 mbedtls_pk_type_t mbedtls_pk_get_type( const mbedtls_pk_context *ctx );
00582 
00583 #if defined(MBEDTLS_PK_PARSE_C)
00584 /** \ingroup pk_module */
00585 /**
00586  * \brief           Parse a private key in PEM or DER format
00587  *
00588  * \param ctx       The PK context to fill. It must have been initialized
00589  *                  but not set up.
00590  * \param key       Input buffer to parse.
00591  *                  The buffer must contain the input exactly, with no
00592  *                  extra trailing material. For PEM, the buffer must
00593  *                  contain a null-terminated string.
00594  * \param keylen    Size of \b key in bytes.
00595  *                  For PEM data, this includes the terminating null byte,
00596  *                  so \p keylen must be equal to `strlen(key) + 1`.
00597  * \param pwd       Optional password for decryption.
00598  *                  Pass \c NULL if expecting a non-encrypted key.
00599  *                  Pass a string of \p pwdlen bytes if expecting an encrypted
00600  *                  key; a non-encrypted key will also be accepted.
00601  *                  The empty password is not supported.
00602  * \param pwdlen    Size of the password in bytes.
00603  *                  Ignored if \p pwd is \c NULL.
00604  *
00605  * \note            On entry, ctx must be empty, either freshly initialised
00606  *                  with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
00607  *                  specific key type, check the result with mbedtls_pk_can_do().
00608  *
00609  * \note            The key is also checked for correctness.
00610  *
00611  * \return          0 if successful, or a specific PK or PEM error code
00612  */
00613 int mbedtls_pk_parse_key( mbedtls_pk_context *ctx,
00614                   const unsigned char *key, size_t keylen,
00615                   const unsigned char *pwd, size_t pwdlen );
00616 
00617 /** \ingroup pk_module */
00618 /**
00619  * \brief           Parse a public key in PEM or DER format
00620  *
00621  * \param ctx       The PK context to fill. It must have been initialized
00622  *                  but not set up.
00623  * \param key       Input buffer to parse.
00624  *                  The buffer must contain the input exactly, with no
00625  *                  extra trailing material. For PEM, the buffer must
00626  *                  contain a null-terminated string.
00627  * \param keylen    Size of \b key in bytes.
00628  *                  For PEM data, this includes the terminating null byte,
00629  *                  so \p keylen must be equal to `strlen(key) + 1`.
00630  *
00631  * \note            On entry, ctx must be empty, either freshly initialised
00632  *                  with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
00633  *                  specific key type, check the result with mbedtls_pk_can_do().
00634  *
00635  * \note            The key is also checked for correctness.
00636  *
00637  * \return          0 if successful, or a specific PK or PEM error code
00638  */
00639 int mbedtls_pk_parse_public_key( mbedtls_pk_context *ctx,
00640                          const unsigned char *key, size_t keylen );
00641 
00642 #if defined(MBEDTLS_FS_IO)
00643 /** \ingroup pk_module */
00644 /**
00645  * \brief           Load and parse a private key
00646  *
00647  * \param ctx       The PK context to fill. It must have been initialized
00648  *                  but not set up.
00649  * \param path      filename to read the private key from
00650  * \param password  Optional password to decrypt the file.
00651  *                  Pass \c NULL if expecting a non-encrypted key.
00652  *                  Pass a null-terminated string if expecting an encrypted
00653  *                  key; a non-encrypted key will also be accepted.
00654  *                  The empty password is not supported.
00655  *
00656  * \note            On entry, ctx must be empty, either freshly initialised
00657  *                  with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
00658  *                  specific key type, check the result with mbedtls_pk_can_do().
00659  *
00660  * \note            The key is also checked for correctness.
00661  *
00662  * \return          0 if successful, or a specific PK or PEM error code
00663  */
00664 int mbedtls_pk_parse_keyfile( mbedtls_pk_context *ctx,
00665                       const char *path, const char *password );
00666 
00667 /** \ingroup pk_module */
00668 /**
00669  * \brief           Load and parse a public key
00670  *
00671  * \param ctx       The PK context to fill. It must have been initialized
00672  *                  but not set up.
00673  * \param path      filename to read the public key from
00674  *
00675  * \note            On entry, ctx must be empty, either freshly initialised
00676  *                  with mbedtls_pk_init() or reset with mbedtls_pk_free(). If
00677  *                  you need a specific key type, check the result with
00678  *                  mbedtls_pk_can_do().
00679  *
00680  * \note            The key is also checked for correctness.
00681  *
00682  * \return          0 if successful, or a specific PK or PEM error code
00683  */
00684 int mbedtls_pk_parse_public_keyfile( mbedtls_pk_context *ctx, const char *path );
00685 #endif /* MBEDTLS_FS_IO */
00686 #endif /* MBEDTLS_PK_PARSE_C */
00687 
00688 #if defined(MBEDTLS_PK_WRITE_C)
00689 /**
00690  * \brief           Write a private key to a PKCS#1 or SEC1 DER structure
00691  *                  Note: data is written at the end of the buffer! Use the
00692  *                        return value to determine where you should start
00693  *                        using the buffer
00694  *
00695  * \param ctx       PK context which must contain a valid private key.
00696  * \param buf       buffer to write to
00697  * \param size      size of the buffer
00698  *
00699  * \return          length of data written if successful, or a specific
00700  *                  error code
00701  */
00702 int mbedtls_pk_write_key_der( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
00703 
00704 /**
00705  * \brief           Write a public key to a SubjectPublicKeyInfo DER structure
00706  *                  Note: data is written at the end of the buffer! Use the
00707  *                        return value to determine where you should start
00708  *                        using the buffer
00709  *
00710  * \param ctx       PK context which must contain a valid public or private key.
00711  * \param buf       buffer to write to
00712  * \param size      size of the buffer
00713  *
00714  * \return          length of data written if successful, or a specific
00715  *                  error code
00716  */
00717 int mbedtls_pk_write_pubkey_der( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
00718 
00719 #if defined(MBEDTLS_PEM_WRITE_C)
00720 /**
00721  * \brief           Write a public key to a PEM string
00722  *
00723  * \param ctx       PK context which must contain a valid public or private key.
00724  * \param buf       Buffer to write to. The output includes a
00725  *                  terminating null byte.
00726  * \param size      Size of the buffer in bytes.
00727  *
00728  * \return          0 if successful, or a specific error code
00729  */
00730 int mbedtls_pk_write_pubkey_pem( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
00731 
00732 /**
00733  * \brief           Write a private key to a PKCS#1 or SEC1 PEM string
00734  *
00735  * \param ctx       PK context which must contain a valid private key.
00736  * \param buf       Buffer to write to. The output includes a
00737  *                  terminating null byte.
00738  * \param size      Size of the buffer in bytes.
00739  *
00740  * \return          0 if successful, or a specific error code
00741  */
00742 int mbedtls_pk_write_key_pem( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
00743 #endif /* MBEDTLS_PEM_WRITE_C */
00744 #endif /* MBEDTLS_PK_WRITE_C */
00745 
00746 /*
00747  * WARNING: Low-level functions. You probably do not want to use these unless
00748  *          you are certain you do ;)
00749  */
00750 
00751 #if defined(MBEDTLS_PK_PARSE_C)
00752 /**
00753  * \brief           Parse a SubjectPublicKeyInfo DER structure
00754  *
00755  * \param p         the position in the ASN.1 data
00756  * \param end       end of the buffer
00757  * \param pk        The PK context to fill. It must have been initialized
00758  *                  but not set up.
00759  *
00760  * \return          0 if successful, or a specific PK error code
00761  */
00762 int mbedtls_pk_parse_subpubkey( unsigned char **p, const unsigned char *end,
00763                         mbedtls_pk_context *pk );
00764 #endif /* MBEDTLS_PK_PARSE_C */
00765 
00766 #if defined(MBEDTLS_PK_WRITE_C)
00767 /**
00768  * \brief           Write a subjectPublicKey to ASN.1 data
00769  *                  Note: function works backwards in data buffer
00770  *
00771  * \param p         reference to current position pointer
00772  * \param start     start of the buffer (for bounds-checking)
00773  * \param key       PK context which must contain a valid public or private key.
00774  *
00775  * \return          the length written or a negative error code
00776  */
00777 int mbedtls_pk_write_pubkey( unsigned char **p, unsigned char *start,
00778                      const mbedtls_pk_context *key );
00779 #endif /* MBEDTLS_PK_WRITE_C */
00780 
00781 /*
00782  * Internal module functions. You probably do not want to use these unless you
00783  * know you do.
00784  */
00785 #if defined(MBEDTLS_FS_IO)
00786 int mbedtls_pk_load_file( const char *path, unsigned char **buf, size_t *n );
00787 #endif
00788 
00789 #if defined(MBEDTLS_USE_PSA_CRYPTO)
00790 /**
00791  * \brief           Turn an EC key into an opaque one.
00792  *
00793  * \warning         This is a temporary utility function for tests. It might
00794  *                  change or be removed at any time without notice.
00795  *
00796  * \note            Only ECDSA keys are supported so far. Signing with the
00797  *                  specified hash is the only allowed use of that key.
00798  *
00799  * \param pk        Input: the EC key to import to a PSA key.
00800  *                  Output: a PK context wrapping that PSA key.
00801  * \param handle    Output: a PSA key handle.
00802  *                  It's the caller's responsibility to call
00803  *                  psa_destroy_key() on that handle after calling
00804  *                  mbedtls_pk_free() on the PK context.
00805  * \param hash_alg  The hash algorithm to allow for use with that key.
00806  *
00807  * \return          \c 0 if successful.
00808  * \return          An Mbed TLS error code otherwise.
00809  */
00810 int mbedtls_pk_wrap_as_opaque( mbedtls_pk_context *pk,
00811                                psa_key_handle_t *handle,
00812                                psa_algorithm_t hash_alg );
00813 #endif /* MBEDTLS_USE_PSA_CRYPTO */
00814 
00815 #ifdef __cplusplus
00816 }
00817 #endif
00818 
00819 #endif /* MBEDTLS_PK_H */