2 * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
4 * Permission is hereby granted, free of charge, to any person obtaining
5 * a copy of this software and associated documentation files (the
6 * "Software"), to deal in the Software without restriction, including
7 * without limitation the rights to use, copy, modify, merge, publish,
8 * distribute, sublicense, and/or sell copies of the Software, and to
9 * permit persons to whom the Software is furnished to do so, subject to
10 * the following conditions:
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
19 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
25 #ifndef BR_BEARSSL_RSA_H__
26 #define BR_BEARSSL_RSA_H__
35 * A RSA engine consists in two functions, for public-key and private-key
36 * operations (modular exponentiations). In both cases, the same buffer is
37 * used as source and destination.
39 * Key elements are provided as arrays of bytes, in big-endian unsigned
40 * encoding (leading zeros are correctly skipped, hence signed encodings
41 * can also be used). The source/destination array (x[]) is an array of
42 * bytes that, per PKCS#1 rules, MUST have the same length as the modulus,
43 * exactly: missing or extra leading bytes, even of value 0x00, are not
46 * Parameter validation: the engine MUST gracefully handle incorrect key
47 * parameters (e.g. an even modulus); it needs not detect all cases of
48 * incorrect key parameters. For public key operations, the engine MUST
49 * validate the length of x[] (it must match the numerical length, in
50 * bytes, of the modulus); it MUST also check that the provided x[]
51 * decodes to an integer that is numerically less than the modulus. For
52 * private key operation, the engine may assume that the length and
53 * contents of x[] are appropriate (it MUST NOT allow an invalid value
54 * to result in a buffer overflow, but an invalid input x[] may result
55 * in an undetected invalid output).
57 * Constant-time requirements: the following information may leak through
58 * execution time and memory access pattern:
59 * -- the actual bit length of the modulus;
60 * -- the actual bit length of each prime factor;
61 * -- the byte lengths as provided to the function calls.
65 * A structure type for a RSA public key, consisting in a modulus and
66 * a public exponent, encoded in unsigned big-endian format. The two
67 * arrays may be larger than needed; functions that accept a RSA public
68 * key are supposed to check the actual modulus length when needed.
78 * A structure type for a RSA private key. The key elements are:
79 * n_bitlen modulus bit length
80 * p prime modulus factor
81 * q other prime modulus factor (may be greater or lower than p)
82 * dp private exponent, reduced modulo p-1
83 * dq private exponent, reduced modulo q-1
84 * iq CRT coefficient: q*iq = 1 mod p.
101 * Type for a public-key engine. The source buffer x[], of size xlen,
102 * is modified in place.
104 * Returned value is 1 on success, 0 on error.
106 * If the source buffer length (xlen) does not exactly match the modulus
107 * length, then an error is reported and x[] is unmodified.
109 typedef uint32_t (*br_rsa_public
)(unsigned char *x
, size_t xlen
,
110 const br_rsa_public_key
*pk
);
113 * Type for a RSA signature verification engine (PKCS#1 v1.5 signatures).
115 * -- The signature itself. The provided array is NOT modified.
116 * -- The encoded OID for the hash function. The provided array must begin
117 * with a single byte that contains the length of the OID value (in
118 * bytes), followed by exactly that many bytes.
119 * This parameter may be NULL, in which case the raw hash value should
120 * be used with the PKCS#1 v1.5 "type 1" padding (used in SSL/TLS up
121 * to TLS-1.1, with a 36-byte hash value).
122 * -- The hash output length, in bytes.
124 * -- An output buffer for the hash value. The caller must still compare
125 * it with the hash of the data over which the signature is computed.
128 * -- Hash length MUST be no more than 64 bytes.
129 * -- OID value length MUST be no more than 32 bytes (i.e. hash_oid[0]
130 * must have a value in the 0..32 range, inclusive).
132 * This function verifies that the signature length (xlen) matches the
133 * modulus length (this function returns 0 on mismatch). If the modulus
134 * size exceeds the maximum supported RSA size, then the function also
137 * Returned value is 1 on success, 0 on error.
139 * Implementations of this type need not be constant-time.
141 typedef uint32_t (*br_rsa_pkcs1_vrfy
)(const unsigned char *x
, size_t xlen
,
142 const unsigned char *hash_oid
, size_t hash_len
,
143 const br_rsa_public_key
*pk
, unsigned char *hash_out
);
146 * Type for a private-key engine. The x[] buffer is modified in place, and
147 * its length is inferred from the modulus length (x[] is assumed to have
148 * a length of (sk->n_bitlen+7)/8 bytes).
150 * Returned value is 1 on success, 0 on error.
152 typedef uint32_t (*br_rsa_private
)(unsigned char *x
,
153 const br_rsa_private_key
*sk
);
156 * Type for a RSA signature generation engine (PKCS#1 v1.5 signatures).
158 * -- The encoded OID for the hash function. The provided array must begin
159 * with a single byte that contains the length of the OID value (in
160 * bytes), followed by exactly that many bytes.
161 * This parameter may be NULL, in which case the raw hash value should
162 * be used with the PKCS#1 v1.5 "type 1" padding (used in SSL/TLS up
163 * to TLS-1.1, with a 36-byte hash value).
164 * -- The hashed data, and length (in bytes).
165 * -- The private key.
166 * -- The output buffer.
168 * Returned value is 1 on success, 0 on error. Error conditions include
169 * a too small modulus for the provided hash OID and value, or some
170 * invalid key parameters. The signature length is exactly
171 * (sk->n_bitlen+7)/8 bytes.
173 * This function is expected to be constant-time with regards to the
174 * private key bytes (lengths of the modulus and the individual factors
175 * may leak, though) and to the hashed data.
177 typedef uint32_t (*br_rsa_pkcs1_sign
)(const unsigned char *hash_oid
,
178 const unsigned char *hash
, size_t hash_len
,
179 const br_rsa_private_key
*sk
, unsigned char *x
);
182 * RSA "i32" engine. Integers are internally represented as arrays of
183 * 32-bit integers, and the core multiplication primitive is the
184 * 32x32->64 multiplication.
187 uint32_t br_rsa_i32_public(unsigned char *x
, size_t xlen
,
188 const br_rsa_public_key
*pk
);
189 uint32_t br_rsa_i32_pkcs1_vrfy(const unsigned char *x
, size_t xlen
,
190 const unsigned char *hash_oid
, size_t hash_len
,
191 const br_rsa_public_key
*pk
, unsigned char *hash_out
);
192 uint32_t br_rsa_i32_private(unsigned char *x
,
193 const br_rsa_private_key
*sk
);
194 uint32_t br_rsa_i32_pkcs1_sign(const unsigned char *hash_oid
,
195 const unsigned char *hash
, size_t hash_len
,
196 const br_rsa_private_key
*sk
, unsigned char *x
);
199 * RSA "i31" engine. Similar to i32, but only 31 bits are used per 32-bit
200 * word. This uses slightly more stack space (about 4% more) and code
201 * space, but it quite faster.
204 uint32_t br_rsa_i31_public(unsigned char *x
, size_t xlen
,
205 const br_rsa_public_key
*pk
);
206 uint32_t br_rsa_i31_pkcs1_vrfy(const unsigned char *x
, size_t xlen
,
207 const unsigned char *hash_oid
, size_t hash_len
,
208 const br_rsa_public_key
*pk
, unsigned char *hash_out
);
209 uint32_t br_rsa_i31_private(unsigned char *x
,
210 const br_rsa_private_key
*sk
);
211 uint32_t br_rsa_i31_pkcs1_sign(const unsigned char *hash_oid
,
212 const unsigned char *hash
, size_t hash_len
,
213 const br_rsa_private_key
*sk
, unsigned char *x
);
216 * Perform RSA decryption for SSL/TLS. This function uses the provided core
217 * and private key to decrypt the message in data[] of size 'len'. The
218 * buffer is modified; the decryption result MUST have length 48, and
219 * is written into the first 48 bytes of data[].
221 * In success, this rturns 1. On error, 0 is returned, and the buffer
222 * contents are indeterminate.
224 uint32_t br_rsa_ssl_decrypt(br_rsa_private core
, const br_rsa_private_key
*sk
,
225 unsigned char *data
, size_t len
);