]>
git.zerfleddert.de Git - proxmark3-svn/blob - common/polarssl/rsa.h
4 * \brief The RSA public-key cryptosystem
6 * Copyright (C) 2006-2010, Brainspark B.V.
8 * This file is part of PolarSSL (http://www.polarssl.org)
9 * Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.org>
11 * All rights reserved.
13 * This program is free software; you can redistribute it and/or modify
14 * it under the terms of the GNU General Public License as published by
15 * the Free Software Foundation; either version 2 of the License, or
16 * (at your option) any later version.
18 * This program is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 * GNU General Public License for more details.
23 * You should have received a copy of the GNU General Public License along
24 * with this program; if not, write to the Free Software Foundation, Inc.,
25 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
27 #ifndef POLARSSL_RSA_H
28 #define POLARSSL_RSA_H
35 #define POLARSSL_ERR_RSA_BAD_INPUT_DATA -0x4080 /**< Bad input parameters to function. */
36 #define POLARSSL_ERR_RSA_INVALID_PADDING -0x4100 /**< Input data contains invalid padding and is rejected. */
37 #define POLARSSL_ERR_RSA_KEY_GEN_FAILED -0x4180 /**< Something failed during generation of a key. */
38 #define POLARSSL_ERR_RSA_KEY_CHECK_FAILED -0x4200 /**< Key failed to pass the libraries validity check. */
39 #define POLARSSL_ERR_RSA_PUBLIC_FAILED -0x4280 /**< The public key operation failed. */
40 #define POLARSSL_ERR_RSA_PRIVATE_FAILED -0x4300 /**< The private key operation failed. */
41 #define POLARSSL_ERR_RSA_VERIFY_FAILED -0x4380 /**< The PKCS#1 verification failed. */
42 #define POLARSSL_ERR_RSA_OUTPUT_TOO_LARGE -0x4400 /**< The output buffer for decryption is not large enough. */
43 #define POLARSSL_ERR_RSA_RNG_FAILED -0x4480 /**< The random generator failed to generate non-zeros. */
52 #define SIG_RSA_SHA1 5
53 #define SIG_RSA_SHA224 14
54 #define SIG_RSA_SHA256 11
55 #define SIG_RSA_SHA384 12
56 #define SIG_RSA_SHA512 13
61 #define RSA_PKCS_V15 0
62 #define RSA_PKCS_V21 1
67 #define ASN1_STR_CONSTRUCTED_SEQUENCE "\x30"
68 #define ASN1_STR_NULL "\x05"
69 #define ASN1_STR_OID "\x06"
70 #define ASN1_STR_OCTET_STRING "\x04"
72 #define OID_DIGEST_ALG_MDX "\x2A\x86\x48\x86\xF7\x0D\x02\x00"
73 #define OID_HASH_ALG_SHA1 "\x2b\x0e\x03\x02\x1a"
74 #define OID_HASH_ALG_SHA2X "\x60\x86\x48\x01\x65\x03\x04\x02\x00"
76 #define OID_ISO_MEMBER_BODIES "\x2a"
77 #define OID_ISO_IDENTIFIED_ORG "\x2b"
80 * ISO Member bodies OID parts
82 #define OID_COUNTRY_US "\x86\x48"
83 #define OID_RSA_DATA_SECURITY "\x86\xf7\x0d"
86 * ISO Identified organization OID parts
88 #define OID_OIW_SECSIG_SHA1 "\x0e\x03\x02\x1a"
91 * DigestInfo ::= SEQUENCE {
92 * digestAlgorithm DigestAlgorithmIdentifier,
95 * DigestAlgorithmIdentifier ::= AlgorithmIdentifier
97 * Digest ::= OCTET STRING
99 #define ASN1_HASH_MDX \
101 ASN1_STR_CONSTRUCTED_SEQUENCE "\x20" \
102 ASN1_STR_CONSTRUCTED_SEQUENCE "\x0C" \
103 ASN1_STR_OID "\x08" \
105 ASN1_STR_NULL "\x00" \
106 ASN1_STR_OCTET_STRING "\x10" \
109 #define ASN1_HASH_SHA1 \
110 ASN1_STR_CONSTRUCTED_SEQUENCE "\x21" \
111 ASN1_STR_CONSTRUCTED_SEQUENCE "\x09" \
112 ASN1_STR_OID "\x05" \
114 ASN1_STR_NULL "\x00" \
115 ASN1_STR_OCTET_STRING "\x14"
117 #define ASN1_HASH_SHA1_ALT \
118 ASN1_STR_CONSTRUCTED_SEQUENCE "\x1F" \
119 ASN1_STR_CONSTRUCTED_SEQUENCE "\x07" \
120 ASN1_STR_OID "\x05" \
122 ASN1_STR_OCTET_STRING "\x14"
124 #define ASN1_HASH_SHA2X \
125 ASN1_STR_CONSTRUCTED_SEQUENCE "\x11" \
126 ASN1_STR_CONSTRUCTED_SEQUENCE "\x0d" \
127 ASN1_STR_OID "\x09" \
129 ASN1_STR_NULL "\x00" \
130 ASN1_STR_OCTET_STRING "\x00"
133 * \brief RSA context structure
137 int ver
; /*!< always 0 */
138 size_t len
; /*!< size(N) in chars */
140 mpi N
; /*!< public modulus */
141 mpi E
; /*!< public exponent */
143 mpi D
; /*!< private exponent */
144 mpi P
; /*!< 1st prime factor */
145 mpi Q
; /*!< 2nd prime factor */
146 mpi DP
; /*!< D % (P - 1) */
147 mpi DQ
; /*!< D % (Q - 1) */
148 mpi QP
; /*!< 1 / (Q % P) */
150 mpi RN
; /*!< cached R^2 mod N */
151 mpi RP
; /*!< cached R^2 mod P */
152 mpi RQ
; /*!< cached R^2 mod Q */
154 int padding
; /*!< RSA_PKCS_V15 for 1.5 padding and
155 RSA_PKCS_v21 for OAEP/PSS */
156 int hash_id
; /*!< Hash identifier of md_type_t as
157 specified in the md.h header file
158 for the EME-OAEP and EMSA-PSS
168 * \brief Initialize an RSA context
170 * Note: Set padding to RSA_PKCS_V21 for the RSAES-OAEP
171 * encryption scheme and the RSASSA-PSS signature scheme.
173 * \param ctx RSA context to be initialized
174 * \param padding RSA_PKCS_V15 or RSA_PKCS_V21
175 * \param hash_id RSA_PKCS_V21 hash identifier
177 * \note The hash_id parameter is actually ignored
178 * when using RSA_PKCS_V15 padding.
180 void rsa_init( rsa_context
*ctx
,
185 * \brief Generate an RSA keypair
187 * \param ctx RSA context that will hold the key
188 * \param f_rng RNG function
189 * \param p_rng RNG parameter
190 * \param nbits size of the public key in bits
191 * \param exponent public exponent (e.g., 65537)
193 * \note rsa_init() must be called beforehand to setup
196 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
198 int rsa_gen_key( rsa_context
*ctx
,
199 int (*f_rng
)(void *, unsigned char *, size_t),
201 unsigned int nbits
, int exponent
);
204 * \brief Check a public RSA key
206 * \param ctx RSA context to be checked
208 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
210 int rsa_check_pubkey( const rsa_context
*ctx
);
213 * \brief Check a private RSA key
215 * \param ctx RSA context to be checked
217 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
219 int rsa_check_privkey( const rsa_context
*ctx
);
222 * \brief Do an RSA public key operation
224 * \param ctx RSA context
225 * \param input input buffer
226 * \param output output buffer
228 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
230 * \note This function does NOT take care of message
231 * padding. Also, be sure to set input[0] = 0 or assure that
232 * input is smaller than N.
234 * \note The input and output buffers must be large
235 * enough (eg. 128 bytes if RSA-1024 is used).
237 int rsa_public( rsa_context
*ctx
,
238 const unsigned char *input
,
239 unsigned char *output
);
242 * \brief Do an RSA private key operation
244 * \param ctx RSA context
245 * \param input input buffer
246 * \param output output buffer
248 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
250 * \note The input and output buffers must be large
251 * enough (eg. 128 bytes if RSA-1024 is used).
253 int rsa_private( rsa_context
*ctx
,
254 const unsigned char *input
,
255 unsigned char *output
);
258 * \brief Generic wrapper to perform a PKCS#1 encryption using the
259 * mode from the context. Add the message padding, then do an
262 * \param ctx RSA context
263 * \param f_rng RNG function (Needed for padding and PKCS#1 v2.1 encoding)
264 * \param p_rng RNG parameter
265 * \param mode RSA_PUBLIC or RSA_PRIVATE
266 * \param ilen contains the plaintext length
267 * \param input buffer holding the data to be encrypted
268 * \param output buffer that will hold the ciphertext
270 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
272 * \note The output buffer must be as large as the size
273 * of ctx->N (eg. 128 bytes if RSA-1024 is used).
275 int rsa_pkcs1_encrypt( rsa_context
*ctx
,
276 int (*f_rng
)(void *, unsigned char *, size_t),
278 int mode
, size_t ilen
,
279 const unsigned char *input
,
280 unsigned char *output
);
283 * \brief Perform a PKCS#1 v1.5 encryption (RSAES-PKCS1-v1_5-ENCRYPT)
285 * \param ctx RSA context
286 * \param f_rng RNG function (Needed for padding)
287 * \param p_rng RNG parameter
288 * \param mode RSA_PUBLIC or RSA_PRIVATE
289 * \param ilen contains the plaintext length
290 * \param input buffer holding the data to be encrypted
291 * \param output buffer that will hold the ciphertext
293 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
295 * \note The output buffer must be as large as the size
296 * of ctx->N (eg. 128 bytes if RSA-1024 is used).
298 int rsa_rsaes_pkcs1_v15_encrypt( rsa_context
*ctx
,
299 int (*f_rng
)(void *, unsigned char *, size_t),
301 int mode
, size_t ilen
,
302 const unsigned char *input
,
303 unsigned char *output
);
306 * \brief Perform a PKCS#1 v2.1 OAEP encryption (RSAES-OAEP-ENCRYPT)
308 * \param ctx RSA context
309 * \param f_rng RNG function (Needed for padding and PKCS#1 v2.1 encoding)
310 * \param p_rng RNG parameter
311 * \param mode RSA_PUBLIC or RSA_PRIVATE
312 * \param label buffer holding the custom label to use
313 * \param label_len contains the label length
314 * \param ilen contains the plaintext length
315 * \param input buffer holding the data to be encrypted
316 * \param output buffer that will hold the ciphertext
318 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
320 * \note The output buffer must be as large as the size
321 * of ctx->N (eg. 128 bytes if RSA-1024 is used).
323 int rsa_rsaes_oaep_encrypt( rsa_context
*ctx
,
324 int (*f_rng
)(void *, unsigned char *, size_t),
327 const unsigned char *label
, size_t label_len
,
329 const unsigned char *input
,
330 unsigned char *output
);
333 * \brief Generic wrapper to perform a PKCS#1 decryption using the
334 * mode from the context. Do an RSA operation, then remove
335 * the message padding
337 * \param ctx RSA context
338 * \param mode RSA_PUBLIC or RSA_PRIVATE
339 * \param olen will contain the plaintext length
340 * \param input buffer holding the encrypted data
341 * \param output buffer that will hold the plaintext
342 * \param output_max_len maximum length of the output buffer
344 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
346 * \note The output buffer must be as large as the size
347 * of ctx->N (eg. 128 bytes if RSA-1024 is used) otherwise
348 * an error is thrown.
350 int rsa_pkcs1_decrypt( rsa_context
*ctx
,
351 int mode
, size_t *olen
,
352 const unsigned char *input
,
353 unsigned char *output
,
354 size_t output_max_len
);
357 * \brief Perform a PKCS#1 v1.5 decryption (RSAES-PKCS1-v1_5-DECRYPT)
359 * \param ctx RSA context
360 * \param mode RSA_PUBLIC or RSA_PRIVATE
361 * \param olen will contain the plaintext length
362 * \param input buffer holding the encrypted data
363 * \param output buffer that will hold the plaintext
364 * \param output_max_len maximum length of the output buffer
366 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
368 * \note The output buffer must be as large as the size
369 * of ctx->N (eg. 128 bytes if RSA-1024 is used) otherwise
370 * an error is thrown.
372 int rsa_rsaes_pkcs1_v15_decrypt( rsa_context
*ctx
,
373 int mode
, size_t *olen
,
374 const unsigned char *input
,
375 unsigned char *output
,
376 size_t output_max_len
);
379 * \brief Perform a PKCS#1 v2.1 OAEP decryption (RSAES-OAEP-DECRYPT)
381 * \param ctx RSA context
382 * \param mode RSA_PUBLIC or RSA_PRIVATE
383 * \param label buffer holding the custom label to use
384 * \param label_len contains the label length
385 * \param olen will contain the plaintext length
386 * \param input buffer holding the encrypted data
387 * \param output buffer that will hold the plaintext
388 * \param output_max_len maximum length of the output buffer
390 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
392 * \note The output buffer must be as large as the size
393 * of ctx->N (eg. 128 bytes if RSA-1024 is used) otherwise
394 * an error is thrown.
396 int rsa_rsaes_oaep_decrypt( rsa_context
*ctx
,
398 const unsigned char *label
, size_t label_len
,
400 const unsigned char *input
,
401 unsigned char *output
,
402 size_t output_max_len
);
405 * \brief Generic wrapper to perform a PKCS#1 signature using the
406 * mode from the context. Do a private RSA operation to sign
409 * \param ctx RSA context
410 * \param f_rng RNG function (Needed for PKCS#1 v2.1 encoding)
411 * \param p_rng RNG parameter
412 * \param mode RSA_PUBLIC or RSA_PRIVATE
413 * \param hash_id SIG_RSA_RAW, SIG_RSA_MD{2,4,5} or SIG_RSA_SHA{1,224,256,384,512}
414 * \param hashlen message digest length (for SIG_RSA_RAW only)
415 * \param hash buffer holding the message digest
416 * \param sig buffer that will hold the ciphertext
418 * \return 0 if the signing operation was successful,
419 * or an POLARSSL_ERR_RSA_XXX error code
421 * \note The "sig" buffer must be as large as the size
422 * of ctx->N (eg. 128 bytes if RSA-1024 is used).
424 * \note In case of PKCS#1 v2.1 encoding keep in mind that
425 * the hash_id in the RSA context is the one used for the
426 * encoding. hash_id in the function call is the type of hash
427 * that is encoded. According to RFC 3447 it is advised to
428 * keep both hashes the same.
430 int rsa_pkcs1_sign( rsa_context
*ctx
,
431 int (*f_rng
)(void *, unsigned char *, size_t),
435 unsigned int hashlen
,
436 const unsigned char *hash
,
437 unsigned char *sig
);
440 * \brief Perform a PKCS#1 v1.5 signature (RSASSA-PKCS1-v1_5-SIGN)
442 * \param ctx RSA context
443 * \param mode RSA_PUBLIC or RSA_PRIVATE
444 * \param hash_id SIG_RSA_RAW, SIG_RSA_MD{2,4,5} or SIG_RSA_SHA{1,224,256,384,512}
445 * \param hashlen message digest length (for SIG_RSA_RAW only)
446 * \param hash buffer holding the message digest
447 * \param sig buffer that will hold the ciphertext
449 * \return 0 if the signing operation was successful,
450 * or an POLARSSL_ERR_RSA_XXX error code
452 * \note The "sig" buffer must be as large as the size
453 * of ctx->N (eg. 128 bytes if RSA-1024 is used).
455 int rsa_rsassa_pkcs1_v15_sign( rsa_context
*ctx
,
458 unsigned int hashlen
,
459 const unsigned char *hash
,
460 unsigned char *sig
);
463 * \brief Perform a PKCS#1 v2.1 PSS signature (RSASSA-PSS-SIGN)
465 * \param ctx RSA context
466 * \param f_rng RNG function (Needed for PKCS#1 v2.1 encoding)
467 * \param p_rng RNG parameter
468 * \param mode RSA_PUBLIC or RSA_PRIVATE
469 * \param hash_id SIG_RSA_RAW, SIG_RSA_MD{2,4,5} or SIG_RSA_SHA{1,224,256,384,512}
470 * \param hashlen message digest length (for SIG_RSA_RAW only)
471 * \param hash buffer holding the message digest
472 * \param sig buffer that will hold the ciphertext
474 * \return 0 if the signing operation was successful,
475 * or an POLARSSL_ERR_RSA_XXX error code
477 * \note The "sig" buffer must be as large as the size
478 * of ctx->N (eg. 128 bytes if RSA-1024 is used).
480 * \note In case of PKCS#1 v2.1 encoding keep in mind that
481 * the hash_id in the RSA context is the one used for the
482 * encoding. hash_id in the function call is the type of hash
483 * that is encoded. According to RFC 3447 it is advised to
484 * keep both hashes the same.
486 int rsa_rsassa_pss_sign( rsa_context
*ctx
,
487 int (*f_rng
)(void *, unsigned char *, size_t),
491 unsigned int hashlen
,
492 const unsigned char *hash
,
493 unsigned char *sig
);
496 * \brief Generic wrapper to perform a PKCS#1 verification using the
497 * mode from the context. Do a public RSA operation and check
500 * \param ctx points to an RSA public key
501 * \param mode RSA_PUBLIC or RSA_PRIVATE
502 * \param hash_id SIG_RSA_RAW, SIG_RSA_MD{2,4,5} or SIG_RSA_SHA{1,224,256,384,512}
503 * \param hashlen message digest length (for SIG_RSA_RAW only)
504 * \param hash buffer holding the message digest
505 * \param sig buffer holding the ciphertext
507 * \return 0 if the verify operation was successful,
508 * or an POLARSSL_ERR_RSA_XXX error code
510 * \note The "sig" buffer must be as large as the size
511 * of ctx->N (eg. 128 bytes if RSA-1024 is used).
513 * \note In case of PKCS#1 v2.1 encoding keep in mind that
514 * the hash_id in the RSA context is the one used for the
515 * verification. hash_id in the function call is the type of hash
516 * that is verified. According to RFC 3447 it is advised to
517 * keep both hashes the same.
519 int rsa_pkcs1_verify( rsa_context
*ctx
,
522 unsigned int hashlen
,
523 const unsigned char *hash
,
524 unsigned char *sig
);
527 * \brief Perform a PKCS#1 v1.5 verification (RSASSA-PKCS1-v1_5-VERIFY)
529 * \param ctx points to an RSA public key
530 * \param mode RSA_PUBLIC or RSA_PRIVATE
531 * \param hash_id SIG_RSA_RAW, SIG_RSA_MD{2,4,5} or SIG_RSA_SHA{1,224,256,384,512}
532 * \param hashlen message digest length (for SIG_RSA_RAW only)
533 * \param hash buffer holding the message digest
534 * \param sig buffer holding the ciphertext
536 * \return 0 if the verify operation was successful,
537 * or an POLARSSL_ERR_RSA_XXX error code
539 * \note The "sig" buffer must be as large as the size
540 * of ctx->N (eg. 128 bytes if RSA-1024 is used).
542 int rsa_rsassa_pkcs1_v15_verify( rsa_context
*ctx
,
545 unsigned int hashlen
,
546 const unsigned char *hash
,
547 unsigned char *sig
);
550 * \brief Perform a PKCS#1 v2.1 PSS verification (RSASSA-PSS-VERIFY)
551 * \brief Do a public RSA and check the message digest
553 * \param ctx points to an RSA public key
554 * \param mode RSA_PUBLIC or RSA_PRIVATE
555 * \param hash_id SIG_RSA_RAW, SIG_RSA_MD{2,4,5} or SIG_RSA_SHA{1,224,256,384,512}
556 * \param hashlen message digest length (for SIG_RSA_RAW only)
557 * \param hash buffer holding the message digest
558 * \param sig buffer holding the ciphertext
560 * \return 0 if the verify operation was successful,
561 * or an POLARSSL_ERR_RSA_XXX error code
563 * \note The "sig" buffer must be as large as the size
564 * of ctx->N (eg. 128 bytes if RSA-1024 is used).
566 * \note In case of PKCS#1 v2.1 encoding keep in mind that
567 * the hash_id in the RSA context is the one used for the
568 * verification. hash_id in the function call is the type of hash
569 * that is verified. According to RFC 3447 it is advised to
570 * keep both hashes the same.
572 int rsa_rsassa_pss_verify( rsa_context
*ctx
,
575 unsigned int hashlen
,
576 const unsigned char *hash
,
577 unsigned char *sig
);
580 * \brief Free the components of an RSA key
582 * \param ctx RSA Context to free
584 void rsa_free( rsa_context
*ctx
);
587 * \brief Checkup routine
589 * \return 0 if successful, or 1 if the test failed
591 int rsa_self_test( int verbose
);