4 * Copyright (C) 2006-2010, Brainspark B.V.
6 * This file is part of PolarSSL (http://www.polarssl.org)
7 * Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.org>
11 * This program is free software; you can redistribute it and/or modify
12 * it under the terms of the GNU General Public License as published by
13 * the Free Software Foundation; either version 2 of the License, or
14 * (at your option) any later version.
16 * This program is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU General Public License for more details.
21 * You should have received a copy of the GNU General Public License along
22 * with this program; if not, write to the Free Software Foundation, Inc.,
23 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
25 #ifndef POLARSSL_RSA_H
26 #define POLARSSL_RSA_H
28 #include "polarssl/bignum.h"
33 #define POLARSSL_ERR_RSA_BAD_INPUT_DATA -0x0400
34 #define POLARSSL_ERR_RSA_INVALID_PADDING -0x0410
35 #define POLARSSL_ERR_RSA_KEY_GEN_FAILED -0x0420
36 #define POLARSSL_ERR_RSA_KEY_CHECK_FAILED -0x0430
37 #define POLARSSL_ERR_RSA_PUBLIC_FAILED -0x0440
38 #define POLARSSL_ERR_RSA_PRIVATE_FAILED -0x0450
39 #define POLARSSL_ERR_RSA_VERIFY_FAILED -0x0460
40 #define POLARSSL_ERR_RSA_OUTPUT_TOO_LARGE -0x0470
41 #define POLARSSL_ERR_RSA_RNG_FAILED -0x0480
50 #define SIG_RSA_SHA1 5
51 #define SIG_RSA_SHA224 14
52 #define SIG_RSA_SHA256 11
53 #define SIG_RSA_SHA384 12
54 #define SIG_RSA_SHA512 13
59 #define RSA_PKCS_V15 0
60 #define RSA_PKCS_V21 1
65 #define ASN1_STR_CONSTRUCTED_SEQUENCE "\x30"
66 #define ASN1_STR_NULL "\x05"
67 #define ASN1_STR_OID "\x06"
68 #define ASN1_STR_OCTET_STRING "\x04"
70 #define OID_DIGEST_ALG_MDX "\x2A\x86\x48\x86\xF7\x0D\x02\x00"
71 #define OID_HASH_ALG_SHA1 "\x2b\x0e\x03\x02\x1a"
72 #define OID_HASH_ALG_SHA2X "\x60\x86\x48\x01\x65\x03\x04\x02\x00"
74 #define OID_ISO_MEMBER_BODIES "\x2a"
75 #define OID_ISO_IDENTIFIED_ORG "\x2b"
78 * ISO Member bodies OID parts
80 #define OID_COUNTRY_US "\x86\x48"
81 #define OID_RSA_DATA_SECURITY "\x86\xf7\x0d"
84 * ISO Identified organization OID parts
86 #define OID_OIW_SECSIG_SHA1 "\x0e\x03\x02\x1a"
89 * DigestInfo ::= SEQUENCE {
90 * digestAlgorithm DigestAlgorithmIdentifier,
93 * DigestAlgorithmIdentifier ::= AlgorithmIdentifier
95 * Digest ::= OCTET STRING
97 #define ASN1_HASH_MDX \
99 ASN1_STR_CONSTRUCTED_SEQUENCE "\x20" \
100 ASN1_STR_CONSTRUCTED_SEQUENCE "\x0C" \
101 ASN1_STR_OID "\x08" \
103 ASN1_STR_NULL "\x00" \
104 ASN1_STR_OCTET_STRING "\x10" \
107 #define ASN1_HASH_SHA1 \
108 ASN1_STR_CONSTRUCTED_SEQUENCE "\x21" \
109 ASN1_STR_CONSTRUCTED_SEQUENCE "\x09" \
110 ASN1_STR_OID "\x05" \
112 ASN1_STR_NULL "\x00" \
113 ASN1_STR_OCTET_STRING "\x14"
115 #define ASN1_HASH_SHA2X \
116 ASN1_STR_CONSTRUCTED_SEQUENCE "\x11" \
117 ASN1_STR_CONSTRUCTED_SEQUENCE "\x0d" \
118 ASN1_STR_OID "\x09" \
120 ASN1_STR_NULL "\x00" \
121 ASN1_STR_OCTET_STRING "\x00"
124 * \brief RSA context structure
128 int ver
; /*!< always 0 */
129 int len
; /*!< size(N) in chars */
131 mpi N
; /*!< public modulus */
132 mpi E
; /*!< public exponent */
134 mpi D
; /*!< private exponent */
135 mpi P
; /*!< 1st prime factor */
136 mpi Q
; /*!< 2nd prime factor */
137 mpi DP
; /*!< D % (P - 1) */
138 mpi DQ
; /*!< D % (Q - 1) */
139 mpi QP
; /*!< 1 / (Q % P) */
141 mpi RN
; /*!< cached R^2 mod N */
142 mpi RP
; /*!< cached R^2 mod P */
143 mpi RQ
; /*!< cached R^2 mod Q */
145 int padding
; /*!< 1.5 or OAEP/PSS */
146 int hash_id
; /*!< hash identifier */
155 * \brief Initialize an RSA context
157 * \param ctx RSA context to be initialized
158 * \param padding RSA_PKCS_V15 or RSA_PKCS_V21
159 * \param hash_id RSA_PKCS_V21 hash identifier
161 * \note The hash_id parameter is actually ignored
162 * when using RSA_PKCS_V15 padding.
164 * \note Currently, RSA_PKCS_V21 padding
167 void rsa_init( rsa_context
*ctx
,
172 * \brief Generate an RSA keypair
174 * \param ctx RSA context that will hold the key
175 * \param f_rng RNG function
176 * \param p_rng RNG parameter
177 * \param nbits size of the public key in bits
178 * \param exponent public exponent (e.g., 65537)
180 * \note rsa_init() must be called beforehand to setup
183 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
185 int rsa_gen_key( rsa_context
*ctx
,
186 int (*f_rng
)(void *),
188 int nbits
, int exponent
);
191 * \brief Check a public RSA key
193 * \param ctx RSA context to be checked
195 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
197 int rsa_check_pubkey( const rsa_context
*ctx
);
200 * \brief Check a private RSA key
202 * \param ctx RSA context to be checked
204 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
206 int rsa_check_privkey( const rsa_context
*ctx
);
209 * \brief Do an RSA public key operation
211 * \param ctx RSA context
212 * \param input input buffer
213 * \param output output buffer
215 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
217 * \note This function does NOT take care of message
218 * padding. Also, be sure to set input[0] = 0 or assure that
219 * input is smaller than N.
221 * \note The input and output buffers must be large
222 * enough (eg. 128 bytes if RSA-1024 is used).
224 int rsa_public( rsa_context
*ctx
,
225 const unsigned char *input
,
226 unsigned char *output
);
229 * \brief Do an RSA private key operation
231 * \param ctx RSA context
232 * \param input input buffer
233 * \param output output buffer
235 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
237 * \note The input and output buffers must be large
238 * enough (eg. 128 bytes if RSA-1024 is used).
240 int rsa_private( rsa_context
*ctx
,
241 const unsigned char *input
,
242 unsigned char *output
);
245 * \brief Add the message padding, then do an RSA operation
247 * \param ctx RSA context
248 * \param f_rng RNG function
249 * \param p_rng RNG parameter
250 * \param mode RSA_PUBLIC or RSA_PRIVATE
251 * \param ilen contains the plaintext length
252 * \param input buffer holding the data to be encrypted
253 * \param output buffer that will hold the ciphertext
255 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
257 * \note The output buffer must be as large as the size
258 * of ctx->N (eg. 128 bytes if RSA-1024 is used).
260 int rsa_pkcs1_encrypt( rsa_context
*ctx
,
261 int (*f_rng
)(void *),
264 const unsigned char *input
,
265 unsigned char *output
);
268 * \brief Do an RSA operation, then remove the message padding
270 * \param ctx RSA context
271 * \param mode RSA_PUBLIC or RSA_PRIVATE
272 * \param input buffer holding the encrypted data
273 * \param output buffer that will hold the plaintext
274 * \param olen will contain the plaintext length
275 * \param output_max_len maximum length of the output buffer
277 * \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
279 * \note The output buffer must be as large as the size
280 * of ctx->N (eg. 128 bytes if RSA-1024 is used) otherwise
281 * an error is thrown.
283 int rsa_pkcs1_decrypt( rsa_context
*ctx
,
285 const unsigned char *input
,
286 unsigned char *output
,
287 int output_max_len
);
290 * \brief Do a private RSA to sign a message digest
292 * \param ctx RSA context
293 * \param mode RSA_PUBLIC or RSA_PRIVATE
294 * \param hash_id SIG_RSA_RAW, SIG_RSA_MD{2,4,5} or SIG_RSA_SHA{1,224,256,384,512}
295 * \param hashlen message digest length (for SIG_RSA_RAW only)
296 * \param hash buffer holding the message digest
297 * \param sig buffer that will hold the ciphertext
299 * \return 0 if the signing operation was successful,
300 * or an POLARSSL_ERR_RSA_XXX error code
302 * \note The "sig" buffer must be as large as the size
303 * of ctx->N (eg. 128 bytes if RSA-1024 is used).
305 int rsa_pkcs1_sign( rsa_context
*ctx
,
309 const unsigned char *hash
,
310 unsigned char *sig
);
313 * \brief Do a public RSA and check the message digest
315 * \param ctx points to an RSA public key
316 * \param mode RSA_PUBLIC or RSA_PRIVATE
317 * \param hash_id SIG_RSA_RAW, SIG_RSA_MD{2,4,5} or SIG_RSA_SHA{1,224,256,384,512}
318 * \param hashlen message digest length (for SIG_RSA_RAW only)
319 * \param hash buffer holding the message digest
320 * \param sig buffer holding the ciphertext
322 * \return 0 if the verify operation was successful,
323 * or an POLARSSL_ERR_RSA_XXX error code
325 * \note The "sig" buffer must be as large as the size
326 * of ctx->N (eg. 128 bytes if RSA-1024 is used).
328 int rsa_pkcs1_verify( rsa_context
*ctx
,
332 const unsigned char *hash
,
333 unsigned char *sig
);
336 * \brief Free the components of an RSA key
338 * \param ctx RSA Context to free
340 void rsa_free( rsa_context
*ctx
);
343 * \brief Checkup routine
345 * \return 0 if successful, or 1 if the test failed
347 int rsa_self_test( int verbose
);