Doug Anson / mbedTLSLibrary

mbed TLS library

Dependents:   HTTPClient-SSL WS_SERVER

include/polarssl/rsa.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 rsa.h
ansond 0:137634ff4186 3 *
ansond 0:137634ff4186 4 * \brief The RSA public-key cryptosystem
ansond 0:137634ff4186 5 *
ansond 0:137634ff4186 6 * Copyright (C) 2006-2014, 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 #ifndef POLARSSL_RSA_H
ansond 0:137634ff4186 25 #define POLARSSL_RSA_H
ansond 0:137634ff4186 26
ansond 0:137634ff4186 27 #if !defined(POLARSSL_CONFIG_FILE)
ansond 0:137634ff4186 28 #include "config.h"
ansond 0:137634ff4186 29 #else
ansond 0:137634ff4186 30 #include POLARSSL_CONFIG_FILE
ansond 0:137634ff4186 31 #endif
ansond 0:137634ff4186 32
ansond 0:137634ff4186 33 #include "bignum.h"
ansond 0:137634ff4186 34 #include "md.h"
ansond 0:137634ff4186 35
ansond 0:137634ff4186 36 #if defined(POLARSSL_THREADING_C)
ansond 0:137634ff4186 37 #include "threading.h"
ansond 0:137634ff4186 38 #endif
ansond 0:137634ff4186 39
ansond 0:137634ff4186 40 /*
ansond 0:137634ff4186 41 * RSA Error codes
ansond 0:137634ff4186 42 */
ansond 0:137634ff4186 43 #define POLARSSL_ERR_RSA_BAD_INPUT_DATA -0x4080 /**< Bad input parameters to function. */
ansond 0:137634ff4186 44 #define POLARSSL_ERR_RSA_INVALID_PADDING -0x4100 /**< Input data contains invalid padding and is rejected. */
ansond 0:137634ff4186 45 #define POLARSSL_ERR_RSA_KEY_GEN_FAILED -0x4180 /**< Something failed during generation of a key. */
ansond 0:137634ff4186 46 #define POLARSSL_ERR_RSA_KEY_CHECK_FAILED -0x4200 /**< Key failed to pass the library's validity check. */
ansond 0:137634ff4186 47 #define POLARSSL_ERR_RSA_PUBLIC_FAILED -0x4280 /**< The public key operation failed. */
ansond 0:137634ff4186 48 #define POLARSSL_ERR_RSA_PRIVATE_FAILED -0x4300 /**< The private key operation failed. */
ansond 0:137634ff4186 49 #define POLARSSL_ERR_RSA_VERIFY_FAILED -0x4380 /**< The PKCS#1 verification failed. */
ansond 0:137634ff4186 50 #define POLARSSL_ERR_RSA_OUTPUT_TOO_LARGE -0x4400 /**< The output buffer for decryption is not large enough. */
ansond 0:137634ff4186 51 #define POLARSSL_ERR_RSA_RNG_FAILED -0x4480 /**< The random generator failed to generate non-zeros. */
ansond 0:137634ff4186 52
ansond 0:137634ff4186 53 /*
ansond 0:137634ff4186 54 * RSA constants
ansond 0:137634ff4186 55 */
ansond 0:137634ff4186 56 #define RSA_PUBLIC 0
ansond 0:137634ff4186 57 #define RSA_PRIVATE 1
ansond 0:137634ff4186 58
ansond 0:137634ff4186 59 #define RSA_PKCS_V15 0
ansond 0:137634ff4186 60 #define RSA_PKCS_V21 1
ansond 0:137634ff4186 61
ansond 0:137634ff4186 62 #define RSA_SIGN 1
ansond 0:137634ff4186 63 #define RSA_CRYPT 2
ansond 0:137634ff4186 64
ansond 0:137634ff4186 65 #define RSA_SALT_LEN_ANY -1
ansond 0:137634ff4186 66
ansond 0:137634ff4186 67 /*
ansond 0:137634ff4186 68 * The above constants may be used even if the RSA module is compile out,
ansond 0:137634ff4186 69 * eg for alternative (PKCS#11) RSA implemenations in the PK layers.
ansond 0:137634ff4186 70 */
ansond 0:137634ff4186 71 #if defined(POLARSSL_RSA_C)
ansond 0:137634ff4186 72
ansond 0:137634ff4186 73 #ifdef __cplusplus
ansond 0:137634ff4186 74 extern "C" {
ansond 0:137634ff4186 75 #endif
ansond 0:137634ff4186 76
ansond 0:137634ff4186 77 /**
ansond 0:137634ff4186 78 * \brief RSA context structure
ansond 0:137634ff4186 79 */
ansond 0:137634ff4186 80 typedef struct
ansond 0:137634ff4186 81 {
ansond 0:137634ff4186 82 int ver; /*!< always 0 */
ansond 0:137634ff4186 83 size_t len; /*!< size(N) in chars */
ansond 0:137634ff4186 84
ansond 0:137634ff4186 85 mpi N; /*!< public modulus */
ansond 0:137634ff4186 86 mpi E; /*!< public exponent */
ansond 0:137634ff4186 87
ansond 0:137634ff4186 88 mpi D; /*!< private exponent */
ansond 0:137634ff4186 89 mpi P; /*!< 1st prime factor */
ansond 0:137634ff4186 90 mpi Q; /*!< 2nd prime factor */
ansond 0:137634ff4186 91 mpi DP; /*!< D % (P - 1) */
ansond 0:137634ff4186 92 mpi DQ; /*!< D % (Q - 1) */
ansond 0:137634ff4186 93 mpi QP; /*!< 1 / (Q % P) */
ansond 0:137634ff4186 94
ansond 0:137634ff4186 95 mpi RN; /*!< cached R^2 mod N */
ansond 0:137634ff4186 96 mpi RP; /*!< cached R^2 mod P */
ansond 0:137634ff4186 97 mpi RQ; /*!< cached R^2 mod Q */
ansond 0:137634ff4186 98
ansond 0:137634ff4186 99 mpi Vi; /*!< cached blinding value */
ansond 0:137634ff4186 100 mpi Vf; /*!< cached un-blinding value */
ansond 0:137634ff4186 101
ansond 0:137634ff4186 102 int padding; /*!< RSA_PKCS_V15 for 1.5 padding and
ansond 0:137634ff4186 103 RSA_PKCS_v21 for OAEP/PSS */
ansond 0:137634ff4186 104 int hash_id; /*!< Hash identifier of md_type_t as
ansond 0:137634ff4186 105 specified in the md.h header file
ansond 0:137634ff4186 106 for the EME-OAEP and EMSA-PSS
ansond 0:137634ff4186 107 encoding */
ansond 0:137634ff4186 108 #if defined(POLARSSL_THREADING_C)
ansond 0:137634ff4186 109 threading_mutex_t mutex; /*!< Thread-safety mutex */
ansond 0:137634ff4186 110 #endif
ansond 0:137634ff4186 111 }
ansond 0:137634ff4186 112 rsa_context;
ansond 0:137634ff4186 113
ansond 0:137634ff4186 114 /**
ansond 0:137634ff4186 115 * \brief Initialize an RSA context
ansond 0:137634ff4186 116 *
ansond 0:137634ff4186 117 * Note: Set padding to RSA_PKCS_V21 for the RSAES-OAEP
ansond 0:137634ff4186 118 * encryption scheme and the RSASSA-PSS signature scheme.
ansond 0:137634ff4186 119 *
ansond 0:137634ff4186 120 * \param ctx RSA context to be initialized
ansond 0:137634ff4186 121 * \param padding RSA_PKCS_V15 or RSA_PKCS_V21
ansond 0:137634ff4186 122 * \param hash_id RSA_PKCS_V21 hash identifier
ansond 0:137634ff4186 123 *
ansond 0:137634ff4186 124 * \note The hash_id parameter is actually ignored
ansond 0:137634ff4186 125 * when using RSA_PKCS_V15 padding.
ansond 0:137634ff4186 126 *
ansond 0:137634ff4186 127 * \note Choice of padding mode is strictly enforced for private key
ansond 0:137634ff4186 128 * operations, since there might be security concerns in
ansond 0:137634ff4186 129 * mixing padding modes. For public key operations it's merely
ansond 0:137634ff4186 130 * a default value, which can be overriden by calling specific
ansond 0:137634ff4186 131 * rsa_rsaes_xxx or rsa_rsassa_xxx functions.
ansond 0:137634ff4186 132 *
ansond 0:137634ff4186 133 * \note The chosen hash is always used for OEAP encryption.
ansond 0:137634ff4186 134 * For PSS signatures, it's always used for making signatures,
ansond 0:137634ff4186 135 * but can be overriden (and always is, if set to
ansond 0:137634ff4186 136 * POLARSSL_MD_NONE) for verifying them.
ansond 0:137634ff4186 137 */
ansond 0:137634ff4186 138 void rsa_init( rsa_context *ctx,
ansond 0:137634ff4186 139 int padding,
ansond 0:137634ff4186 140 int hash_id);
ansond 0:137634ff4186 141
ansond 0:137634ff4186 142 /**
ansond 0:137634ff4186 143 * \brief Set padding for an already initialized RSA context
ansond 0:137634ff4186 144 * See \c rsa_init() for details.
ansond 0:137634ff4186 145 *
ansond 0:137634ff4186 146 * \param ctx RSA context to be set
ansond 0:137634ff4186 147 * \param padding RSA_PKCS_V15 or RSA_PKCS_V21
ansond 0:137634ff4186 148 * \param hash_id RSA_PKCS_V21 hash identifier
ansond 0:137634ff4186 149 */
ansond 0:137634ff4186 150 void rsa_set_padding( rsa_context *ctx, int padding, int hash_id);
ansond 0:137634ff4186 151
ansond 0:137634ff4186 152 /**
ansond 0:137634ff4186 153 * \brief Generate an RSA keypair
ansond 0:137634ff4186 154 *
ansond 0:137634ff4186 155 * \param ctx RSA context that will hold the key
ansond 0:137634ff4186 156 * \param f_rng RNG function
ansond 0:137634ff4186 157 * \param p_rng RNG parameter
ansond 0:137634ff4186 158 * \param nbits size of the public key in bits
ansond 0:137634ff4186 159 * \param exponent public exponent (e.g., 65537)
ansond 0:137634ff4186 160 *
ansond 0:137634ff4186 161 * \note rsa_init() must be called beforehand to setup
ansond 0:137634ff4186 162 * the RSA context.
ansond 0:137634ff4186 163 *
ansond 0:137634ff4186 164 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
ansond 0:137634ff4186 165 */
ansond 0:137634ff4186 166 int rsa_gen_key( rsa_context *ctx,
ansond 0:137634ff4186 167 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 168 void *p_rng,
ansond 0:137634ff4186 169 unsigned int nbits, int exponent );
ansond 0:137634ff4186 170
ansond 0:137634ff4186 171 /**
ansond 0:137634ff4186 172 * \brief Check a public RSA key
ansond 0:137634ff4186 173 *
ansond 0:137634ff4186 174 * \param ctx RSA context to be checked
ansond 0:137634ff4186 175 *
ansond 0:137634ff4186 176 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
ansond 0:137634ff4186 177 */
ansond 0:137634ff4186 178 int rsa_check_pubkey( const rsa_context *ctx );
ansond 0:137634ff4186 179
ansond 0:137634ff4186 180 /**
ansond 0:137634ff4186 181 * \brief Check a private RSA key
ansond 0:137634ff4186 182 *
ansond 0:137634ff4186 183 * \param ctx RSA context to be checked
ansond 0:137634ff4186 184 *
ansond 0:137634ff4186 185 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
ansond 0:137634ff4186 186 */
ansond 0:137634ff4186 187 int rsa_check_privkey( const rsa_context *ctx );
ansond 0:137634ff4186 188
ansond 0:137634ff4186 189 /**
ansond 0:137634ff4186 190 * \brief Check a public-private RSA key pair.
ansond 0:137634ff4186 191 * Check each of the contexts, and make sure they match.
ansond 0:137634ff4186 192 *
ansond 0:137634ff4186 193 * \param pub RSA context holding the public key
ansond 0:137634ff4186 194 * \param prv RSA context holding the private key
ansond 0:137634ff4186 195 *
ansond 0:137634ff4186 196 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
ansond 0:137634ff4186 197 */
ansond 0:137634ff4186 198 int rsa_check_pub_priv( const rsa_context *pub, const rsa_context *prv );
ansond 0:137634ff4186 199
ansond 0:137634ff4186 200 /**
ansond 0:137634ff4186 201 * \brief Do an RSA public key operation
ansond 0:137634ff4186 202 *
ansond 0:137634ff4186 203 * \param ctx RSA context
ansond 0:137634ff4186 204 * \param input input buffer
ansond 0:137634ff4186 205 * \param output output buffer
ansond 0:137634ff4186 206 *
ansond 0:137634ff4186 207 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
ansond 0:137634ff4186 208 *
ansond 0:137634ff4186 209 * \note This function does NOT take care of message
ansond 0:137634ff4186 210 * padding. Also, be sure to set input[0] = 0 or assure that
ansond 0:137634ff4186 211 * input is smaller than N.
ansond 0:137634ff4186 212 *
ansond 0:137634ff4186 213 * \note The input and output buffers must be large
ansond 0:137634ff4186 214 * enough (eg. 128 bytes if RSA-1024 is used).
ansond 0:137634ff4186 215 */
ansond 0:137634ff4186 216 int rsa_public( rsa_context *ctx,
ansond 0:137634ff4186 217 const unsigned char *input,
ansond 0:137634ff4186 218 unsigned char *output );
ansond 0:137634ff4186 219
ansond 0:137634ff4186 220 /**
ansond 0:137634ff4186 221 * \brief Do an RSA private key operation
ansond 0:137634ff4186 222 *
ansond 0:137634ff4186 223 * \param ctx RSA context
ansond 0:137634ff4186 224 * \param f_rng RNG function (Needed for blinding)
ansond 0:137634ff4186 225 * \param p_rng RNG parameter
ansond 0:137634ff4186 226 * \param input input buffer
ansond 0:137634ff4186 227 * \param output output buffer
ansond 0:137634ff4186 228 *
ansond 0:137634ff4186 229 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
ansond 0:137634ff4186 230 *
ansond 0:137634ff4186 231 * \note The input and output buffers must be large
ansond 0:137634ff4186 232 * enough (eg. 128 bytes if RSA-1024 is used).
ansond 0:137634ff4186 233 */
ansond 0:137634ff4186 234 int rsa_private( rsa_context *ctx,
ansond 0:137634ff4186 235 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 236 void *p_rng,
ansond 0:137634ff4186 237 const unsigned char *input,
ansond 0:137634ff4186 238 unsigned char *output );
ansond 0:137634ff4186 239
ansond 0:137634ff4186 240 /**
ansond 0:137634ff4186 241 * \brief Generic wrapper to perform a PKCS#1 encryption using the
ansond 0:137634ff4186 242 * mode from the context. Add the message padding, then do an
ansond 0:137634ff4186 243 * RSA operation.
ansond 0:137634ff4186 244 *
ansond 0:137634ff4186 245 * \param ctx RSA context
ansond 0:137634ff4186 246 * \param f_rng RNG function (Needed for padding and PKCS#1 v2.1 encoding
ansond 0:137634ff4186 247 * and RSA_PRIVATE)
ansond 0:137634ff4186 248 * \param p_rng RNG parameter
ansond 0:137634ff4186 249 * \param mode RSA_PUBLIC or RSA_PRIVATE
ansond 0:137634ff4186 250 * \param ilen contains the plaintext length
ansond 0:137634ff4186 251 * \param input buffer holding the data to be encrypted
ansond 0:137634ff4186 252 * \param output buffer that will hold the ciphertext
ansond 0:137634ff4186 253 *
ansond 0:137634ff4186 254 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
ansond 0:137634ff4186 255 *
ansond 0:137634ff4186 256 * \note The output buffer must be as large as the size
ansond 0:137634ff4186 257 * of ctx->N (eg. 128 bytes if RSA-1024 is used).
ansond 0:137634ff4186 258 */
ansond 0:137634ff4186 259 int rsa_pkcs1_encrypt( rsa_context *ctx,
ansond 0:137634ff4186 260 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 261 void *p_rng,
ansond 0:137634ff4186 262 int mode, size_t ilen,
ansond 0:137634ff4186 263 const unsigned char *input,
ansond 0:137634ff4186 264 unsigned char *output );
ansond 0:137634ff4186 265
ansond 0:137634ff4186 266 /**
ansond 0:137634ff4186 267 * \brief Perform a PKCS#1 v1.5 encryption (RSAES-PKCS1-v1_5-ENCRYPT)
ansond 0:137634ff4186 268 *
ansond 0:137634ff4186 269 * \param ctx RSA context
ansond 0:137634ff4186 270 * \param f_rng RNG function (Needed for padding and RSA_PRIVATE)
ansond 0:137634ff4186 271 * \param p_rng RNG parameter
ansond 0:137634ff4186 272 * \param mode RSA_PUBLIC or RSA_PRIVATE
ansond 0:137634ff4186 273 * \param ilen contains the plaintext length
ansond 0:137634ff4186 274 * \param input buffer holding the data to be encrypted
ansond 0:137634ff4186 275 * \param output buffer that will hold the ciphertext
ansond 0:137634ff4186 276 *
ansond 0:137634ff4186 277 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
ansond 0:137634ff4186 278 *
ansond 0:137634ff4186 279 * \note The output buffer must be as large as the size
ansond 0:137634ff4186 280 * of ctx->N (eg. 128 bytes if RSA-1024 is used).
ansond 0:137634ff4186 281 */
ansond 0:137634ff4186 282 int rsa_rsaes_pkcs1_v15_encrypt( rsa_context *ctx,
ansond 0:137634ff4186 283 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 284 void *p_rng,
ansond 0:137634ff4186 285 int mode, size_t ilen,
ansond 0:137634ff4186 286 const unsigned char *input,
ansond 0:137634ff4186 287 unsigned char *output );
ansond 0:137634ff4186 288
ansond 0:137634ff4186 289 /**
ansond 0:137634ff4186 290 * \brief Perform a PKCS#1 v2.1 OAEP encryption (RSAES-OAEP-ENCRYPT)
ansond 0:137634ff4186 291 *
ansond 0:137634ff4186 292 * \param ctx RSA context
ansond 0:137634ff4186 293 * \param f_rng RNG function (Needed for padding and PKCS#1 v2.1 encoding
ansond 0:137634ff4186 294 * and RSA_PRIVATE)
ansond 0:137634ff4186 295 * \param p_rng RNG parameter
ansond 0:137634ff4186 296 * \param mode RSA_PUBLIC or RSA_PRIVATE
ansond 0:137634ff4186 297 * \param label buffer holding the custom label to use
ansond 0:137634ff4186 298 * \param label_len contains the label length
ansond 0:137634ff4186 299 * \param ilen contains the plaintext length
ansond 0:137634ff4186 300 * \param input buffer holding the data to be encrypted
ansond 0:137634ff4186 301 * \param output buffer that will hold the ciphertext
ansond 0:137634ff4186 302 *
ansond 0:137634ff4186 303 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
ansond 0:137634ff4186 304 *
ansond 0:137634ff4186 305 * \note The output buffer must be as large as the size
ansond 0:137634ff4186 306 * of ctx->N (eg. 128 bytes if RSA-1024 is used).
ansond 0:137634ff4186 307 */
ansond 0:137634ff4186 308 int rsa_rsaes_oaep_encrypt( rsa_context *ctx,
ansond 0:137634ff4186 309 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 310 void *p_rng,
ansond 0:137634ff4186 311 int mode,
ansond 0:137634ff4186 312 const unsigned char *label, size_t label_len,
ansond 0:137634ff4186 313 size_t ilen,
ansond 0:137634ff4186 314 const unsigned char *input,
ansond 0:137634ff4186 315 unsigned char *output );
ansond 0:137634ff4186 316
ansond 0:137634ff4186 317 /**
ansond 0:137634ff4186 318 * \brief Generic wrapper to perform a PKCS#1 decryption using the
ansond 0:137634ff4186 319 * mode from the context. Do an RSA operation, then remove
ansond 0:137634ff4186 320 * the message padding
ansond 0:137634ff4186 321 *
ansond 0:137634ff4186 322 * \param ctx RSA context
ansond 0:137634ff4186 323 * \param f_rng RNG function (Only needed for RSA_PRIVATE)
ansond 0:137634ff4186 324 * \param p_rng RNG parameter
ansond 0:137634ff4186 325 * \param mode RSA_PUBLIC or RSA_PRIVATE
ansond 0:137634ff4186 326 * \param olen will contain the plaintext length
ansond 0:137634ff4186 327 * \param input buffer holding the encrypted data
ansond 0:137634ff4186 328 * \param output buffer that will hold the plaintext
ansond 0:137634ff4186 329 * \param output_max_len maximum length of the output buffer
ansond 0:137634ff4186 330 *
ansond 0:137634ff4186 331 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
ansond 0:137634ff4186 332 *
ansond 0:137634ff4186 333 * \note The output buffer must be as large as the size
ansond 0:137634ff4186 334 * of ctx->N (eg. 128 bytes if RSA-1024 is used) otherwise
ansond 0:137634ff4186 335 * an error is thrown.
ansond 0:137634ff4186 336 */
ansond 0:137634ff4186 337 int rsa_pkcs1_decrypt( rsa_context *ctx,
ansond 0:137634ff4186 338 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 339 void *p_rng,
ansond 0:137634ff4186 340 int mode, size_t *olen,
ansond 0:137634ff4186 341 const unsigned char *input,
ansond 0:137634ff4186 342 unsigned char *output,
ansond 0:137634ff4186 343 size_t output_max_len );
ansond 0:137634ff4186 344
ansond 0:137634ff4186 345 /**
ansond 0:137634ff4186 346 * \brief Perform a PKCS#1 v1.5 decryption (RSAES-PKCS1-v1_5-DECRYPT)
ansond 0:137634ff4186 347 *
ansond 0:137634ff4186 348 * \param ctx RSA context
ansond 0:137634ff4186 349 * \param f_rng RNG function (Only needed for RSA_PRIVATE)
ansond 0:137634ff4186 350 * \param p_rng RNG parameter
ansond 0:137634ff4186 351 * \param mode RSA_PUBLIC or RSA_PRIVATE
ansond 0:137634ff4186 352 * \param olen will contain the plaintext length
ansond 0:137634ff4186 353 * \param input buffer holding the encrypted data
ansond 0:137634ff4186 354 * \param output buffer that will hold the plaintext
ansond 0:137634ff4186 355 * \param output_max_len maximum length of the output buffer
ansond 0:137634ff4186 356 *
ansond 0:137634ff4186 357 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
ansond 0:137634ff4186 358 *
ansond 0:137634ff4186 359 * \note The output buffer must be as large as the size
ansond 0:137634ff4186 360 * of ctx->N (eg. 128 bytes if RSA-1024 is used) otherwise
ansond 0:137634ff4186 361 * an error is thrown.
ansond 0:137634ff4186 362 */
ansond 0:137634ff4186 363 int rsa_rsaes_pkcs1_v15_decrypt( rsa_context *ctx,
ansond 0:137634ff4186 364 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 365 void *p_rng,
ansond 0:137634ff4186 366 int mode, size_t *olen,
ansond 0:137634ff4186 367 const unsigned char *input,
ansond 0:137634ff4186 368 unsigned char *output,
ansond 0:137634ff4186 369 size_t output_max_len );
ansond 0:137634ff4186 370
ansond 0:137634ff4186 371 /**
ansond 0:137634ff4186 372 * \brief Perform a PKCS#1 v2.1 OAEP decryption (RSAES-OAEP-DECRYPT)
ansond 0:137634ff4186 373 *
ansond 0:137634ff4186 374 * \param ctx RSA context
ansond 0:137634ff4186 375 * \param f_rng RNG function (Only needed for RSA_PRIVATE)
ansond 0:137634ff4186 376 * \param p_rng RNG parameter
ansond 0:137634ff4186 377 * \param mode RSA_PUBLIC or RSA_PRIVATE
ansond 0:137634ff4186 378 * \param label buffer holding the custom label to use
ansond 0:137634ff4186 379 * \param label_len contains the label length
ansond 0:137634ff4186 380 * \param olen will contain the plaintext length
ansond 0:137634ff4186 381 * \param input buffer holding the encrypted data
ansond 0:137634ff4186 382 * \param output buffer that will hold the plaintext
ansond 0:137634ff4186 383 * \param output_max_len maximum length of the output buffer
ansond 0:137634ff4186 384 *
ansond 0:137634ff4186 385 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
ansond 0:137634ff4186 386 *
ansond 0:137634ff4186 387 * \note The output buffer must be as large as the size
ansond 0:137634ff4186 388 * of ctx->N (eg. 128 bytes if RSA-1024 is used) otherwise
ansond 0:137634ff4186 389 * an error is thrown.
ansond 0:137634ff4186 390 */
ansond 0:137634ff4186 391 int rsa_rsaes_oaep_decrypt( rsa_context *ctx,
ansond 0:137634ff4186 392 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 393 void *p_rng,
ansond 0:137634ff4186 394 int mode,
ansond 0:137634ff4186 395 const unsigned char *label, size_t label_len,
ansond 0:137634ff4186 396 size_t *olen,
ansond 0:137634ff4186 397 const unsigned char *input,
ansond 0:137634ff4186 398 unsigned char *output,
ansond 0:137634ff4186 399 size_t output_max_len );
ansond 0:137634ff4186 400
ansond 0:137634ff4186 401 /**
ansond 0:137634ff4186 402 * \brief Generic wrapper to perform a PKCS#1 signature using the
ansond 0:137634ff4186 403 * mode from the context. Do a private RSA operation to sign
ansond 0:137634ff4186 404 * a message digest
ansond 0:137634ff4186 405 *
ansond 0:137634ff4186 406 * \param ctx RSA context
ansond 0:137634ff4186 407 * \param f_rng RNG function (Needed for PKCS#1 v2.1 encoding and for
ansond 0:137634ff4186 408 * RSA_PRIVATE)
ansond 0:137634ff4186 409 * \param p_rng RNG parameter
ansond 0:137634ff4186 410 * \param mode RSA_PUBLIC or RSA_PRIVATE
ansond 0:137634ff4186 411 * \param md_alg a POLARSSL_MD_* (use POLARSSL_MD_NONE for signing raw data)
ansond 0:137634ff4186 412 * \param hashlen message digest length (for POLARSSL_MD_NONE only)
ansond 0:137634ff4186 413 * \param hash buffer holding the message digest
ansond 0:137634ff4186 414 * \param sig buffer that will hold the ciphertext
ansond 0:137634ff4186 415 *
ansond 0:137634ff4186 416 * \return 0 if the signing operation was successful,
ansond 0:137634ff4186 417 * or an POLARSSL_ERR_RSA_XXX error code
ansond 0:137634ff4186 418 *
ansond 0:137634ff4186 419 * \note The "sig" buffer must be as large as the size
ansond 0:137634ff4186 420 * of ctx->N (eg. 128 bytes if RSA-1024 is used).
ansond 0:137634ff4186 421 *
ansond 0:137634ff4186 422 * \note In case of PKCS#1 v2.1 encoding, see comments on
ansond 0:137634ff4186 423 * \note \c rsa_rsassa_pss_sign() for details on md_alg and hash_id.
ansond 0:137634ff4186 424 */
ansond 0:137634ff4186 425 int rsa_pkcs1_sign( rsa_context *ctx,
ansond 0:137634ff4186 426 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 427 void *p_rng,
ansond 0:137634ff4186 428 int mode,
ansond 0:137634ff4186 429 md_type_t md_alg,
ansond 0:137634ff4186 430 unsigned int hashlen,
ansond 0:137634ff4186 431 const unsigned char *hash,
ansond 0:137634ff4186 432 unsigned char *sig );
ansond 0:137634ff4186 433
ansond 0:137634ff4186 434 /**
ansond 0:137634ff4186 435 * \brief Perform a PKCS#1 v1.5 signature (RSASSA-PKCS1-v1_5-SIGN)
ansond 0:137634ff4186 436 *
ansond 0:137634ff4186 437 * \param ctx RSA context
ansond 0:137634ff4186 438 * \param f_rng RNG function (Only needed for RSA_PRIVATE)
ansond 0:137634ff4186 439 * \param p_rng RNG parameter
ansond 0:137634ff4186 440 * \param mode RSA_PUBLIC or RSA_PRIVATE
ansond 0:137634ff4186 441 * \param md_alg a POLARSSL_MD_* (use POLARSSL_MD_NONE for signing raw data)
ansond 0:137634ff4186 442 * \param hashlen message digest length (for POLARSSL_MD_NONE only)
ansond 0:137634ff4186 443 * \param hash buffer holding the message digest
ansond 0:137634ff4186 444 * \param sig buffer that will hold the ciphertext
ansond 0:137634ff4186 445 *
ansond 0:137634ff4186 446 * \return 0 if the signing operation was successful,
ansond 0:137634ff4186 447 * or an POLARSSL_ERR_RSA_XXX error code
ansond 0:137634ff4186 448 *
ansond 0:137634ff4186 449 * \note The "sig" buffer must be as large as the size
ansond 0:137634ff4186 450 * of ctx->N (eg. 128 bytes if RSA-1024 is used).
ansond 0:137634ff4186 451 */
ansond 0:137634ff4186 452 int rsa_rsassa_pkcs1_v15_sign( rsa_context *ctx,
ansond 0:137634ff4186 453 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 454 void *p_rng,
ansond 0:137634ff4186 455 int mode,
ansond 0:137634ff4186 456 md_type_t md_alg,
ansond 0:137634ff4186 457 unsigned int hashlen,
ansond 0:137634ff4186 458 const unsigned char *hash,
ansond 0:137634ff4186 459 unsigned char *sig );
ansond 0:137634ff4186 460
ansond 0:137634ff4186 461 /**
ansond 0:137634ff4186 462 * \brief Perform a PKCS#1 v2.1 PSS signature (RSASSA-PSS-SIGN)
ansond 0:137634ff4186 463 *
ansond 0:137634ff4186 464 * \param ctx RSA context
ansond 0:137634ff4186 465 * \param f_rng RNG function (Needed for PKCS#1 v2.1 encoding and for
ansond 0:137634ff4186 466 * RSA_PRIVATE)
ansond 0:137634ff4186 467 * \param p_rng RNG parameter
ansond 0:137634ff4186 468 * \param mode RSA_PUBLIC or RSA_PRIVATE
ansond 0:137634ff4186 469 * \param md_alg a POLARSSL_MD_* (use POLARSSL_MD_NONE for signing raw data)
ansond 0:137634ff4186 470 * \param hashlen message digest length (for POLARSSL_MD_NONE only)
ansond 0:137634ff4186 471 * \param hash buffer holding the message digest
ansond 0:137634ff4186 472 * \param sig buffer that will hold the ciphertext
ansond 0:137634ff4186 473 *
ansond 0:137634ff4186 474 * \return 0 if the signing operation was successful,
ansond 0:137634ff4186 475 * or an POLARSSL_ERR_RSA_XXX error code
ansond 0:137634ff4186 476 *
ansond 0:137634ff4186 477 * \note The "sig" buffer must be as large as the size
ansond 0:137634ff4186 478 * of ctx->N (eg. 128 bytes if RSA-1024 is used).
ansond 0:137634ff4186 479 *
ansond 0:137634ff4186 480 * \note The hash_id in the RSA context is the one used for the
ansond 0:137634ff4186 481 * encoding. md_alg in the function call is the type of hash
ansond 0:137634ff4186 482 * that is encoded. According to RFC 3447 it is advised to
ansond 0:137634ff4186 483 * keep both hashes the same.
ansond 0:137634ff4186 484 */
ansond 0:137634ff4186 485 int rsa_rsassa_pss_sign( rsa_context *ctx,
ansond 0:137634ff4186 486 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 487 void *p_rng,
ansond 0:137634ff4186 488 int mode,
ansond 0:137634ff4186 489 md_type_t md_alg,
ansond 0:137634ff4186 490 unsigned int hashlen,
ansond 0:137634ff4186 491 const unsigned char *hash,
ansond 0:137634ff4186 492 unsigned char *sig );
ansond 0:137634ff4186 493
ansond 0:137634ff4186 494 /**
ansond 0:137634ff4186 495 * \brief Generic wrapper to perform a PKCS#1 verification using the
ansond 0:137634ff4186 496 * mode from the context. Do a public RSA operation and check
ansond 0:137634ff4186 497 * the message digest
ansond 0:137634ff4186 498 *
ansond 0:137634ff4186 499 * \param ctx points to an RSA public key
ansond 0:137634ff4186 500 * \param f_rng RNG function (Only needed for RSA_PRIVATE)
ansond 0:137634ff4186 501 * \param p_rng RNG parameter
ansond 0:137634ff4186 502 * \param mode RSA_PUBLIC or RSA_PRIVATE
ansond 0:137634ff4186 503 * \param md_alg a POLARSSL_MD_* (use POLARSSL_MD_NONE for signing raw data)
ansond 0:137634ff4186 504 * \param hashlen message digest length (for POLARSSL_MD_NONE only)
ansond 0:137634ff4186 505 * \param hash buffer holding the message digest
ansond 0:137634ff4186 506 * \param sig buffer holding the ciphertext
ansond 0:137634ff4186 507 *
ansond 0:137634ff4186 508 * \return 0 if the verify operation was successful,
ansond 0:137634ff4186 509 * or an POLARSSL_ERR_RSA_XXX error code
ansond 0:137634ff4186 510 *
ansond 0:137634ff4186 511 * \note The "sig" buffer must be as large as the size
ansond 0:137634ff4186 512 * of ctx->N (eg. 128 bytes if RSA-1024 is used).
ansond 0:137634ff4186 513 *
ansond 0:137634ff4186 514 * \note In case of PKCS#1 v2.1 encoding, see comments on
ansond 0:137634ff4186 515 * \c rsa_rsassa_pss_verify() about md_alg and hash_id.
ansond 0:137634ff4186 516 */
ansond 0:137634ff4186 517 int rsa_pkcs1_verify( rsa_context *ctx,
ansond 0:137634ff4186 518 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 519 void *p_rng,
ansond 0:137634ff4186 520 int mode,
ansond 0:137634ff4186 521 md_type_t md_alg,
ansond 0:137634ff4186 522 unsigned int hashlen,
ansond 0:137634ff4186 523 const unsigned char *hash,
ansond 0:137634ff4186 524 const unsigned char *sig );
ansond 0:137634ff4186 525
ansond 0:137634ff4186 526 /**
ansond 0:137634ff4186 527 * \brief Perform a PKCS#1 v1.5 verification (RSASSA-PKCS1-v1_5-VERIFY)
ansond 0:137634ff4186 528 *
ansond 0:137634ff4186 529 * \param ctx points to an RSA public key
ansond 0:137634ff4186 530 * \param f_rng RNG function (Only needed for RSA_PRIVATE)
ansond 0:137634ff4186 531 * \param p_rng RNG parameter
ansond 0:137634ff4186 532 * \param mode RSA_PUBLIC or RSA_PRIVATE
ansond 0:137634ff4186 533 * \param md_alg a POLARSSL_MD_* (use POLARSSL_MD_NONE for signing raw data)
ansond 0:137634ff4186 534 * \param hashlen message digest length (for POLARSSL_MD_NONE only)
ansond 0:137634ff4186 535 * \param hash buffer holding the message digest
ansond 0:137634ff4186 536 * \param sig buffer holding the ciphertext
ansond 0:137634ff4186 537 *
ansond 0:137634ff4186 538 * \return 0 if the verify operation was successful,
ansond 0:137634ff4186 539 * or an POLARSSL_ERR_RSA_XXX error code
ansond 0:137634ff4186 540 *
ansond 0:137634ff4186 541 * \note The "sig" buffer must be as large as the size
ansond 0:137634ff4186 542 * of ctx->N (eg. 128 bytes if RSA-1024 is used).
ansond 0:137634ff4186 543 */
ansond 0:137634ff4186 544 int rsa_rsassa_pkcs1_v15_verify( rsa_context *ctx,
ansond 0:137634ff4186 545 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 546 void *p_rng,
ansond 0:137634ff4186 547 int mode,
ansond 0:137634ff4186 548 md_type_t md_alg,
ansond 0:137634ff4186 549 unsigned int hashlen,
ansond 0:137634ff4186 550 const unsigned char *hash,
ansond 0:137634ff4186 551 const unsigned char *sig );
ansond 0:137634ff4186 552
ansond 0:137634ff4186 553 /**
ansond 0:137634ff4186 554 * \brief Perform a PKCS#1 v2.1 PSS verification (RSASSA-PSS-VERIFY)
ansond 0:137634ff4186 555 * (This is the "simple" version.)
ansond 0:137634ff4186 556 *
ansond 0:137634ff4186 557 * \param ctx points to an RSA public key
ansond 0:137634ff4186 558 * \param f_rng RNG function (Only needed for RSA_PRIVATE)
ansond 0:137634ff4186 559 * \param p_rng RNG parameter
ansond 0:137634ff4186 560 * \param mode RSA_PUBLIC or RSA_PRIVATE
ansond 0:137634ff4186 561 * \param md_alg a POLARSSL_MD_* (use POLARSSL_MD_NONE for signing raw data)
ansond 0:137634ff4186 562 * \param hashlen message digest length (for POLARSSL_MD_NONE only)
ansond 0:137634ff4186 563 * \param hash buffer holding the message digest
ansond 0:137634ff4186 564 * \param sig buffer holding the ciphertext
ansond 0:137634ff4186 565 *
ansond 0:137634ff4186 566 * \return 0 if the verify operation was successful,
ansond 0:137634ff4186 567 * or an POLARSSL_ERR_RSA_XXX error code
ansond 0:137634ff4186 568 *
ansond 0:137634ff4186 569 * \note The "sig" buffer must be as large as the size
ansond 0:137634ff4186 570 * of ctx->N (eg. 128 bytes if RSA-1024 is used).
ansond 0:137634ff4186 571 *
ansond 0:137634ff4186 572 * \note The hash_id in the RSA context is the one used for the
ansond 0:137634ff4186 573 * verification. md_alg in the function call is the type of
ansond 0:137634ff4186 574 * hash that is verified. According to RFC 3447 it is advised to
ansond 0:137634ff4186 575 * keep both hashes the same. If hash_id in the RSA context is
ansond 0:137634ff4186 576 * unset, the md_alg from the function call is used.
ansond 0:137634ff4186 577 */
ansond 0:137634ff4186 578 int rsa_rsassa_pss_verify( rsa_context *ctx,
ansond 0:137634ff4186 579 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 580 void *p_rng,
ansond 0:137634ff4186 581 int mode,
ansond 0:137634ff4186 582 md_type_t md_alg,
ansond 0:137634ff4186 583 unsigned int hashlen,
ansond 0:137634ff4186 584 const unsigned char *hash,
ansond 0:137634ff4186 585 const unsigned char *sig );
ansond 0:137634ff4186 586
ansond 0:137634ff4186 587 /**
ansond 0:137634ff4186 588 * \brief Perform a PKCS#1 v2.1 PSS verification (RSASSA-PSS-VERIFY)
ansond 0:137634ff4186 589 * (This is the version with "full" options.)
ansond 0:137634ff4186 590 *
ansond 0:137634ff4186 591 * \param ctx points to an RSA public key
ansond 0:137634ff4186 592 * \param f_rng RNG function (Only needed for RSA_PRIVATE)
ansond 0:137634ff4186 593 * \param p_rng RNG parameter
ansond 0:137634ff4186 594 * \param mode RSA_PUBLIC or RSA_PRIVATE
ansond 0:137634ff4186 595 * \param md_alg a POLARSSL_MD_* (use POLARSSL_MD_NONE for signing raw data)
ansond 0:137634ff4186 596 * \param hashlen message digest length (for POLARSSL_MD_NONE only)
ansond 0:137634ff4186 597 * \param hash buffer holding the message digest
ansond 0:137634ff4186 598 * \param mgf1_hash_id message digest used for mask generation
ansond 0:137634ff4186 599 * \param expected_salt_len Length of the salt used in padding, use
ansond 0:137634ff4186 600 * RSA_SALT_LEN_ANY to accept any salt length
ansond 0:137634ff4186 601 * \param sig buffer holding the ciphertext
ansond 0:137634ff4186 602 *
ansond 0:137634ff4186 603 * \return 0 if the verify operation was successful,
ansond 0:137634ff4186 604 * or an POLARSSL_ERR_RSA_XXX error code
ansond 0:137634ff4186 605 *
ansond 0:137634ff4186 606 * \note The "sig" buffer must be as large as the size
ansond 0:137634ff4186 607 * of ctx->N (eg. 128 bytes if RSA-1024 is used).
ansond 0:137634ff4186 608 *
ansond 0:137634ff4186 609 * \note The hash_id in the RSA context is ignored.
ansond 0:137634ff4186 610 */
ansond 0:137634ff4186 611 int rsa_rsassa_pss_verify_ext( rsa_context *ctx,
ansond 0:137634ff4186 612 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 613 void *p_rng,
ansond 0:137634ff4186 614 int mode,
ansond 0:137634ff4186 615 md_type_t md_alg,
ansond 0:137634ff4186 616 unsigned int hashlen,
ansond 0:137634ff4186 617 const unsigned char *hash,
ansond 0:137634ff4186 618 md_type_t mgf1_hash_id,
ansond 0:137634ff4186 619 int expected_salt_len,
ansond 0:137634ff4186 620 const unsigned char *sig );
ansond 0:137634ff4186 621
ansond 0:137634ff4186 622 /**
ansond 0:137634ff4186 623 * \brief Copy the components of an RSA context
ansond 0:137634ff4186 624 *
ansond 0:137634ff4186 625 * \param dst Destination context
ansond 0:137634ff4186 626 * \param src Source context
ansond 0:137634ff4186 627 *
ansond 0:137634ff4186 628 * \return O on success,
ansond 0:137634ff4186 629 * POLARSSL_ERR_MPI_MALLOC_FAILED on memory allocation failure
ansond 0:137634ff4186 630 */
ansond 0:137634ff4186 631 int rsa_copy( rsa_context *dst, const rsa_context *src );
ansond 0:137634ff4186 632
ansond 0:137634ff4186 633 /**
ansond 0:137634ff4186 634 * \brief Free the components of an RSA key
ansond 0:137634ff4186 635 *
ansond 0:137634ff4186 636 * \param ctx RSA Context to free
ansond 0:137634ff4186 637 */
ansond 0:137634ff4186 638 void rsa_free( rsa_context *ctx );
ansond 0:137634ff4186 639
ansond 0:137634ff4186 640 /**
ansond 0:137634ff4186 641 * \brief Checkup routine
ansond 0:137634ff4186 642 *
ansond 0:137634ff4186 643 * \return 0 if successful, or 1 if the test failed
ansond 0:137634ff4186 644 */
ansond 0:137634ff4186 645 int rsa_self_test( int verbose );
ansond 0:137634ff4186 646
ansond 0:137634ff4186 647 #ifdef __cplusplus
ansond 0:137634ff4186 648 }
ansond 0:137634ff4186 649 #endif
ansond 0:137634ff4186 650
ansond 0:137634ff4186 651 #endif /* POLARSSL_RSA_C */
ansond 0:137634ff4186 652
ansond 0:137634ff4186 653 #endif /* rsa.h */
ansond 0:137634ff4186 654