1 /*

2 * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>

3 *

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:

11 *

12 * The above copyright notice and this permission notice shall be

13 * included in all copies or substantial portions of the Software.

14 *

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

22 * SOFTWARE.

23 */

25 #ifndef BR_BEARSSL_RSA_H__

26 #define BR_BEARSSL_RSA_H__

28 #include <stddef.h>

29 #include <stdint.h>

31 /*

32 * RSA

33 * ---

34 *

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.

38 *

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

44 * tolerated for x[].

45 *

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).

56 *

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.

62 */

64 /*

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.

69 */

77 /*

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.

85 */

100 /*

101 * Type for a public-key engine. The source buffer x[], of size xlen,

102 * is modified in place.

103 *

104 * Returned value is 1 on success, 0 on error.

105 *

106 * If the source buffer length (xlen) does not exactly match the modulus

107 * length, then an error is reported and x[] is unmodified.

108 */

112 /*

113 * Type for a RSA signature verification engine (PKCS#1 v1.5 signatures).

114 * Parameters are:

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.

123 * -- The public key.

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.

126 *

127 * CONSTRAINTS:

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).

131 *

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

135 * returns 0.

136 *

137 * Returned value is 1 on success, 0 on error.

138 *

139 * Implementations of this type need not be constant-time.

140 */

145 /*

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).

149 *

150 * Returned value is 1 on success, 0 on error.

151 */

155 /*

156 * Type for a RSA signature generation engine (PKCS#1 v1.5 signatures).

157 * Parameters are:

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.

167 *

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.

172 *

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.

176 */

181 /*

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.

185 */

198 /*

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.

202 */

215 /*

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[].

220 *

221 * In success, this rturns 1. On error, 0 is returned, and the buffer

222 * contents are indeterminate.

223 */

227 #endif