Doug Anson / mbedTLSLibrary

mbed TLS library

Dependents:   HTTPClient-SSL WS_SERVER

include/polarssl/pk.h@0:137634ff4186, 2015-06-11 (annotated)

Committer:
ansond
Date:
Thu Jun 11 03:27:03 2015 +0000
Revision:
0:137634ff4186
initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
ansond 0:137634ff4186 1 /**
ansond 0:137634ff4186 2 * \file pk.h
ansond 0:137634ff4186 3 *
ansond 0:137634ff4186 4 * \brief Public Key abstraction layer
ansond 0:137634ff4186 5 *
ansond 0:137634ff4186 6 * Copyright (C) 2006-2013, ARM Limited, All Rights Reserved
ansond 0:137634ff4186 7 *
ansond 0:137634ff4186 8 * This file is part of mbed TLS (https://tls.mbed.org)
ansond 0:137634ff4186 9 *
ansond 0:137634ff4186 10 * This program is free software; you can redistribute it and/or modify
ansond 0:137634ff4186 11 * it under the terms of the GNU General Public License as published by
ansond 0:137634ff4186 12 * the Free Software Foundation; either version 2 of the License, or
ansond 0:137634ff4186 13 * (at your option) any later version.
ansond 0:137634ff4186 14 *
ansond 0:137634ff4186 15 * This program is distributed in the hope that it will be useful,
ansond 0:137634ff4186 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
ansond 0:137634ff4186 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
ansond 0:137634ff4186 18 * GNU General Public License for more details.
ansond 0:137634ff4186 19 *
ansond 0:137634ff4186 20 * You should have received a copy of the GNU General Public License along
ansond 0:137634ff4186 21 * with this program; if not, write to the Free Software Foundation, Inc.,
ansond 0:137634ff4186 22 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
ansond 0:137634ff4186 23 */
ansond 0:137634ff4186 24
ansond 0:137634ff4186 25 #ifndef POLARSSL_PK_H
ansond 0:137634ff4186 26 #define POLARSSL_PK_H
ansond 0:137634ff4186 27
ansond 0:137634ff4186 28 #if !defined(POLARSSL_CONFIG_FILE)
ansond 0:137634ff4186 29 #include "config.h"
ansond 0:137634ff4186 30 #else
ansond 0:137634ff4186 31 #include POLARSSL_CONFIG_FILE
ansond 0:137634ff4186 32 #endif
ansond 0:137634ff4186 33
ansond 0:137634ff4186 34 #include "md.h"
ansond 0:137634ff4186 35
ansond 0:137634ff4186 36 #if defined(POLARSSL_RSA_C)
ansond 0:137634ff4186 37 #include "rsa.h"
ansond 0:137634ff4186 38 #endif
ansond 0:137634ff4186 39
ansond 0:137634ff4186 40 #if defined(POLARSSL_ECP_C)
ansond 0:137634ff4186 41 #include "ecp.h"
ansond 0:137634ff4186 42 #endif
ansond 0:137634ff4186 43
ansond 0:137634ff4186 44 #if defined(POLARSSL_ECDSA_C)
ansond 0:137634ff4186 45 #include "ecdsa.h"
ansond 0:137634ff4186 46 #endif
ansond 0:137634ff4186 47
ansond 0:137634ff4186 48 #define POLARSSL_ERR_PK_MALLOC_FAILED -0x2F80 /**< Memory alloation failed. */
ansond 0:137634ff4186 49 #define POLARSSL_ERR_PK_TYPE_MISMATCH -0x2F00 /**< Type mismatch, eg attempt to encrypt with an ECDSA key */
ansond 0:137634ff4186 50 #define POLARSSL_ERR_PK_BAD_INPUT_DATA -0x2E80 /**< Bad input parameters to function. */
ansond 0:137634ff4186 51 #define POLARSSL_ERR_PK_FILE_IO_ERROR -0x2E00 /**< Read/write of file failed. */
ansond 0:137634ff4186 52 #define POLARSSL_ERR_PK_KEY_INVALID_VERSION -0x2D80 /**< Unsupported key version */
ansond 0:137634ff4186 53 #define POLARSSL_ERR_PK_KEY_INVALID_FORMAT -0x2D00 /**< Invalid key tag or value. */
ansond 0:137634ff4186 54 #define POLARSSL_ERR_PK_UNKNOWN_PK_ALG -0x2C80 /**< Key algorithm is unsupported (only RSA and EC are supported). */
ansond 0:137634ff4186 55 #define POLARSSL_ERR_PK_PASSWORD_REQUIRED -0x2C00 /**< Private key password can't be empty. */
ansond 0:137634ff4186 56 #define POLARSSL_ERR_PK_PASSWORD_MISMATCH -0x2B80 /**< Given private key password does not allow for correct decryption. */
ansond 0:137634ff4186 57 #define POLARSSL_ERR_PK_INVALID_PUBKEY -0x2B00 /**< The pubkey tag or value is invalid (only RSA and EC are supported). */
ansond 0:137634ff4186 58 #define POLARSSL_ERR_PK_INVALID_ALG -0x2A80 /**< The algorithm tag or value is invalid. */
ansond 0:137634ff4186 59 #define POLARSSL_ERR_PK_UNKNOWN_NAMED_CURVE -0x2A00 /**< Elliptic curve is unsupported (only NIST curves are supported). */
ansond 0:137634ff4186 60 #define POLARSSL_ERR_PK_FEATURE_UNAVAILABLE -0x2980 /**< Unavailable feature, e.g. RSA disabled for RSA key. */
ansond 0:137634ff4186 61 #define POLARSSL_ERR_PK_SIG_LEN_MISMATCH -0x2000 /**< The signature is valid but its length is less than expected. */
ansond 0:137634ff4186 62
ansond 0:137634ff4186 63
ansond 0:137634ff4186 64 #if defined(POLARSSL_RSA_C)
ansond 0:137634ff4186 65 /**
ansond 0:137634ff4186 66 * Quick access to an RSA context inside a PK context.
ansond 0:137634ff4186 67 *
ansond 0:137634ff4186 68 * \warning You must make sure the PK context actually holds an RSA context
ansond 0:137634ff4186 69 * before using this macro!
ansond 0:137634ff4186 70 */
ansond 0:137634ff4186 71 #define pk_rsa( pk ) ( (rsa_context *) (pk).pk_ctx )
ansond 0:137634ff4186 72 #endif /* POLARSSL_RSA_C */
ansond 0:137634ff4186 73
ansond 0:137634ff4186 74 #if defined(POLARSSL_ECP_C)
ansond 0:137634ff4186 75 /**
ansond 0:137634ff4186 76 * Quick access to an EC context inside a PK context.
ansond 0:137634ff4186 77 *
ansond 0:137634ff4186 78 * \warning You must make sure the PK context actually holds an EC context
ansond 0:137634ff4186 79 * before using this macro!
ansond 0:137634ff4186 80 */
ansond 0:137634ff4186 81 #define pk_ec( pk ) ( (ecp_keypair *) (pk).pk_ctx )
ansond 0:137634ff4186 82 #endif /* POLARSSL_ECP_C */
ansond 0:137634ff4186 83
ansond 0:137634ff4186 84
ansond 0:137634ff4186 85 #ifdef __cplusplus
ansond 0:137634ff4186 86 extern "C" {
ansond 0:137634ff4186 87 #endif
ansond 0:137634ff4186 88
ansond 0:137634ff4186 89 /**
ansond 0:137634ff4186 90 * \brief Public key types
ansond 0:137634ff4186 91 */
ansond 0:137634ff4186 92 typedef enum {
ansond 0:137634ff4186 93 POLARSSL_PK_NONE=0,
ansond 0:137634ff4186 94 POLARSSL_PK_RSA,
ansond 0:137634ff4186 95 POLARSSL_PK_ECKEY,
ansond 0:137634ff4186 96 POLARSSL_PK_ECKEY_DH,
ansond 0:137634ff4186 97 POLARSSL_PK_ECDSA,
ansond 0:137634ff4186 98 POLARSSL_PK_RSA_ALT,
ansond 0:137634ff4186 99 POLARSSL_PK_RSASSA_PSS,
ansond 0:137634ff4186 100 } pk_type_t;
ansond 0:137634ff4186 101
ansond 0:137634ff4186 102 /**
ansond 0:137634ff4186 103 * \brief Options for RSASSA-PSS signature verification.
ansond 0:137634ff4186 104 * See \c rsa_rsassa_pss_verify_ext()
ansond 0:137634ff4186 105 */
ansond 0:137634ff4186 106 typedef struct
ansond 0:137634ff4186 107 {
ansond 0:137634ff4186 108 md_type_t mgf1_hash_id;
ansond 0:137634ff4186 109 int expected_salt_len;
ansond 0:137634ff4186 110
ansond 0:137634ff4186 111 } pk_rsassa_pss_options;
ansond 0:137634ff4186 112
ansond 0:137634ff4186 113 /**
ansond 0:137634ff4186 114 * \brief Types for interfacing with the debug module
ansond 0:137634ff4186 115 */
ansond 0:137634ff4186 116 typedef enum
ansond 0:137634ff4186 117 {
ansond 0:137634ff4186 118 POLARSSL_PK_DEBUG_NONE = 0,
ansond 0:137634ff4186 119 POLARSSL_PK_DEBUG_MPI,
ansond 0:137634ff4186 120 POLARSSL_PK_DEBUG_ECP,
ansond 0:137634ff4186 121 } pk_debug_type;
ansond 0:137634ff4186 122
ansond 0:137634ff4186 123 /**
ansond 0:137634ff4186 124 * \brief Item to send to the debug module
ansond 0:137634ff4186 125 */
ansond 0:137634ff4186 126 typedef struct
ansond 0:137634ff4186 127 {
ansond 0:137634ff4186 128 pk_debug_type type;
ansond 0:137634ff4186 129 const char *name;
ansond 0:137634ff4186 130 void *value;
ansond 0:137634ff4186 131 } pk_debug_item;
ansond 0:137634ff4186 132
ansond 0:137634ff4186 133 /** Maximum number of item send for debugging, plus 1 */
ansond 0:137634ff4186 134 #define POLARSSL_PK_DEBUG_MAX_ITEMS 3
ansond 0:137634ff4186 135
ansond 0:137634ff4186 136 /**
ansond 0:137634ff4186 137 * \brief Public key information and operations
ansond 0:137634ff4186 138 */
ansond 0:137634ff4186 139 typedef struct
ansond 0:137634ff4186 140 {
ansond 0:137634ff4186 141 /** Public key type */
ansond 0:137634ff4186 142 pk_type_t type;
ansond 0:137634ff4186 143
ansond 0:137634ff4186 144 /** Type name */
ansond 0:137634ff4186 145 const char *name;
ansond 0:137634ff4186 146
ansond 0:137634ff4186 147 /** Get key size in bits */
ansond 0:137634ff4186 148 size_t (*get_size)( const void * );
ansond 0:137634ff4186 149
ansond 0:137634ff4186 150 /** Tell if the context implements this type (e.g. ECKEY can do ECDSA) */
ansond 0:137634ff4186 151 int (*can_do)( pk_type_t type );
ansond 0:137634ff4186 152
ansond 0:137634ff4186 153 /** Verify signature */
ansond 0:137634ff4186 154 int (*verify_func)( void *ctx, md_type_t md_alg,
ansond 0:137634ff4186 155 const unsigned char *hash, size_t hash_len,
ansond 0:137634ff4186 156 const unsigned char *sig, size_t sig_len );
ansond 0:137634ff4186 157
ansond 0:137634ff4186 158 /** Make signature */
ansond 0:137634ff4186 159 int (*sign_func)( void *ctx, md_type_t md_alg,
ansond 0:137634ff4186 160 const unsigned char *hash, size_t hash_len,
ansond 0:137634ff4186 161 unsigned char *sig, size_t *sig_len,
ansond 0:137634ff4186 162 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 163 void *p_rng );
ansond 0:137634ff4186 164
ansond 0:137634ff4186 165 /** Decrypt message */
ansond 0:137634ff4186 166 int (*decrypt_func)( void *ctx, const unsigned char *input, size_t ilen,
ansond 0:137634ff4186 167 unsigned char *output, size_t *olen, size_t osize,
ansond 0:137634ff4186 168 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 169 void *p_rng );
ansond 0:137634ff4186 170
ansond 0:137634ff4186 171 /** Encrypt message */
ansond 0:137634ff4186 172 int (*encrypt_func)( void *ctx, const unsigned char *input, size_t ilen,
ansond 0:137634ff4186 173 unsigned char *output, size_t *olen, size_t osize,
ansond 0:137634ff4186 174 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 175 void *p_rng );
ansond 0:137634ff4186 176
ansond 0:137634ff4186 177 /** Check public-private key pair */
ansond 0:137634ff4186 178 int (*check_pair_func)( const void *pub, const void *prv );
ansond 0:137634ff4186 179
ansond 0:137634ff4186 180 /** Allocate a new context */
ansond 0:137634ff4186 181 void * (*ctx_alloc_func)( void );
ansond 0:137634ff4186 182
ansond 0:137634ff4186 183 /** Free the given context */
ansond 0:137634ff4186 184 void (*ctx_free_func)( void *ctx );
ansond 0:137634ff4186 185
ansond 0:137634ff4186 186 /** Interface with the debug module */
ansond 0:137634ff4186 187 void (*debug_func)( const void *ctx, pk_debug_item *items );
ansond 0:137634ff4186 188
ansond 0:137634ff4186 189 } pk_info_t;
ansond 0:137634ff4186 190
ansond 0:137634ff4186 191 /**
ansond 0:137634ff4186 192 * \brief Public key container
ansond 0:137634ff4186 193 */
ansond 0:137634ff4186 194 typedef struct
ansond 0:137634ff4186 195 {
ansond 0:137634ff4186 196 const pk_info_t * pk_info; /**< Public key informations */
ansond 0:137634ff4186 197 void * pk_ctx; /**< Underlying public key context */
ansond 0:137634ff4186 198 } pk_context;
ansond 0:137634ff4186 199
ansond 0:137634ff4186 200 /**
ansond 0:137634ff4186 201 * \brief Types for RSA-alt abstraction
ansond 0:137634ff4186 202 */
ansond 0:137634ff4186 203 typedef int (*pk_rsa_alt_decrypt_func)( void *ctx, int mode, size_t *olen,
ansond 0:137634ff4186 204 const unsigned char *input, unsigned char *output,
ansond 0:137634ff4186 205 size_t output_max_len );
ansond 0:137634ff4186 206 typedef int (*pk_rsa_alt_sign_func)( void *ctx,
ansond 0:137634ff4186 207 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
ansond 0:137634ff4186 208 int mode, md_type_t md_alg, unsigned int hashlen,
ansond 0:137634ff4186 209 const unsigned char *hash, unsigned char *sig );
ansond 0:137634ff4186 210 typedef size_t (*pk_rsa_alt_key_len_func)( void *ctx );
ansond 0:137634ff4186 211
ansond 0:137634ff4186 212 /**
ansond 0:137634ff4186 213 * \brief Return information associated with the given PK type
ansond 0:137634ff4186 214 *
ansond 0:137634ff4186 215 * \param pk_type PK type to search for.
ansond 0:137634ff4186 216 *
ansond 0:137634ff4186 217 * \return The PK info associated with the type or NULL if not found.
ansond 0:137634ff4186 218 */
ansond 0:137634ff4186 219 const pk_info_t *pk_info_from_type( pk_type_t pk_type );
ansond 0:137634ff4186 220
ansond 0:137634ff4186 221 /**
ansond 0:137634ff4186 222 * \brief Initialize a pk_context (as NONE)
ansond 0:137634ff4186 223 */
ansond 0:137634ff4186 224 void pk_init( pk_context *ctx );
ansond 0:137634ff4186 225
ansond 0:137634ff4186 226 /**
ansond 0:137634ff4186 227 * \brief Free a pk_context
ansond 0:137634ff4186 228 */
ansond 0:137634ff4186 229 void pk_free( pk_context *ctx );
ansond 0:137634ff4186 230
ansond 0:137634ff4186 231 /**
ansond 0:137634ff4186 232 * \brief Initialize a PK context with the information given
ansond 0:137634ff4186 233 * and allocates the type-specific PK subcontext.
ansond 0:137634ff4186 234 *
ansond 0:137634ff4186 235 * \param ctx Context to initialize. Must be empty (type NONE).
ansond 0:137634ff4186 236 * \param info Information to use
ansond 0:137634ff4186 237 *
ansond 0:137634ff4186 238 * \return 0 on success,
ansond 0:137634ff4186 239 * POLARSSL_ERR_PK_BAD_INPUT_DATA on invalid input,
ansond 0:137634ff4186 240 * POLARSSL_ERR_PK_MALLOC_FAILED on allocation failure.
ansond 0:137634ff4186 241 *
ansond 0:137634ff4186 242 * \note For contexts holding an RSA-alt key, use
ansond 0:137634ff4186 243 * \c pk_init_ctx_rsa_alt() instead.
ansond 0:137634ff4186 244 */
ansond 0:137634ff4186 245 int pk_init_ctx( pk_context *ctx, const pk_info_t *info );
ansond 0:137634ff4186 246
ansond 0:137634ff4186 247 /**
ansond 0:137634ff4186 248 * \brief Initialize an RSA-alt context
ansond 0:137634ff4186 249 *
ansond 0:137634ff4186 250 * \param ctx Context to initialize. Must be empty (type NONE).
ansond 0:137634ff4186 251 * \param key RSA key pointer
ansond 0:137634ff4186 252 * \param decrypt_func Decryption function
ansond 0:137634ff4186 253 * \param sign_func Signing function
ansond 0:137634ff4186 254 * \param key_len_func Function returning key length in bytes
ansond 0:137634ff4186 255 *
ansond 0:137634ff4186 256 * \return 0 on success, or POLARSSL_ERR_PK_BAD_INPUT_DATA if the
ansond 0:137634ff4186 257 * context wasn't already initialized as RSA_ALT.
ansond 0:137634ff4186 258 *
ansond 0:137634ff4186 259 * \note This function replaces \c pk_init_ctx() for RSA-alt.
ansond 0:137634ff4186 260 */
ansond 0:137634ff4186 261 int pk_init_ctx_rsa_alt( pk_context *ctx, void * key,
ansond 0:137634ff4186 262 pk_rsa_alt_decrypt_func decrypt_func,
ansond 0:137634ff4186 263 pk_rsa_alt_sign_func sign_func,
ansond 0:137634ff4186 264 pk_rsa_alt_key_len_func key_len_func );
ansond 0:137634ff4186 265
ansond 0:137634ff4186 266 /**
ansond 0:137634ff4186 267 * \brief Get the size in bits of the underlying key
ansond 0:137634ff4186 268 *
ansond 0:137634ff4186 269 * \param ctx Context to use
ansond 0:137634ff4186 270 *
ansond 0:137634ff4186 271 * \return Key size in bits, or 0 on error
ansond 0:137634ff4186 272 */
ansond 0:137634ff4186 273 size_t pk_get_size( const pk_context *ctx );
ansond 0:137634ff4186 274
ansond 0:137634ff4186 275 /**
ansond 0:137634ff4186 276 * \brief Get the length in bytes of the underlying key
ansond 0:137634ff4186 277 * \param ctx Context to use
ansond 0:137634ff4186 278 *
ansond 0:137634ff4186 279 * \return Key length in bytes, or 0 on error
ansond 0:137634ff4186 280 */
ansond 0:137634ff4186 281 static inline size_t pk_get_len( const pk_context *ctx )
ansond 0:137634ff4186 282 {
ansond 0:137634ff4186 283 return( ( pk_get_size( ctx ) + 7 ) / 8 );
ansond 0:137634ff4186 284 }
ansond 0:137634ff4186 285
ansond 0:137634ff4186 286 /**
ansond 0:137634ff4186 287 * \brief Tell if a context can do the operation given by type
ansond 0:137634ff4186 288 *
ansond 0:137634ff4186 289 * \param ctx Context to test
ansond 0:137634ff4186 290 * \param type Target type
ansond 0:137634ff4186 291 *
ansond 0:137634ff4186 292 * \return 0 if context can't do the operations,
ansond 0:137634ff4186 293 * 1 otherwise.
ansond 0:137634ff4186 294 */
ansond 0:137634ff4186 295 int pk_can_do( pk_context *ctx, pk_type_t type );
ansond 0:137634ff4186 296
ansond 0:137634ff4186 297 /**
ansond 0:137634ff4186 298 * \brief Verify signature (including padding if relevant).
ansond 0:137634ff4186 299 *
ansond 0:137634ff4186 300 * \param ctx PK context to use
ansond 0:137634ff4186 301 * \param md_alg Hash algorithm used (see notes)
ansond 0:137634ff4186 302 * \param hash Hash of the message to sign
ansond 0:137634ff4186 303 * \param hash_len Hash length or 0 (see notes)
ansond 0:137634ff4186 304 * \param sig Signature to verify
ansond 0:137634ff4186 305 * \param sig_len Signature length
ansond 0:137634ff4186 306 *
ansond 0:137634ff4186 307 * \return 0 on success (signature is valid),
ansond 0:137634ff4186 308 * POLARSSL_ERR_PK_SIG_LEN_MISMATCH if the signature is
ansond 0:137634ff4186 309 * valid but its actual length is less than sig_len,
ansond 0:137634ff4186 310 * or a specific error code.
ansond 0:137634ff4186 311 *
ansond 0:137634ff4186 312 * \note For RSA keys, the default padding type is PKCS#1 v1.5.
ansond 0:137634ff4186 313 * Use \c pk_verify_ext( POLARSSL_PK_RSASSA_PSS, ... )
ansond 0:137634ff4186 314 * to verify RSASSA_PSS signatures.
ansond 0:137634ff4186 315 *
ansond 0:137634ff4186 316 * \note If hash_len is 0, then the length associated with md_alg
ansond 0:137634ff4186 317 * is used instead, or an error returned if it is invalid.
ansond 0:137634ff4186 318 *
ansond 0:137634ff4186 319 * \note md_alg may be POLARSSL_MD_NONE, only if hash_len != 0
ansond 0:137634ff4186 320 */
ansond 0:137634ff4186 321 int pk_verify( pk_context *ctx, md_type_t md_alg,
ansond 0:137634ff4186 322 const unsigned char *hash, size_t hash_len,
ansond 0:137634ff4186 323 const unsigned char *sig, size_t sig_len );
ansond 0:137634ff4186 324
ansond 0:137634ff4186 325 /**
ansond 0:137634ff4186 326 * \brief Verify signature, with options.
ansond 0:137634ff4186 327 * (Includes verification of the padding depending on type.)
ansond 0:137634ff4186 328 *
ansond 0:137634ff4186 329 * \param type Signature type (inc. possible padding type) to verify
ansond 0:137634ff4186 330 * \param options Pointer to type-specific options, or NULL
ansond 0:137634ff4186 331 * \param ctx PK context to use
ansond 0:137634ff4186 332 * \param md_alg Hash algorithm used (see notes)
ansond 0:137634ff4186 333 * \param hash Hash of the message to sign
ansond 0:137634ff4186 334 * \param hash_len Hash length or 0 (see notes)
ansond 0:137634ff4186 335 * \param sig Signature to verify
ansond 0:137634ff4186 336 * \param sig_len Signature length
ansond 0:137634ff4186 337 *
ansond 0:137634ff4186 338 * \return 0 on success (signature is valid),
ansond 0:137634ff4186 339 * POLARSSL_ERR_PK_TYPE_MISMATCH if the PK context can't be
ansond 0:137634ff4186 340 * used for this type of signatures,
ansond 0:137634ff4186 341 * POLARSSL_ERR_PK_SIG_LEN_MISMATCH if the signature is
ansond 0:137634ff4186 342 * valid but its actual length is less than sig_len,
ansond 0:137634ff4186 343 * or a specific error code.
ansond 0:137634ff4186 344 *
ansond 0:137634ff4186 345 * \note If hash_len is 0, then the length associated with md_alg
ansond 0:137634ff4186 346 * is used instead, or an error returned if it is invalid.
ansond 0:137634ff4186 347 *
ansond 0:137634ff4186 348 * \note md_alg may be POLARSSL_MD_NONE, only if hash_len != 0
ansond 0:137634ff4186 349 *
ansond 0:137634ff4186 350 * \note If type is POLARSSL_PK_RSASSA_PSS, then options must point
ansond 0:137634ff4186 351 * to a pk_rsassa_pss_options structure,
ansond 0:137634ff4186 352 * otherwise it must be NULL.
ansond 0:137634ff4186 353 */
ansond 0:137634ff4186 354 int pk_verify_ext( pk_type_t type, const void *options,
ansond 0:137634ff4186 355 pk_context *ctx, md_type_t md_alg,
ansond 0:137634ff4186 356 const unsigned char *hash, size_t hash_len,
ansond 0:137634ff4186 357 const unsigned char *sig, size_t sig_len );
ansond 0:137634ff4186 358
ansond 0:137634ff4186 359 /**
ansond 0:137634ff4186 360 * \brief Make signature, including padding if relevant.
ansond 0:137634ff4186 361 *
ansond 0:137634ff4186 362 * \param ctx PK context to use
ansond 0:137634ff4186 363 * \param md_alg Hash algorithm used (see notes)
ansond 0:137634ff4186 364 * \param hash Hash of the message to sign
ansond 0:137634ff4186 365 * \param hash_len Hash length or 0 (see notes)
ansond 0:137634ff4186 366 * \param sig Place to write the signature
ansond 0:137634ff4186 367 * \param sig_len Number of bytes written
ansond 0:137634ff4186 368 * \param f_rng RNG function
ansond 0:137634ff4186 369 * \param p_rng RNG parameter
ansond 0:137634ff4186 370 *
ansond 0:137634ff4186 371 * \return 0 on success, or a specific error code.
ansond 0:137634ff4186 372 *
ansond 0:137634ff4186 373 * \note For RSA keys, the default padding type is PKCS#1 v1.5.
ansond 0:137634ff4186 374 * There is no interface in the PK module to make RSASSA-PSS
ansond 0:137634ff4186 375 * signatures yet.
ansond 0:137634ff4186 376 *
ansond 0:137634ff4186 377 * \note If hash_len is 0, then the length associated with md_alg
ansond 0:137634ff4186 378 * is used instead, or an error returned if it is invalid.
ansond 0:137634ff4186 379 *
ansond 0:137634ff4186 380 * \note md_alg may be POLARSSL_MD_NONE, only if hash_len != 0
ansond 0:137634ff4186 381 */
ansond 0:137634ff4186 382 int pk_sign( pk_context *ctx, md_type_t md_alg,
ansond 0:137634ff4186 383 const unsigned char *hash, size_t hash_len,
ansond 0:137634ff4186 384 unsigned char *sig, size_t *sig_len,
ansond 0:137634ff4186 385 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
ansond 0:137634ff4186 386
ansond 0:137634ff4186 387 /**
ansond 0:137634ff4186 388 * \brief Decrypt message (including padding if relevant).
ansond 0:137634ff4186 389 *
ansond 0:137634ff4186 390 * \param ctx PK context to use
ansond 0:137634ff4186 391 * \param input Input to decrypt
ansond 0:137634ff4186 392 * \param ilen Input size
ansond 0:137634ff4186 393 * \param output Decrypted output
ansond 0:137634ff4186 394 * \param olen Decrypted message length
ansond 0:137634ff4186 395 * \param osize Size of the output buffer
ansond 0:137634ff4186 396 * \param f_rng RNG function
ansond 0:137634ff4186 397 * \param p_rng RNG parameter
ansond 0:137634ff4186 398 *
ansond 0:137634ff4186 399 * \note For RSA keys, the default padding type is PKCS#1 v1.5.
ansond 0:137634ff4186 400 *
ansond 0:137634ff4186 401 * \return 0 on success, or a specific error code.
ansond 0:137634ff4186 402 */
ansond 0:137634ff4186 403 int pk_decrypt( pk_context *ctx,
ansond 0:137634ff4186 404 const unsigned char *input, size_t ilen,
ansond 0:137634ff4186 405 unsigned char *output, size_t *olen, size_t osize,
ansond 0:137634ff4186 406 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
ansond 0:137634ff4186 407
ansond 0:137634ff4186 408 /**
ansond 0:137634ff4186 409 * \brief Encrypt message (including padding if relevant).
ansond 0:137634ff4186 410 *
ansond 0:137634ff4186 411 * \param ctx PK context to use
ansond 0:137634ff4186 412 * \param input Message to encrypt
ansond 0:137634ff4186 413 * \param ilen Message size
ansond 0:137634ff4186 414 * \param output Encrypted output
ansond 0:137634ff4186 415 * \param olen Encrypted output length
ansond 0:137634ff4186 416 * \param osize Size of the output buffer
ansond 0:137634ff4186 417 * \param f_rng RNG function
ansond 0:137634ff4186 418 * \param p_rng RNG parameter
ansond 0:137634ff4186 419 *
ansond 0:137634ff4186 420 * \note For RSA keys, the default padding type is PKCS#1 v1.5.
ansond 0:137634ff4186 421 *
ansond 0:137634ff4186 422 * \return 0 on success, or a specific error code.
ansond 0:137634ff4186 423 */
ansond 0:137634ff4186 424 int pk_encrypt( pk_context *ctx,
ansond 0:137634ff4186 425 const unsigned char *input, size_t ilen,
ansond 0:137634ff4186 426 unsigned char *output, size_t *olen, size_t osize,
ansond 0:137634ff4186 427 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
ansond 0:137634ff4186 428
ansond 0:137634ff4186 429 /**
ansond 0:137634ff4186 430 * \brief Check if a public-private pair of keys matches.
ansond 0:137634ff4186 431 *
ansond 0:137634ff4186 432 * \param pub Context holding a public key.
ansond 0:137634ff4186 433 * \param prv Context holding a private (and public) key.
ansond 0:137634ff4186 434 *
ansond 0:137634ff4186 435 * \return 0 on success or POLARSSL_ERR_PK_BAD_INPUT_DATA
ansond 0:137634ff4186 436 */
ansond 0:137634ff4186 437 int pk_check_pair( const pk_context *pub, const pk_context *prv );
ansond 0:137634ff4186 438
ansond 0:137634ff4186 439 /**
ansond 0:137634ff4186 440 * \brief Export debug information
ansond 0:137634ff4186 441 *
ansond 0:137634ff4186 442 * \param ctx Context to use
ansond 0:137634ff4186 443 * \param items Place to write debug items
ansond 0:137634ff4186 444 *
ansond 0:137634ff4186 445 * \return 0 on success or POLARSSL_ERR_PK_BAD_INPUT_DATA
ansond 0:137634ff4186 446 */
ansond 0:137634ff4186 447 int pk_debug( const pk_context *ctx, pk_debug_item *items );
ansond 0:137634ff4186 448
ansond 0:137634ff4186 449 /**
ansond 0:137634ff4186 450 * \brief Access the type name
ansond 0:137634ff4186 451 *
ansond 0:137634ff4186 452 * \param ctx Context to use
ansond 0:137634ff4186 453 *
ansond 0:137634ff4186 454 * \return Type name on success, or "invalid PK"
ansond 0:137634ff4186 455 */
ansond 0:137634ff4186 456 const char * pk_get_name( const pk_context *ctx );
ansond 0:137634ff4186 457
ansond 0:137634ff4186 458 /**
ansond 0:137634ff4186 459 * \brief Get the key type
ansond 0:137634ff4186 460 *
ansond 0:137634ff4186 461 * \param ctx Context to use
ansond 0:137634ff4186 462 *
ansond 0:137634ff4186 463 * \return Type on success, or POLARSSL_PK_NONE
ansond 0:137634ff4186 464 */
ansond 0:137634ff4186 465 pk_type_t pk_get_type( const pk_context *ctx );
ansond 0:137634ff4186 466
ansond 0:137634ff4186 467 #if defined(POLARSSL_PK_PARSE_C)
ansond 0:137634ff4186 468 /** \ingroup pk_module */
ansond 0:137634ff4186 469 /**
ansond 0:137634ff4186 470 * \brief Parse a private key
ansond 0:137634ff4186 471 *
ansond 0:137634ff4186 472 * \param ctx key to be initialized
ansond 0:137634ff4186 473 * \param key input buffer
ansond 0:137634ff4186 474 * \param keylen size of the buffer
ansond 0:137634ff4186 475 * \param pwd password for decryption (optional)
ansond 0:137634ff4186 476 * \param pwdlen size of the password
ansond 0:137634ff4186 477 *
ansond 0:137634ff4186 478 * \note On entry, ctx must be empty, either freshly initialised
ansond 0:137634ff4186 479 * with pk_init() or reset with pk_free(). If you need a
ansond 0:137634ff4186 480 * specific key type, check the result with pk_can_do().
ansond 0:137634ff4186 481 *
ansond 0:137634ff4186 482 * \note The key is also checked for correctness.
ansond 0:137634ff4186 483 *
ansond 0:137634ff4186 484 * \return 0 if successful, or a specific PK or PEM error code
ansond 0:137634ff4186 485 */
ansond 0:137634ff4186 486 int pk_parse_key( pk_context *ctx,
ansond 0:137634ff4186 487 const unsigned char *key, size_t keylen,
ansond 0:137634ff4186 488 const unsigned char *pwd, size_t pwdlen );
ansond 0:137634ff4186 489
ansond 0:137634ff4186 490 /** \ingroup pk_module */
ansond 0:137634ff4186 491 /**
ansond 0:137634ff4186 492 * \brief Parse a public key
ansond 0:137634ff4186 493 *
ansond 0:137634ff4186 494 * \param ctx key to be initialized
ansond 0:137634ff4186 495 * \param key input buffer
ansond 0:137634ff4186 496 * \param keylen size of the buffer
ansond 0:137634ff4186 497 *
ansond 0:137634ff4186 498 * \note On entry, ctx must be empty, either freshly initialised
ansond 0:137634ff4186 499 * with pk_init() or reset with pk_free(). If you need a
ansond 0:137634ff4186 500 * specific key type, check the result with pk_can_do().
ansond 0:137634ff4186 501 *
ansond 0:137634ff4186 502 * \note The key is also checked for correctness.
ansond 0:137634ff4186 503 *
ansond 0:137634ff4186 504 * \return 0 if successful, or a specific PK or PEM error code
ansond 0:137634ff4186 505 */
ansond 0:137634ff4186 506 int pk_parse_public_key( pk_context *ctx,
ansond 0:137634ff4186 507 const unsigned char *key, size_t keylen );
ansond 0:137634ff4186 508
ansond 0:137634ff4186 509 #if defined(POLARSSL_FS_IO)
ansond 0:137634ff4186 510 /** \ingroup pk_module */
ansond 0:137634ff4186 511 /**
ansond 0:137634ff4186 512 * \brief Load and parse a private key
ansond 0:137634ff4186 513 *
ansond 0:137634ff4186 514 * \param ctx key to be initialized
ansond 0:137634ff4186 515 * \param path filename to read the private key from
ansond 0:137634ff4186 516 * \param password password to decrypt the file (can be NULL)
ansond 0:137634ff4186 517 *
ansond 0:137634ff4186 518 * \note On entry, ctx must be empty, either freshly initialised
ansond 0:137634ff4186 519 * with pk_init() or reset with pk_free(). If you need a
ansond 0:137634ff4186 520 * specific key type, check the result with pk_can_do().
ansond 0:137634ff4186 521 *
ansond 0:137634ff4186 522 * \note The key is also checked for correctness.
ansond 0:137634ff4186 523 *
ansond 0:137634ff4186 524 * \return 0 if successful, or a specific PK or PEM error code
ansond 0:137634ff4186 525 */
ansond 0:137634ff4186 526 int pk_parse_keyfile( pk_context *ctx,
ansond 0:137634ff4186 527 const char *path, const char *password );
ansond 0:137634ff4186 528
ansond 0:137634ff4186 529 /** \ingroup pk_module */
ansond 0:137634ff4186 530 /**
ansond 0:137634ff4186 531 * \brief Load and parse a public key
ansond 0:137634ff4186 532 *
ansond 0:137634ff4186 533 * \param ctx key to be initialized
ansond 0:137634ff4186 534 * \param path filename to read the private key from
ansond 0:137634ff4186 535 *
ansond 0:137634ff4186 536 * \note On entry, ctx must be empty, either freshly initialised
ansond 0:137634ff4186 537 * with pk_init() or reset with pk_free(). If you need a
ansond 0:137634ff4186 538 * specific key type, check the result with pk_can_do().
ansond 0:137634ff4186 539 *
ansond 0:137634ff4186 540 * \note The key is also checked for correctness.
ansond 0:137634ff4186 541 *
ansond 0:137634ff4186 542 * \return 0 if successful, or a specific PK or PEM error code
ansond 0:137634ff4186 543 */
ansond 0:137634ff4186 544 int pk_parse_public_keyfile( pk_context *ctx, const char *path );
ansond 0:137634ff4186 545 #endif /* POLARSSL_FS_IO */
ansond 0:137634ff4186 546 #endif /* POLARSSL_PK_PARSE_C */
ansond 0:137634ff4186 547
ansond 0:137634ff4186 548 #if defined(POLARSSL_PK_WRITE_C)
ansond 0:137634ff4186 549 /**
ansond 0:137634ff4186 550 * \brief Write a private key to a PKCS#1 or SEC1 DER structure
ansond 0:137634ff4186 551 * Note: data is written at the end of the buffer! Use the
ansond 0:137634ff4186 552 * return value to determine where you should start
ansond 0:137634ff4186 553 * using the buffer
ansond 0:137634ff4186 554 *
ansond 0:137634ff4186 555 * \param ctx private to write away
ansond 0:137634ff4186 556 * \param buf buffer to write to
ansond 0:137634ff4186 557 * \param size size of the buffer
ansond 0:137634ff4186 558 *
ansond 0:137634ff4186 559 * \return length of data written if successful, or a specific
ansond 0:137634ff4186 560 * error code
ansond 0:137634ff4186 561 */
ansond 0:137634ff4186 562 int pk_write_key_der( pk_context *ctx, unsigned char *buf, size_t size );
ansond 0:137634ff4186 563
ansond 0:137634ff4186 564 /**
ansond 0:137634ff4186 565 * \brief Write a public key to a SubjectPublicKeyInfo DER structure
ansond 0:137634ff4186 566 * Note: data is written at the end of the buffer! Use the
ansond 0:137634ff4186 567 * return value to determine where you should start
ansond 0:137634ff4186 568 * using the buffer
ansond 0:137634ff4186 569 *
ansond 0:137634ff4186 570 * \param ctx public key to write away
ansond 0:137634ff4186 571 * \param buf buffer to write to
ansond 0:137634ff4186 572 * \param size size of the buffer
ansond 0:137634ff4186 573 *
ansond 0:137634ff4186 574 * \return length of data written if successful, or a specific
ansond 0:137634ff4186 575 * error code
ansond 0:137634ff4186 576 */
ansond 0:137634ff4186 577 int pk_write_pubkey_der( pk_context *ctx, unsigned char *buf, size_t size );
ansond 0:137634ff4186 578
ansond 0:137634ff4186 579 #if defined(POLARSSL_PEM_WRITE_C)
ansond 0:137634ff4186 580 /**
ansond 0:137634ff4186 581 * \brief Write a public key to a PEM string
ansond 0:137634ff4186 582 *
ansond 0:137634ff4186 583 * \param ctx public key to write away
ansond 0:137634ff4186 584 * \param buf buffer to write to
ansond 0:137634ff4186 585 * \param size size of the buffer
ansond 0:137634ff4186 586 *
ansond 0:137634ff4186 587 * \return 0 successful, or a specific error code
ansond 0:137634ff4186 588 */
ansond 0:137634ff4186 589 int pk_write_pubkey_pem( pk_context *ctx, unsigned char *buf, size_t size );
ansond 0:137634ff4186 590
ansond 0:137634ff4186 591 /**
ansond 0:137634ff4186 592 * \brief Write a private key to a PKCS#1 or SEC1 PEM string
ansond 0:137634ff4186 593 *
ansond 0:137634ff4186 594 * \param ctx private to write away
ansond 0:137634ff4186 595 * \param buf buffer to write to
ansond 0:137634ff4186 596 * \param size size of the buffer
ansond 0:137634ff4186 597 *
ansond 0:137634ff4186 598 * \return 0 successful, or a specific error code
ansond 0:137634ff4186 599 */
ansond 0:137634ff4186 600 int pk_write_key_pem( pk_context *ctx, unsigned char *buf, size_t size );
ansond 0:137634ff4186 601 #endif /* POLARSSL_PEM_WRITE_C */
ansond 0:137634ff4186 602 #endif /* POLARSSL_PK_WRITE_C */
ansond 0:137634ff4186 603
ansond 0:137634ff4186 604 /*
ansond 0:137634ff4186 605 * WARNING: Low-level functions. You probably do not want to use these unless
ansond 0:137634ff4186 606 * you are certain you do ;)
ansond 0:137634ff4186 607 */
ansond 0:137634ff4186 608
ansond 0:137634ff4186 609 #if defined(POLARSSL_PK_PARSE_C)
ansond 0:137634ff4186 610 /**
ansond 0:137634ff4186 611 * \brief Parse a SubjectPublicKeyInfo DER structure
ansond 0:137634ff4186 612 *
ansond 0:137634ff4186 613 * \param p the position in the ASN.1 data
ansond 0:137634ff4186 614 * \param end end of the buffer
ansond 0:137634ff4186 615 * \param pk the key to fill
ansond 0:137634ff4186 616 *
ansond 0:137634ff4186 617 * \return 0 if successful, or a specific PK error code
ansond 0:137634ff4186 618 */
ansond 0:137634ff4186 619 int pk_parse_subpubkey( unsigned char **p, const unsigned char *end,
ansond 0:137634ff4186 620 pk_context *pk );
ansond 0:137634ff4186 621 #endif /* POLARSSL_PK_PARSE_C */
ansond 0:137634ff4186 622
ansond 0:137634ff4186 623 #if defined(POLARSSL_PK_WRITE_C)
ansond 0:137634ff4186 624 /**
ansond 0:137634ff4186 625 * \brief Write a subjectPublicKey to ASN.1 data
ansond 0:137634ff4186 626 * Note: function works backwards in data buffer
ansond 0:137634ff4186 627 *
ansond 0:137634ff4186 628 * \param p reference to current position pointer
ansond 0:137634ff4186 629 * \param start start of the buffer (for bounds-checking)
ansond 0:137634ff4186 630 * \param key public key to write away
ansond 0:137634ff4186 631 *
ansond 0:137634ff4186 632 * \return the length written or a negative error code
ansond 0:137634ff4186 633 */
ansond 0:137634ff4186 634 int pk_write_pubkey( unsigned char **p, unsigned char *start,
ansond 0:137634ff4186 635 const pk_context *key );
ansond 0:137634ff4186 636 #endif /* POLARSSL_PK_WRITE_C */
ansond 0:137634ff4186 637
ansond 0:137634ff4186 638 /*
ansond 0:137634ff4186 639 * Internal module functions. You probably do not want to use these unless you
ansond 0:137634ff4186 640 * know you do.
ansond 0:137634ff4186 641 */
ansond 0:137634ff4186 642 #if defined(POLARSSL_FS_IO)
ansond 0:137634ff4186 643 int pk_load_file( const char *path, unsigned char **buf, size_t *n );
ansond 0:137634ff4186 644 #endif
ansond 0:137634ff4186 645
ansond 0:137634ff4186 646 #ifdef __cplusplus
ansond 0:137634ff4186 647 }
ansond 0:137634ff4186 648 #endif
ansond 0:137634ff4186 649
ansond 0:137634ff4186 650 #endif /* POLARSSL_PK_H */
ansond 0:137634ff4186 651