Willie Solano / mbedtls-slave-prot-prod

mbed TLS Build

Dependents:   Slave-prot-prod

include/mbedtls/pk.h@0:cdf462088d13, 2017-01-05 (annotated)

Committer:
markrad
Date:
Thu Jan 05 00:18:44 2017 +0000
Revision:
0:cdf462088d13
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
markrad 0:cdf462088d13 1 /**
markrad 0:cdf462088d13 2 * \file pk.h
markrad 0:cdf462088d13 3 *
markrad 0:cdf462088d13 4 * \brief Public Key abstraction layer
markrad 0:cdf462088d13 5 *
markrad 0:cdf462088d13 6 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
markrad 0:cdf462088d13 7 * SPDX-License-Identifier: Apache-2.0
markrad 0:cdf462088d13 8 *
markrad 0:cdf462088d13 9 * Licensed under the Apache License, Version 2.0 (the "License"); you may
markrad 0:cdf462088d13 10 * not use this file except in compliance with the License.
markrad 0:cdf462088d13 11 * You may obtain a copy of the License at
markrad 0:cdf462088d13 12 *
markrad 0:cdf462088d13 13 * http://www.apache.org/licenses/LICENSE-2.0
markrad 0:cdf462088d13 14 *
markrad 0:cdf462088d13 15 * Unless required by applicable law or agreed to in writing, software
markrad 0:cdf462088d13 16 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
markrad 0:cdf462088d13 17 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
markrad 0:cdf462088d13 18 * See the License for the specific language governing permissions and
markrad 0:cdf462088d13 19 * limitations under the License.
markrad 0:cdf462088d13 20 *
markrad 0:cdf462088d13 21 * This file is part of mbed TLS (https://tls.mbed.org)
markrad 0:cdf462088d13 22 */
markrad 0:cdf462088d13 23
markrad 0:cdf462088d13 24 #ifndef MBEDTLS_PK_H
markrad 0:cdf462088d13 25 #define MBEDTLS_PK_H
markrad 0:cdf462088d13 26
markrad 0:cdf462088d13 27 #if !defined(MBEDTLS_CONFIG_FILE)
markrad 0:cdf462088d13 28 #include "config.h"
markrad 0:cdf462088d13 29 #else
markrad 0:cdf462088d13 30 #include MBEDTLS_CONFIG_FILE
markrad 0:cdf462088d13 31 #endif
markrad 0:cdf462088d13 32
markrad 0:cdf462088d13 33 #include "md.h"
markrad 0:cdf462088d13 34
markrad 0:cdf462088d13 35 #if defined(MBEDTLS_RSA_C)
markrad 0:cdf462088d13 36 #include "rsa.h"
markrad 0:cdf462088d13 37 #endif
markrad 0:cdf462088d13 38
markrad 0:cdf462088d13 39 #if defined(MBEDTLS_ECP_C)
markrad 0:cdf462088d13 40 #include "ecp.h"
markrad 0:cdf462088d13 41 #endif
markrad 0:cdf462088d13 42
markrad 0:cdf462088d13 43 #if defined(MBEDTLS_ECDSA_C)
markrad 0:cdf462088d13 44 #include "ecdsa.h"
markrad 0:cdf462088d13 45 #endif
markrad 0:cdf462088d13 46
markrad 0:cdf462088d13 47 #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
markrad 0:cdf462088d13 48 !defined(inline) && !defined(__cplusplus)
markrad 0:cdf462088d13 49 #define inline __inline
markrad 0:cdf462088d13 50 #endif
markrad 0:cdf462088d13 51
markrad 0:cdf462088d13 52 #define MBEDTLS_ERR_PK_ALLOC_FAILED -0x3F80 /**< Memory allocation failed. */
markrad 0:cdf462088d13 53 #define MBEDTLS_ERR_PK_TYPE_MISMATCH -0x3F00 /**< Type mismatch, eg attempt to encrypt with an ECDSA key */
markrad 0:cdf462088d13 54 #define MBEDTLS_ERR_PK_BAD_INPUT_DATA -0x3E80 /**< Bad input parameters to function. */
markrad 0:cdf462088d13 55 #define MBEDTLS_ERR_PK_FILE_IO_ERROR -0x3E00 /**< Read/write of file failed. */
markrad 0:cdf462088d13 56 #define MBEDTLS_ERR_PK_KEY_INVALID_VERSION -0x3D80 /**< Unsupported key version */
markrad 0:cdf462088d13 57 #define MBEDTLS_ERR_PK_KEY_INVALID_FORMAT -0x3D00 /**< Invalid key tag or value. */
markrad 0:cdf462088d13 58 #define MBEDTLS_ERR_PK_UNKNOWN_PK_ALG -0x3C80 /**< Key algorithm is unsupported (only RSA and EC are supported). */
markrad 0:cdf462088d13 59 #define MBEDTLS_ERR_PK_PASSWORD_REQUIRED -0x3C00 /**< Private key password can't be empty. */
markrad 0:cdf462088d13 60 #define MBEDTLS_ERR_PK_PASSWORD_MISMATCH -0x3B80 /**< Given private key password does not allow for correct decryption. */
markrad 0:cdf462088d13 61 #define MBEDTLS_ERR_PK_INVALID_PUBKEY -0x3B00 /**< The pubkey tag or value is invalid (only RSA and EC are supported). */
markrad 0:cdf462088d13 62 #define MBEDTLS_ERR_PK_INVALID_ALG -0x3A80 /**< The algorithm tag or value is invalid. */
markrad 0:cdf462088d13 63 #define MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE -0x3A00 /**< Elliptic curve is unsupported (only NIST curves are supported). */
markrad 0:cdf462088d13 64 #define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE -0x3980 /**< Unavailable feature, e.g. RSA disabled for RSA key. */
markrad 0:cdf462088d13 65 #define MBEDTLS_ERR_PK_SIG_LEN_MISMATCH -0x3900 /**< The signature is valid but its length is less than expected. */
markrad 0:cdf462088d13 66
markrad 0:cdf462088d13 67 #ifdef __cplusplus
markrad 0:cdf462088d13 68 extern "C" {
markrad 0:cdf462088d13 69 #endif
markrad 0:cdf462088d13 70
markrad 0:cdf462088d13 71 /**
markrad 0:cdf462088d13 72 * \brief Public key types
markrad 0:cdf462088d13 73 */
markrad 0:cdf462088d13 74 typedef enum {
markrad 0:cdf462088d13 75 MBEDTLS_PK_NONE=0,
markrad 0:cdf462088d13 76 MBEDTLS_PK_RSA,
markrad 0:cdf462088d13 77 MBEDTLS_PK_ECKEY,
markrad 0:cdf462088d13 78 MBEDTLS_PK_ECKEY_DH,
markrad 0:cdf462088d13 79 MBEDTLS_PK_ECDSA,
markrad 0:cdf462088d13 80 MBEDTLS_PK_RSA_ALT,
markrad 0:cdf462088d13 81 MBEDTLS_PK_RSASSA_PSS,
markrad 0:cdf462088d13 82 } mbedtls_pk_type_t;
markrad 0:cdf462088d13 83
markrad 0:cdf462088d13 84 /**
markrad 0:cdf462088d13 85 * \brief Options for RSASSA-PSS signature verification.
markrad 0:cdf462088d13 86 * See \c mbedtls_rsa_rsassa_pss_verify_ext()
markrad 0:cdf462088d13 87 */
markrad 0:cdf462088d13 88 typedef struct
markrad 0:cdf462088d13 89 {
markrad 0:cdf462088d13 90 mbedtls_md_type_t mgf1_hash_id;
markrad 0:cdf462088d13 91 int expected_salt_len;
markrad 0:cdf462088d13 92
markrad 0:cdf462088d13 93 } mbedtls_pk_rsassa_pss_options;
markrad 0:cdf462088d13 94
markrad 0:cdf462088d13 95 /**
markrad 0:cdf462088d13 96 * \brief Types for interfacing with the debug module
markrad 0:cdf462088d13 97 */
markrad 0:cdf462088d13 98 typedef enum
markrad 0:cdf462088d13 99 {
markrad 0:cdf462088d13 100 MBEDTLS_PK_DEBUG_NONE = 0,
markrad 0:cdf462088d13 101 MBEDTLS_PK_DEBUG_MPI,
markrad 0:cdf462088d13 102 MBEDTLS_PK_DEBUG_ECP,
markrad 0:cdf462088d13 103 } mbedtls_pk_debug_type;
markrad 0:cdf462088d13 104
markrad 0:cdf462088d13 105 /**
markrad 0:cdf462088d13 106 * \brief Item to send to the debug module
markrad 0:cdf462088d13 107 */
markrad 0:cdf462088d13 108 typedef struct
markrad 0:cdf462088d13 109 {
markrad 0:cdf462088d13 110 mbedtls_pk_debug_type type;
markrad 0:cdf462088d13 111 const char *name;
markrad 0:cdf462088d13 112 void *value;
markrad 0:cdf462088d13 113 } mbedtls_pk_debug_item;
markrad 0:cdf462088d13 114
markrad 0:cdf462088d13 115 /** Maximum number of item send for debugging, plus 1 */
markrad 0:cdf462088d13 116 #define MBEDTLS_PK_DEBUG_MAX_ITEMS 3
markrad 0:cdf462088d13 117
markrad 0:cdf462088d13 118 /**
markrad 0:cdf462088d13 119 * \brief Public key information and operations
markrad 0:cdf462088d13 120 */
markrad 0:cdf462088d13 121 typedef struct mbedtls_pk_info_t mbedtls_pk_info_t;
markrad 0:cdf462088d13 122
markrad 0:cdf462088d13 123 /**
markrad 0:cdf462088d13 124 * \brief Public key container
markrad 0:cdf462088d13 125 */
markrad 0:cdf462088d13 126 typedef struct
markrad 0:cdf462088d13 127 {
markrad 0:cdf462088d13 128 const mbedtls_pk_info_t * pk_info; /**< Public key informations */
markrad 0:cdf462088d13 129 void * pk_ctx; /**< Underlying public key context */
markrad 0:cdf462088d13 130 } mbedtls_pk_context;
markrad 0:cdf462088d13 131
markrad 0:cdf462088d13 132 #if defined(MBEDTLS_RSA_C)
markrad 0:cdf462088d13 133 /**
markrad 0:cdf462088d13 134 * Quick access to an RSA context inside a PK context.
markrad 0:cdf462088d13 135 *
markrad 0:cdf462088d13 136 * \warning You must make sure the PK context actually holds an RSA context
markrad 0:cdf462088d13 137 * before using this function!
markrad 0:cdf462088d13 138 */
markrad 0:cdf462088d13 139 static inline mbedtls_rsa_context *mbedtls_pk_rsa( const mbedtls_pk_context pk )
markrad 0:cdf462088d13 140 {
markrad 0:cdf462088d13 141 return( (mbedtls_rsa_context *) (pk).pk_ctx );
markrad 0:cdf462088d13 142 }
markrad 0:cdf462088d13 143 #endif /* MBEDTLS_RSA_C */
markrad 0:cdf462088d13 144
markrad 0:cdf462088d13 145 #if defined(MBEDTLS_ECP_C)
markrad 0:cdf462088d13 146 /**
markrad 0:cdf462088d13 147 * Quick access to an EC context inside a PK context.
markrad 0:cdf462088d13 148 *
markrad 0:cdf462088d13 149 * \warning You must make sure the PK context actually holds an EC context
markrad 0:cdf462088d13 150 * before using this function!
markrad 0:cdf462088d13 151 */
markrad 0:cdf462088d13 152 static inline mbedtls_ecp_keypair *mbedtls_pk_ec( const mbedtls_pk_context pk )
markrad 0:cdf462088d13 153 {
markrad 0:cdf462088d13 154 return( (mbedtls_ecp_keypair *) (pk).pk_ctx );
markrad 0:cdf462088d13 155 }
markrad 0:cdf462088d13 156 #endif /* MBEDTLS_ECP_C */
markrad 0:cdf462088d13 157
markrad 0:cdf462088d13 158 #if defined(MBEDTLS_PK_RSA_ALT_SUPPORT)
markrad 0:cdf462088d13 159 /**
markrad 0:cdf462088d13 160 * \brief Types for RSA-alt abstraction
markrad 0:cdf462088d13 161 */
markrad 0:cdf462088d13 162 typedef int (*mbedtls_pk_rsa_alt_decrypt_func)( void *ctx, int mode, size_t *olen,
markrad 0:cdf462088d13 163 const unsigned char *input, unsigned char *output,
markrad 0:cdf462088d13 164 size_t output_max_len );
markrad 0:cdf462088d13 165 typedef int (*mbedtls_pk_rsa_alt_sign_func)( void *ctx,
markrad 0:cdf462088d13 166 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
markrad 0:cdf462088d13 167 int mode, mbedtls_md_type_t md_alg, unsigned int hashlen,
markrad 0:cdf462088d13 168 const unsigned char *hash, unsigned char *sig );
markrad 0:cdf462088d13 169 typedef size_t (*mbedtls_pk_rsa_alt_key_len_func)( void *ctx );
markrad 0:cdf462088d13 170 #endif /* MBEDTLS_PK_RSA_ALT_SUPPORT */
markrad 0:cdf462088d13 171
markrad 0:cdf462088d13 172 /**
markrad 0:cdf462088d13 173 * \brief Return information associated with the given PK type
markrad 0:cdf462088d13 174 *
markrad 0:cdf462088d13 175 * \param pk_type PK type to search for.
markrad 0:cdf462088d13 176 *
markrad 0:cdf462088d13 177 * \return The PK info associated with the type or NULL if not found.
markrad 0:cdf462088d13 178 */
markrad 0:cdf462088d13 179 const mbedtls_pk_info_t *mbedtls_pk_info_from_type( mbedtls_pk_type_t pk_type );
markrad 0:cdf462088d13 180
markrad 0:cdf462088d13 181 /**
markrad 0:cdf462088d13 182 * \brief Initialize a mbedtls_pk_context (as NONE)
markrad 0:cdf462088d13 183 */
markrad 0:cdf462088d13 184 void mbedtls_pk_init( mbedtls_pk_context *ctx );
markrad 0:cdf462088d13 185
markrad 0:cdf462088d13 186 /**
markrad 0:cdf462088d13 187 * \brief Free a mbedtls_pk_context
markrad 0:cdf462088d13 188 */
markrad 0:cdf462088d13 189 void mbedtls_pk_free( mbedtls_pk_context *ctx );
markrad 0:cdf462088d13 190
markrad 0:cdf462088d13 191 /**
markrad 0:cdf462088d13 192 * \brief Initialize a PK context with the information given
markrad 0:cdf462088d13 193 * and allocates the type-specific PK subcontext.
markrad 0:cdf462088d13 194 *
markrad 0:cdf462088d13 195 * \param ctx Context to initialize. Must be empty (type NONE).
markrad 0:cdf462088d13 196 * \param info Information to use
markrad 0:cdf462088d13 197 *
markrad 0:cdf462088d13 198 * \return 0 on success,
markrad 0:cdf462088d13 199 * MBEDTLS_ERR_PK_BAD_INPUT_DATA on invalid input,
markrad 0:cdf462088d13 200 * MBEDTLS_ERR_PK_ALLOC_FAILED on allocation failure.
markrad 0:cdf462088d13 201 *
markrad 0:cdf462088d13 202 * \note For contexts holding an RSA-alt key, use
markrad 0:cdf462088d13 203 * \c mbedtls_pk_setup_rsa_alt() instead.
markrad 0:cdf462088d13 204 */
markrad 0:cdf462088d13 205 int mbedtls_pk_setup( mbedtls_pk_context *ctx, const mbedtls_pk_info_t *info );
markrad 0:cdf462088d13 206
markrad 0:cdf462088d13 207 #if defined(MBEDTLS_PK_RSA_ALT_SUPPORT)
markrad 0:cdf462088d13 208 /**
markrad 0:cdf462088d13 209 * \brief Initialize an RSA-alt context
markrad 0:cdf462088d13 210 *
markrad 0:cdf462088d13 211 * \param ctx Context to initialize. Must be empty (type NONE).
markrad 0:cdf462088d13 212 * \param key RSA key pointer
markrad 0:cdf462088d13 213 * \param decrypt_func Decryption function
markrad 0:cdf462088d13 214 * \param sign_func Signing function
markrad 0:cdf462088d13 215 * \param key_len_func Function returning key length in bytes
markrad 0:cdf462088d13 216 *
markrad 0:cdf462088d13 217 * \return 0 on success, or MBEDTLS_ERR_PK_BAD_INPUT_DATA if the
markrad 0:cdf462088d13 218 * context wasn't already initialized as RSA_ALT.
markrad 0:cdf462088d13 219 *
markrad 0:cdf462088d13 220 * \note This function replaces \c mbedtls_pk_setup() for RSA-alt.
markrad 0:cdf462088d13 221 */
markrad 0:cdf462088d13 222 int mbedtls_pk_setup_rsa_alt( mbedtls_pk_context *ctx, void * key,
markrad 0:cdf462088d13 223 mbedtls_pk_rsa_alt_decrypt_func decrypt_func,
markrad 0:cdf462088d13 224 mbedtls_pk_rsa_alt_sign_func sign_func,
markrad 0:cdf462088d13 225 mbedtls_pk_rsa_alt_key_len_func key_len_func );
markrad 0:cdf462088d13 226 #endif /* MBEDTLS_PK_RSA_ALT_SUPPORT */
markrad 0:cdf462088d13 227
markrad 0:cdf462088d13 228 /**
markrad 0:cdf462088d13 229 * \brief Get the size in bits of the underlying key
markrad 0:cdf462088d13 230 *
markrad 0:cdf462088d13 231 * \param ctx Context to use
markrad 0:cdf462088d13 232 *
markrad 0:cdf462088d13 233 * \return Key size in bits, or 0 on error
markrad 0:cdf462088d13 234 */
markrad 0:cdf462088d13 235 size_t mbedtls_pk_get_bitlen( const mbedtls_pk_context *ctx );
markrad 0:cdf462088d13 236
markrad 0:cdf462088d13 237 /**
markrad 0:cdf462088d13 238 * \brief Get the length in bytes of the underlying key
markrad 0:cdf462088d13 239 * \param ctx Context to use
markrad 0:cdf462088d13 240 *
markrad 0:cdf462088d13 241 * \return Key length in bytes, or 0 on error
markrad 0:cdf462088d13 242 */
markrad 0:cdf462088d13 243 static inline size_t mbedtls_pk_get_len( const mbedtls_pk_context *ctx )
markrad 0:cdf462088d13 244 {
markrad 0:cdf462088d13 245 return( ( mbedtls_pk_get_bitlen( ctx ) + 7 ) / 8 );
markrad 0:cdf462088d13 246 }
markrad 0:cdf462088d13 247
markrad 0:cdf462088d13 248 /**
markrad 0:cdf462088d13 249 * \brief Tell if a context can do the operation given by type
markrad 0:cdf462088d13 250 *
markrad 0:cdf462088d13 251 * \param ctx Context to test
markrad 0:cdf462088d13 252 * \param type Target type
markrad 0:cdf462088d13 253 *
markrad 0:cdf462088d13 254 * \return 0 if context can't do the operations,
markrad 0:cdf462088d13 255 * 1 otherwise.
markrad 0:cdf462088d13 256 */
markrad 0:cdf462088d13 257 int mbedtls_pk_can_do( const mbedtls_pk_context *ctx, mbedtls_pk_type_t type );
markrad 0:cdf462088d13 258
markrad 0:cdf462088d13 259 /**
markrad 0:cdf462088d13 260 * \brief Verify signature (including padding if relevant).
markrad 0:cdf462088d13 261 *
markrad 0:cdf462088d13 262 * \param ctx PK context to use
markrad 0:cdf462088d13 263 * \param md_alg Hash algorithm used (see notes)
markrad 0:cdf462088d13 264 * \param hash Hash of the message to sign
markrad 0:cdf462088d13 265 * \param hash_len Hash length or 0 (see notes)
markrad 0:cdf462088d13 266 * \param sig Signature to verify
markrad 0:cdf462088d13 267 * \param sig_len Signature length
markrad 0:cdf462088d13 268 *
markrad 0:cdf462088d13 269 * \return 0 on success (signature is valid),
markrad 0:cdf462088d13 270 * MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if the signature is
markrad 0:cdf462088d13 271 * valid but its actual length is less than sig_len,
markrad 0:cdf462088d13 272 * or a specific error code.
markrad 0:cdf462088d13 273 *
markrad 0:cdf462088d13 274 * \note For RSA keys, the default padding type is PKCS#1 v1.5.
markrad 0:cdf462088d13 275 * Use \c mbedtls_pk_verify_ext( MBEDTLS_PK_RSASSA_PSS, ... )
markrad 0:cdf462088d13 276 * to verify RSASSA_PSS signatures.
markrad 0:cdf462088d13 277 *
markrad 0:cdf462088d13 278 * \note If hash_len is 0, then the length associated with md_alg
markrad 0:cdf462088d13 279 * is used instead, or an error returned if it is invalid.
markrad 0:cdf462088d13 280 *
markrad 0:cdf462088d13 281 * \note md_alg may be MBEDTLS_MD_NONE, only if hash_len != 0
markrad 0:cdf462088d13 282 */
markrad 0:cdf462088d13 283 int mbedtls_pk_verify( mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
markrad 0:cdf462088d13 284 const unsigned char *hash, size_t hash_len,
markrad 0:cdf462088d13 285 const unsigned char *sig, size_t sig_len );
markrad 0:cdf462088d13 286
markrad 0:cdf462088d13 287 /**
markrad 0:cdf462088d13 288 * \brief Verify signature, with options.
markrad 0:cdf462088d13 289 * (Includes verification of the padding depending on type.)
markrad 0:cdf462088d13 290 *
markrad 0:cdf462088d13 291 * \param type Signature type (inc. possible padding type) to verify
markrad 0:cdf462088d13 292 * \param options Pointer to type-specific options, or NULL
markrad 0:cdf462088d13 293 * \param ctx PK context to use
markrad 0:cdf462088d13 294 * \param md_alg Hash algorithm used (see notes)
markrad 0:cdf462088d13 295 * \param hash Hash of the message to sign
markrad 0:cdf462088d13 296 * \param hash_len Hash length or 0 (see notes)
markrad 0:cdf462088d13 297 * \param sig Signature to verify
markrad 0:cdf462088d13 298 * \param sig_len Signature length
markrad 0:cdf462088d13 299 *
markrad 0:cdf462088d13 300 * \return 0 on success (signature is valid),
markrad 0:cdf462088d13 301 * MBEDTLS_ERR_PK_TYPE_MISMATCH if the PK context can't be
markrad 0:cdf462088d13 302 * used for this type of signatures,
markrad 0:cdf462088d13 303 * MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if the signature is
markrad 0:cdf462088d13 304 * valid but its actual length is less than sig_len,
markrad 0:cdf462088d13 305 * or a specific error code.
markrad 0:cdf462088d13 306 *
markrad 0:cdf462088d13 307 * \note If hash_len is 0, then the length associated with md_alg
markrad 0:cdf462088d13 308 * is used instead, or an error returned if it is invalid.
markrad 0:cdf462088d13 309 *
markrad 0:cdf462088d13 310 * \note md_alg may be MBEDTLS_MD_NONE, only if hash_len != 0
markrad 0:cdf462088d13 311 *
markrad 0:cdf462088d13 312 * \note If type is MBEDTLS_PK_RSASSA_PSS, then options must point
markrad 0:cdf462088d13 313 * to a mbedtls_pk_rsassa_pss_options structure,
markrad 0:cdf462088d13 314 * otherwise it must be NULL.
markrad 0:cdf462088d13 315 */
markrad 0:cdf462088d13 316 int mbedtls_pk_verify_ext( mbedtls_pk_type_t type, const void *options,
markrad 0:cdf462088d13 317 mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
markrad 0:cdf462088d13 318 const unsigned char *hash, size_t hash_len,
markrad 0:cdf462088d13 319 const unsigned char *sig, size_t sig_len );
markrad 0:cdf462088d13 320
markrad 0:cdf462088d13 321 /**
markrad 0:cdf462088d13 322 * \brief Make signature, including padding if relevant.
markrad 0:cdf462088d13 323 *
markrad 0:cdf462088d13 324 * \param ctx PK context to use - must hold a private key
markrad 0:cdf462088d13 325 * \param md_alg Hash algorithm used (see notes)
markrad 0:cdf462088d13 326 * \param hash Hash of the message to sign
markrad 0:cdf462088d13 327 * \param hash_len Hash length or 0 (see notes)
markrad 0:cdf462088d13 328 * \param sig Place to write the signature
markrad 0:cdf462088d13 329 * \param sig_len Number of bytes written
markrad 0:cdf462088d13 330 * \param f_rng RNG function
markrad 0:cdf462088d13 331 * \param p_rng RNG parameter
markrad 0:cdf462088d13 332 *
markrad 0:cdf462088d13 333 * \return 0 on success, or a specific error code.
markrad 0:cdf462088d13 334 *
markrad 0:cdf462088d13 335 * \note For RSA keys, the default padding type is PKCS#1 v1.5.
markrad 0:cdf462088d13 336 * There is no interface in the PK module to make RSASSA-PSS
markrad 0:cdf462088d13 337 * signatures yet.
markrad 0:cdf462088d13 338 *
markrad 0:cdf462088d13 339 * \note If hash_len is 0, then the length associated with md_alg
markrad 0:cdf462088d13 340 * is used instead, or an error returned if it is invalid.
markrad 0:cdf462088d13 341 *
markrad 0:cdf462088d13 342 * \note For RSA, md_alg may be MBEDTLS_MD_NONE if hash_len != 0.
markrad 0:cdf462088d13 343 * For ECDSA, md_alg may never be MBEDTLS_MD_NONE.
markrad 0:cdf462088d13 344 */
markrad 0:cdf462088d13 345 int mbedtls_pk_sign( mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
markrad 0:cdf462088d13 346 const unsigned char *hash, size_t hash_len,
markrad 0:cdf462088d13 347 unsigned char *sig, size_t *sig_len,
markrad 0:cdf462088d13 348 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
markrad 0:cdf462088d13 349
markrad 0:cdf462088d13 350 /**
markrad 0:cdf462088d13 351 * \brief Decrypt message (including padding if relevant).
markrad 0:cdf462088d13 352 *
markrad 0:cdf462088d13 353 * \param ctx PK context to use - must hold a private key
markrad 0:cdf462088d13 354 * \param input Input to decrypt
markrad 0:cdf462088d13 355 * \param ilen Input size
markrad 0:cdf462088d13 356 * \param output Decrypted output
markrad 0:cdf462088d13 357 * \param olen Decrypted message length
markrad 0:cdf462088d13 358 * \param osize Size of the output buffer
markrad 0:cdf462088d13 359 * \param f_rng RNG function
markrad 0:cdf462088d13 360 * \param p_rng RNG parameter
markrad 0:cdf462088d13 361 *
markrad 0:cdf462088d13 362 * \note For RSA keys, the default padding type is PKCS#1 v1.5.
markrad 0:cdf462088d13 363 *
markrad 0:cdf462088d13 364 * \return 0 on success, or a specific error code.
markrad 0:cdf462088d13 365 */
markrad 0:cdf462088d13 366 int mbedtls_pk_decrypt( mbedtls_pk_context *ctx,
markrad 0:cdf462088d13 367 const unsigned char *input, size_t ilen,
markrad 0:cdf462088d13 368 unsigned char *output, size_t *olen, size_t osize,
markrad 0:cdf462088d13 369 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
markrad 0:cdf462088d13 370
markrad 0:cdf462088d13 371 /**
markrad 0:cdf462088d13 372 * \brief Encrypt message (including padding if relevant).
markrad 0:cdf462088d13 373 *
markrad 0:cdf462088d13 374 * \param ctx PK context to use
markrad 0:cdf462088d13 375 * \param input Message to encrypt
markrad 0:cdf462088d13 376 * \param ilen Message size
markrad 0:cdf462088d13 377 * \param output Encrypted output
markrad 0:cdf462088d13 378 * \param olen Encrypted output length
markrad 0:cdf462088d13 379 * \param osize Size of the output buffer
markrad 0:cdf462088d13 380 * \param f_rng RNG function
markrad 0:cdf462088d13 381 * \param p_rng RNG parameter
markrad 0:cdf462088d13 382 *
markrad 0:cdf462088d13 383 * \note For RSA keys, the default padding type is PKCS#1 v1.5.
markrad 0:cdf462088d13 384 *
markrad 0:cdf462088d13 385 * \return 0 on success, or a specific error code.
markrad 0:cdf462088d13 386 */
markrad 0:cdf462088d13 387 int mbedtls_pk_encrypt( mbedtls_pk_context *ctx,
markrad 0:cdf462088d13 388 const unsigned char *input, size_t ilen,
markrad 0:cdf462088d13 389 unsigned char *output, size_t *olen, size_t osize,
markrad 0:cdf462088d13 390 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
markrad 0:cdf462088d13 391
markrad 0:cdf462088d13 392 /**
markrad 0:cdf462088d13 393 * \brief Check if a public-private pair of keys matches.
markrad 0:cdf462088d13 394 *
markrad 0:cdf462088d13 395 * \param pub Context holding a public key.
markrad 0:cdf462088d13 396 * \param prv Context holding a private (and public) key.
markrad 0:cdf462088d13 397 *
markrad 0:cdf462088d13 398 * \return 0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA
markrad 0:cdf462088d13 399 */
markrad 0:cdf462088d13 400 int mbedtls_pk_check_pair( const mbedtls_pk_context *pub, const mbedtls_pk_context *prv );
markrad 0:cdf462088d13 401
markrad 0:cdf462088d13 402 /**
markrad 0:cdf462088d13 403 * \brief Export debug information
markrad 0:cdf462088d13 404 *
markrad 0:cdf462088d13 405 * \param ctx Context to use
markrad 0:cdf462088d13 406 * \param items Place to write debug items
markrad 0:cdf462088d13 407 *
markrad 0:cdf462088d13 408 * \return 0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA
markrad 0:cdf462088d13 409 */
markrad 0:cdf462088d13 410 int mbedtls_pk_debug( const mbedtls_pk_context *ctx, mbedtls_pk_debug_item *items );
markrad 0:cdf462088d13 411
markrad 0:cdf462088d13 412 /**
markrad 0:cdf462088d13 413 * \brief Access the type name
markrad 0:cdf462088d13 414 *
markrad 0:cdf462088d13 415 * \param ctx Context to use
markrad 0:cdf462088d13 416 *
markrad 0:cdf462088d13 417 * \return Type name on success, or "invalid PK"
markrad 0:cdf462088d13 418 */
markrad 0:cdf462088d13 419 const char * mbedtls_pk_get_name( const mbedtls_pk_context *ctx );
markrad 0:cdf462088d13 420
markrad 0:cdf462088d13 421 /**
markrad 0:cdf462088d13 422 * \brief Get the key type
markrad 0:cdf462088d13 423 *
markrad 0:cdf462088d13 424 * \param ctx Context to use
markrad 0:cdf462088d13 425 *
markrad 0:cdf462088d13 426 * \return Type on success, or MBEDTLS_PK_NONE
markrad 0:cdf462088d13 427 */
markrad 0:cdf462088d13 428 mbedtls_pk_type_t mbedtls_pk_get_type( const mbedtls_pk_context *ctx );
markrad 0:cdf462088d13 429
markrad 0:cdf462088d13 430 #if defined(MBEDTLS_PK_PARSE_C)
markrad 0:cdf462088d13 431 /** \ingroup pk_module */
markrad 0:cdf462088d13 432 /**
markrad 0:cdf462088d13 433 * \brief Parse a private key in PEM or DER format
markrad 0:cdf462088d13 434 *
markrad 0:cdf462088d13 435 * \param ctx key to be initialized
markrad 0:cdf462088d13 436 * \param key input buffer
markrad 0:cdf462088d13 437 * \param keylen size of the buffer
markrad 0:cdf462088d13 438 * (including the terminating null byte for PEM data)
markrad 0:cdf462088d13 439 * \param pwd password for decryption (optional)
markrad 0:cdf462088d13 440 * \param pwdlen size of the password
markrad 0:cdf462088d13 441 *
markrad 0:cdf462088d13 442 * \note On entry, ctx must be empty, either freshly initialised
markrad 0:cdf462088d13 443 * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
markrad 0:cdf462088d13 444 * specific key type, check the result with mbedtls_pk_can_do().
markrad 0:cdf462088d13 445 *
markrad 0:cdf462088d13 446 * \note The key is also checked for correctness.
markrad 0:cdf462088d13 447 *
markrad 0:cdf462088d13 448 * \return 0 if successful, or a specific PK or PEM error code
markrad 0:cdf462088d13 449 */
markrad 0:cdf462088d13 450 int mbedtls_pk_parse_key( mbedtls_pk_context *ctx,
markrad 0:cdf462088d13 451 const unsigned char *key, size_t keylen,
markrad 0:cdf462088d13 452 const unsigned char *pwd, size_t pwdlen );
markrad 0:cdf462088d13 453
markrad 0:cdf462088d13 454 /** \ingroup pk_module */
markrad 0:cdf462088d13 455 /**
markrad 0:cdf462088d13 456 * \brief Parse a public key in PEM or DER format
markrad 0:cdf462088d13 457 *
markrad 0:cdf462088d13 458 * \param ctx key to be initialized
markrad 0:cdf462088d13 459 * \param key input buffer
markrad 0:cdf462088d13 460 * \param keylen size of the buffer
markrad 0:cdf462088d13 461 * (including the terminating null byte for PEM data)
markrad 0:cdf462088d13 462 *
markrad 0:cdf462088d13 463 * \note On entry, ctx must be empty, either freshly initialised
markrad 0:cdf462088d13 464 * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
markrad 0:cdf462088d13 465 * specific key type, check the result with mbedtls_pk_can_do().
markrad 0:cdf462088d13 466 *
markrad 0:cdf462088d13 467 * \note The key is also checked for correctness.
markrad 0:cdf462088d13 468 *
markrad 0:cdf462088d13 469 * \return 0 if successful, or a specific PK or PEM error code
markrad 0:cdf462088d13 470 */
markrad 0:cdf462088d13 471 int mbedtls_pk_parse_public_key( mbedtls_pk_context *ctx,
markrad 0:cdf462088d13 472 const unsigned char *key, size_t keylen );
markrad 0:cdf462088d13 473
markrad 0:cdf462088d13 474 #if defined(MBEDTLS_FS_IO)
markrad 0:cdf462088d13 475 /** \ingroup pk_module */
markrad 0:cdf462088d13 476 /**
markrad 0:cdf462088d13 477 * \brief Load and parse a private key
markrad 0:cdf462088d13 478 *
markrad 0:cdf462088d13 479 * \param ctx key to be initialized
markrad 0:cdf462088d13 480 * \param path filename to read the private key from
markrad 0:cdf462088d13 481 * \param password password to decrypt the file (can be NULL)
markrad 0:cdf462088d13 482 *
markrad 0:cdf462088d13 483 * \note On entry, ctx must be empty, either freshly initialised
markrad 0:cdf462088d13 484 * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
markrad 0:cdf462088d13 485 * specific key type, check the result with mbedtls_pk_can_do().
markrad 0:cdf462088d13 486 *
markrad 0:cdf462088d13 487 * \note The key is also checked for correctness.
markrad 0:cdf462088d13 488 *
markrad 0:cdf462088d13 489 * \return 0 if successful, or a specific PK or PEM error code
markrad 0:cdf462088d13 490 */
markrad 0:cdf462088d13 491 int mbedtls_pk_parse_keyfile( mbedtls_pk_context *ctx,
markrad 0:cdf462088d13 492 const char *path, const char *password );
markrad 0:cdf462088d13 493
markrad 0:cdf462088d13 494 /** \ingroup pk_module */
markrad 0:cdf462088d13 495 /**
markrad 0:cdf462088d13 496 * \brief Load and parse a public key
markrad 0:cdf462088d13 497 *
markrad 0:cdf462088d13 498 * \param ctx key to be initialized
markrad 0:cdf462088d13 499 * \param path filename to read the public key from
markrad 0:cdf462088d13 500 *
markrad 0:cdf462088d13 501 * \note On entry, ctx must be empty, either freshly initialised
markrad 0:cdf462088d13 502 * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If
markrad 0:cdf462088d13 503 * you need a specific key type, check the result with
markrad 0:cdf462088d13 504 * mbedtls_pk_can_do().
markrad 0:cdf462088d13 505 *
markrad 0:cdf462088d13 506 * \note The key is also checked for correctness.
markrad 0:cdf462088d13 507 *
markrad 0:cdf462088d13 508 * \return 0 if successful, or a specific PK or PEM error code
markrad 0:cdf462088d13 509 */
markrad 0:cdf462088d13 510 int mbedtls_pk_parse_public_keyfile( mbedtls_pk_context *ctx, const char *path );
markrad 0:cdf462088d13 511 #endif /* MBEDTLS_FS_IO */
markrad 0:cdf462088d13 512 #endif /* MBEDTLS_PK_PARSE_C */
markrad 0:cdf462088d13 513
markrad 0:cdf462088d13 514 #if defined(MBEDTLS_PK_WRITE_C)
markrad 0:cdf462088d13 515 /**
markrad 0:cdf462088d13 516 * \brief Write a private key to a PKCS#1 or SEC1 DER structure
markrad 0:cdf462088d13 517 * Note: data is written at the end of the buffer! Use the
markrad 0:cdf462088d13 518 * return value to determine where you should start
markrad 0:cdf462088d13 519 * using the buffer
markrad 0:cdf462088d13 520 *
markrad 0:cdf462088d13 521 * \param ctx private to write away
markrad 0:cdf462088d13 522 * \param buf buffer to write to
markrad 0:cdf462088d13 523 * \param size size of the buffer
markrad 0:cdf462088d13 524 *
markrad 0:cdf462088d13 525 * \return length of data written if successful, or a specific
markrad 0:cdf462088d13 526 * error code
markrad 0:cdf462088d13 527 */
markrad 0:cdf462088d13 528 int mbedtls_pk_write_key_der( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
markrad 0:cdf462088d13 529
markrad 0:cdf462088d13 530 /**
markrad 0:cdf462088d13 531 * \brief Write a public key to a SubjectPublicKeyInfo DER structure
markrad 0:cdf462088d13 532 * Note: data is written at the end of the buffer! Use the
markrad 0:cdf462088d13 533 * return value to determine where you should start
markrad 0:cdf462088d13 534 * using the buffer
markrad 0:cdf462088d13 535 *
markrad 0:cdf462088d13 536 * \param ctx public key to write away
markrad 0:cdf462088d13 537 * \param buf buffer to write to
markrad 0:cdf462088d13 538 * \param size size of the buffer
markrad 0:cdf462088d13 539 *
markrad 0:cdf462088d13 540 * \return length of data written if successful, or a specific
markrad 0:cdf462088d13 541 * error code
markrad 0:cdf462088d13 542 */
markrad 0:cdf462088d13 543 int mbedtls_pk_write_pubkey_der( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
markrad 0:cdf462088d13 544
markrad 0:cdf462088d13 545 #if defined(MBEDTLS_PEM_WRITE_C)
markrad 0:cdf462088d13 546 /**
markrad 0:cdf462088d13 547 * \brief Write a public key to a PEM string
markrad 0:cdf462088d13 548 *
markrad 0:cdf462088d13 549 * \param ctx public key to write away
markrad 0:cdf462088d13 550 * \param buf buffer to write to
markrad 0:cdf462088d13 551 * \param size size of the buffer
markrad 0:cdf462088d13 552 *
markrad 0:cdf462088d13 553 * \return 0 if successful, or a specific error code
markrad 0:cdf462088d13 554 */
markrad 0:cdf462088d13 555 int mbedtls_pk_write_pubkey_pem( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
markrad 0:cdf462088d13 556
markrad 0:cdf462088d13 557 /**
markrad 0:cdf462088d13 558 * \brief Write a private key to a PKCS#1 or SEC1 PEM string
markrad 0:cdf462088d13 559 *
markrad 0:cdf462088d13 560 * \param ctx private to write away
markrad 0:cdf462088d13 561 * \param buf buffer to write to
markrad 0:cdf462088d13 562 * \param size size of the buffer
markrad 0:cdf462088d13 563 *
markrad 0:cdf462088d13 564 * \return 0 if successful, or a specific error code
markrad 0:cdf462088d13 565 */
markrad 0:cdf462088d13 566 int mbedtls_pk_write_key_pem( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
markrad 0:cdf462088d13 567 #endif /* MBEDTLS_PEM_WRITE_C */
markrad 0:cdf462088d13 568 #endif /* MBEDTLS_PK_WRITE_C */
markrad 0:cdf462088d13 569
markrad 0:cdf462088d13 570 /*
markrad 0:cdf462088d13 571 * WARNING: Low-level functions. You probably do not want to use these unless
markrad 0:cdf462088d13 572 * you are certain you do ;)
markrad 0:cdf462088d13 573 */
markrad 0:cdf462088d13 574
markrad 0:cdf462088d13 575 #if defined(MBEDTLS_PK_PARSE_C)
markrad 0:cdf462088d13 576 /**
markrad 0:cdf462088d13 577 * \brief Parse a SubjectPublicKeyInfo DER structure
markrad 0:cdf462088d13 578 *
markrad 0:cdf462088d13 579 * \param p the position in the ASN.1 data
markrad 0:cdf462088d13 580 * \param end end of the buffer
markrad 0:cdf462088d13 581 * \param pk the key to fill
markrad 0:cdf462088d13 582 *
markrad 0:cdf462088d13 583 * \return 0 if successful, or a specific PK error code
markrad 0:cdf462088d13 584 */
markrad 0:cdf462088d13 585 int mbedtls_pk_parse_subpubkey( unsigned char **p, const unsigned char *end,
markrad 0:cdf462088d13 586 mbedtls_pk_context *pk );
markrad 0:cdf462088d13 587 #endif /* MBEDTLS_PK_PARSE_C */
markrad 0:cdf462088d13 588
markrad 0:cdf462088d13 589 #if defined(MBEDTLS_PK_WRITE_C)
markrad 0:cdf462088d13 590 /**
markrad 0:cdf462088d13 591 * \brief Write a subjectPublicKey to ASN.1 data
markrad 0:cdf462088d13 592 * Note: function works backwards in data buffer
markrad 0:cdf462088d13 593 *
markrad 0:cdf462088d13 594 * \param p reference to current position pointer
markrad 0:cdf462088d13 595 * \param start start of the buffer (for bounds-checking)
markrad 0:cdf462088d13 596 * \param key public key to write away
markrad 0:cdf462088d13 597 *
markrad 0:cdf462088d13 598 * \return the length written or a negative error code
markrad 0:cdf462088d13 599 */
markrad 0:cdf462088d13 600 int mbedtls_pk_write_pubkey( unsigned char **p, unsigned char *start,
markrad 0:cdf462088d13 601 const mbedtls_pk_context *key );
markrad 0:cdf462088d13 602 #endif /* MBEDTLS_PK_WRITE_C */
markrad 0:cdf462088d13 603
markrad 0:cdf462088d13 604 /*
markrad 0:cdf462088d13 605 * Internal module functions. You probably do not want to use these unless you
markrad 0:cdf462088d13 606 * know you do.
markrad 0:cdf462088d13 607 */
markrad 0:cdf462088d13 608 #if defined(MBEDTLS_FS_IO)
markrad 0:cdf462088d13 609 int mbedtls_pk_load_file( const char *path, unsigned char **buf, size_t *n );
markrad 0:cdf462088d13 610 #endif
markrad 0:cdf462088d13 611
markrad 0:cdf462088d13 612 #ifdef __cplusplus
markrad 0:cdf462088d13 613 }
markrad 0:cdf462088d13 614 #endif
markrad 0:cdf462088d13 615
markrad 0:cdf462088d13 616 #endif /* MBEDTLS_PK_H */