1 /* Copyright (c) (2010,2011,2012,2014,2015,2016,2017,2018,2019,2020) Apple Inc. All rights reserved.
2 *
3 * corecrypto is licensed under Apple Inc.’s Internal Use License Agreement (which
4 * is contained in the License.txt file distributed with corecrypto) and only to
5 * people who accept that license. IMPORTANT: Any license rights granted to you by
6 * Apple Inc. (if any) are limited to internal use within your organization only on
7 * devices and computers you own or control, for the sole purpose of verifying the
8 * security characteristics and correct functioning of the Apple Software. You may
9 * not, directly or indirectly, redistribute the Apple Software or any portions thereof.
10 */
11
12 #ifndef _CORECRYPTO_CCRSA_H_
13 #define _CORECRYPTO_CCRSA_H_
14
15 #include <corecrypto/cc.h>
16 #include <corecrypto/ccdigest.h>
17 #include <corecrypto/ccrng.h>
18 #include <corecrypto/cczp.h>
19 #include <corecrypto/cc_fault_canary.h>
20 #include <stdbool.h>
21
22 // Apple does not generate keys of greater than 4096 bits
23 // This limit is relaxed to accommodate potential third-party consumers
24 #define CCRSA_KEYGEN_MAX_NBITS 8192
25
26 struct ccrsa_full_ctx {
27 __CCZP_ELEMENTS_DEFINITIONS(pb_)
28 } CC_ALIGNED(CCN_UNIT_SIZE);
29
30 struct ccrsa_pub_ctx {
31 __CCZP_ELEMENTS_DEFINITIONS(pb_)
32 } CC_ALIGNED(CCN_UNIT_SIZE);
33
34 struct ccrsa_priv_ctx {
35 __CCZP_ELEMENTS_DEFINITIONS(pv_)
36 } CC_ALIGNED(CCN_UNIT_SIZE);
37
38 typedef struct ccrsa_full_ctx* ccrsa_full_ctx_t;
39 typedef struct ccrsa_pub_ctx* ccrsa_pub_ctx_t;
40 typedef struct ccrsa_priv_ctx* ccrsa_priv_ctx_t;
41
42 /*
43 public key cczp d=e^-1 mod lambda(m) priv key cczp priv key cczq dp, dq, qinv
44 | | | | |
45 | | | | |
46 +-------+------+-------+------++------++-------+------+---------++-------+------+---------++-------+-------+---------+
47 | zm_hd | m[n] |mr[n+1]| e[n] || d[n] || zp_hd |p[n/2]|pr[n/2+1]|| zq_hd |q[n/2]|qr[n/2+1]||dp[n/2]|dq[n/2]|qinv[n/2]|
48 +-------+------+-------+------++------++-------+------+---------++-------+------+---------++-------+-------+---------+
49 */
50
51 /* Return the size of an ccec_full_ctx where each ccn is _size_ bytes. Get _size_ through ccn_sizeof(nbits) */
52
53 /* Return the size of an ccec_full_ctx where each ccn is _size_ bytes. */
54
55 #define ccrsa_pub_ctx_size(_size_) (sizeof(struct cczp) + CCN_UNIT_SIZE + 3 * (_size_))
56 #define ccrsa_priv_ctx_size(_size_) ((sizeof(struct cczp) + CCN_UNIT_SIZE) * 2 + 7 * ccn_sizeof(ccn_bitsof_size(_size_)/2 + 1))
57 #define ccrsa_full_ctx_size(_size_) (ccrsa_pub_ctx_size(_size_) + _size_ + ccrsa_priv_ctx_size(_size_))
58
59 /* Declare a fully scheduled rsa key. Size is the size in bytes each ccn in
60 the key. For example to declare (on the stack or in a struct) a 1021 bit
61 rsa public key named foo use ccrsa_pub_ctx_decl(ccn_sizeof(1021), foo).
62 */
63 #define ccrsa_full_ctx_decl(_size_, _name_) cc_ctx_decl(struct ccrsa_full_ctx, ccrsa_full_ctx_size(_size_), _name_)
64 #define ccrsa_full_ctx_clear(_size_, _name_) cc_clear(ccrsa_full_ctx_size(_size_), _name_)
65 #define ccrsa_pub_ctx_decl(_size_, _name_) cc_ctx_decl(struct ccrsa_pub_ctx, ccrsa_pub_ctx_size(_size_), _name_)
66 #define ccrsa_pub_ctx_clear(_size_, _name_) cc_clear(ccrsa_pub_ctx_size(_size_), _name_)
67
68 // accessors to ccrsa full and public key fields. */
69 // The offsets are computed using pb_ccn. If any object other than ccrsa_full_ctx_t
70 // or ccrsa_pub_ctx_t is passed to the macros, compiler error is generated.
71
72 #define ccrsa_ctx_zm(_ctx_) ((cczp_t)(_ctx_))
73 #define ccrsa_ctx_n(_ctx_) (ccrsa_ctx_zm(_ctx_)->n)
74 #define ccrsa_ctx_m(_ctx_) ((_ctx_)->pb_ccn)
75
76 #define ccrsa_ctx_e(_ctx_) (ccrsa_ctx_m(_ctx_) + 2 * ccrsa_ctx_n(_ctx_) + 1)
77 #define ccrsa_ctx_d(_ctx_) (ccrsa_ctx_m(_ctx_) + 3 * ccrsa_ctx_n(_ctx_) + 1)
78
79 // accessors to ccrsa private key fields
80 // The offsets are computed using pv_ccn. If any object other than ccrsa_priv_ctx_t
81 // is passed to the macros, compiler error is generated.
82 #define ccrsa_ctx_private_zp(FK) ((cczp_t)ccrsa_get_private_ctx_ptr(FK))
83 #define ccrsa_ctx_private_zq(FK) ((cczp_t)((ccrsa_get_private_ctx_ptr(FK))->pv_ccn + 2 * ccrsa_ctx_private_zp(FK)->n + 1))
84 #define ccrsa_ctx_private_dp(FK) ((ccrsa_get_private_ctx_ptr(FK))->pv_ccn + 4 * ccrsa_ctx_private_zp(FK)->n + 2 + ccn_nof_size(sizeof(struct cczp)))
85 #define ccrsa_ctx_private_dq(FK) ((ccrsa_get_private_ctx_ptr(FK))->pv_ccn + 5 * ccrsa_ctx_private_zp(FK)->n + 2 + ccn_nof_size(sizeof(struct cczp)))
86 #define ccrsa_ctx_private_qinv(FK) ((ccrsa_get_private_ctx_ptr(FK))->pv_ccn + 6 * ccrsa_ctx_private_zp(FK)->n + 2 + ccn_nof_size(sizeof(struct cczp)))
87
88 /* rvalue accessors to ccec_key fields. */
89 CC_INLINE
ccrsa_get_private_ctx_ptr(ccrsa_full_ctx_t fk)90 ccrsa_priv_ctx_t ccrsa_get_private_ctx_ptr(ccrsa_full_ctx_t fk) {
91 ccrsa_priv_ctx_t priv = (ccrsa_priv_ctx_t)(ccrsa_ctx_d(fk)+ccrsa_ctx_n(fk));
92 return priv;
93 }
94
95 /*!
96 @function ccrsa_ctx_public
97 @abstract gets the public key from full key
98 @param fk RSA full key
99 @result Returns RSA public ker
100 */
101 CC_INLINE
ccrsa_ctx_public(ccrsa_full_ctx_t fk)102 ccrsa_pub_ctx_t ccrsa_ctx_public(ccrsa_full_ctx_t fk) {
103 return (ccrsa_pub_ctx_t) fk;
104 }
105
106 /*!
107 @function ccrsa_pubkeylength
108 @abstract Compute the actual bit length of the RSA key (bit length of the modulus)
109 @param pubk An initialized RSA public key
110 @result bit length of the RSA key
111 */
112 CC_NONNULL_ALL
113 size_t ccrsa_pubkeylength(ccrsa_pub_ctx_t pubk);
114
115 /* PKCS1 pad_markers */
116 #define CCRSA_PKCS1_PAD_SIGN 1
117 #define CCRSA_PKCS1_PAD_ENCRYPT 2
118
119 /*!
120 @function ccrsa_init_pub
121 @abstract Initialize an RSA public key structure based on modulus and exponent. Values are copied into the structure.
122 @param pubk allocated public key structure (see requirements below)
123 @param modulus cc_unit array of the modulus
124 @param exponent cc_unit array of the exponent
125 @result CCERR_OK if no error
126
127 @discussion ccrsa_ctx_n(pubk) must have been initialized based on the modulus size, typically using ccn_nof_size(mod_nbytes).
128 The public key structure pubk is typically allocated with ccrsa_pub_ctx_decl(ccn_sizeof_size(mod_nbytes), pubk);
129 */
130 CC_NONNULL_ALL
131 int ccrsa_init_pub(ccrsa_pub_ctx_t pubk, const cc_unit *modulus,
132 const cc_unit *exponent);
133
134 /*! @function ccrsa_make_priv
135 @abstract Initializes an RSA public and private key given the public
136 exponent e and prime factors p and q.
137
138 @param full_ctx Initialized context with ccrsa_ctx_n(full_ctx) set to 2*ccn_nof_size(p_nbytes)
139 @param e_nbytes Number of bytes of public exponent e.
140 @param e_bytes Public exponent e in Big Endian.
141 @param p_nbytes Number of bytes of prime factor p.
142 @param p_bytes Prime factor p in Big Endian.
143 @param q_nbytes Number of bytes of prime factor q.
144 @param q_bytes Prime factor q in Big Endian.
145
146 @return 0 iff successful.
147
148 @discussion ccrsa_ctx_n(full_ctx) must already be set to 2*ccn_nof_size(p_mbytes), with the expectation that p_nbytes>q_nbytes.
149 e is the public exponent, and e_nbytes<= 2*p_nbytes.
150 The output is a fully formed RSA context with N=pq, d=e^{-1} mod lambda(N), and appropriate inverses of different associated values precomputed
151 to speed computation.
152 */
153 int ccrsa_make_priv(ccrsa_full_ctx_t full_ctx,
154 size_t e_nbytes, const uint8_t *e_bytes,
155 size_t p_nbytes, const uint8_t *p_bytes,
156 size_t q_nbytes, const uint8_t *q_bytes);
157
158 /*! @function ccrsa_recover_priv
159 @abstract Initializes an RSA public and private key given the modulus m,
160 the public exponent e and the private exponent d.
161
162 @discussion Follows the algorithm described by
163 NIST SP 800-56B, Appendix C, "Prime Factory Recovery".
164
165 @param full_ctx Initialized context with ccrsa_ctx_n(full_ctx) set to ccn_nof_size(m_nbytes)
166 @param m_nbytes Number of bytes of modulus m.
167 @param m_bytes Modulus m in Big Endian.
168 @param e_nbytes Number of bytes of public exponent e.
169 @param e_bytes Public exponent e in Big Endian.
170 @param d_nbytes Number of bytes of private exponent d.
171 @param d_bytes Private exponent d in Big Endian.
172 @param rng RNG instance.
173
174 @return 0 iff successful.
175 */
176 int ccrsa_recover_priv(ccrsa_full_ctx_t full_ctx,
177 size_t m_nbytes, const uint8_t *m_bytes,
178 size_t e_nbytes, const uint8_t *e_bytes,
179 size_t d_nbytes, const uint8_t *d_bytes,
180 struct ccrng_state *rng);
181
182 /*!
183 @function ccrsa_make_pub
184 @abstract Initialize public key based on modulus and public exponent as big endian byte arrays;
185
186 @param pubk allocated public key structure (see requirements below)
187 @param exp_nbytes Number of bytes in big endian exponent.
188 @param exp Pointer to big endian exponent e (may have leading 0's).
189 @param mod_nbytes Number of bytes in big endian modulus.
190 @param mod Pointer to big endian to rsa modulus N.
191 @result 0 iff successful.
192
193 @discussion ccrsa_ctx_n(pubk) must have been initialized based on the modulus size, typically using ccn_nof_size(mod_nbytes).
194 The public key structure pubk is typically allocated with ccrsa_pub_ctx_decl(ccn_sizeof_size(mod_nbytes), pubk);
195 */
196
197 CC_NONNULL((1, 3, 5))
198 int ccrsa_make_pub(ccrsa_pub_ctx_t pubk,
199 size_t exp_nbytes, const uint8_t *exp,
200 size_t mod_nbytes, const uint8_t *mod);
201
202 /*!
203 @function ccrsa_pub_crypt
204 @abstract Perform an RSA public key operation: (in)^e mod m
205 @param key initialized public key defining e and m
206 @param out result of the operation, at least ccrsa_key_n(key) cc_units must have been allocated
207 @param in base of the exponentiation, of size ccrsa_key_n(key)
208 @result CCERR_OK if no error
209
210 @discussion Input to this function must not be secrets as the execution flow may expose their values
211 Clients can use ccn_read_uint() to convert bytes to cc_units to use for this API.
212 */
213 CC_NONNULL((1, 2, 3))
214 int ccrsa_pub_crypt(ccrsa_pub_ctx_t key, cc_unit *out, const cc_unit *in);
215
216 /*!
217 @function ccrsa_generate_key
218 @abstract Generate a nbit RSA key pair.
219
220 @param nbits Bit size requested for the key
221 @param fk Allocated context where the generated key will be stored
222 @param e_nbytes Byte size of the input public exponent
223 @param e_bytes Input public exponent in big endian. Recommend value is {0x01, 0x00, 0x01}
224 @param rng Random Number generator used.
225 @result CCERR_OK if no error
226
227 @discussion
228 fk should be allocated using ccrsa_full_ctx_decl(ccn_sizeof(nbits), fk).
229 The unsigned big endian byte array exponent e of length e_size is used as the exponent. It's an error to call this function with an exponent larger than nbits
230 */
231 CC_NONNULL_ALL
232 int ccrsa_generate_key(size_t nbits, ccrsa_full_ctx_t fk,
233 size_t e_nbytes, const void *e_bytes, struct ccrng_state *rng) CC_WARN_RESULT;
234
235 /*!
236 @function ccrsa_generate_fips186_key
237 @abstract Generate a nbit RSA key pair in conformance with FIPS186-4 standard.
238
239 @param nbits Bit size requested for the key
240 @param fk Allocated context where the generated key will be stored
241 @param e_nbytes Byte size of the input public exponent
242 @param e_bytes Input public exponent in big endian. Recommend value is {0x01, 0x00, 0x01}
243 @param rng Random Number generator used for p and q
244 @param rng_mr Random Number generator only used for the primality check
245 @result CCERR_OK if no error
246
247 @discussion
248 fk should be allocated using ccrsa_full_ctx_decl(ccn_sizeof(nbits), fk).
249 rng and rng_mr shoud be set to the same value. The distinction is only relevant for testing
250 */
251 CC_NONNULL_ALL int
252 ccrsa_generate_fips186_key(size_t nbits, ccrsa_full_ctx_t fk,
253 size_t e_nbytes, const void *e_bytes,
254 struct ccrng_state *rng, struct ccrng_state *rng_mr) CC_WARN_RESULT;
255
256
257
258 /* Construct RSA key from fix input in conformance with FIPS186-4 standard */
259
260 /*!
261 @function ccrsa_make_fips186_key
262 @abstract Initialize an RSA full key from explicit inputs necessary for validating conformance to FIPS186-4
263
264 @param nbits size in bits of the key to construct
265 @param e_n Size in cc_unit of the public exponent
266 @param e Public exponent represented in cc_units
267 @param xp1_nbytes Size in byte of the first seed for the construction of p
268 @param xp1 First seed for the construction of p
269 @param xp2_nbytes Size in byte of the second seed for the construction of p
270 @param xp2 Second seed for the construction of p
271 @param xp_nbytes Size in byte of the large seed for the construction of p
272 @param xp large seed for the construction of p
273 @param xq1_nbytes Size in byte of the first seed for the construction of q
274 @param xq1 First seed for the construction of q
275 @param xq2_nbytes Size in byte of the second seed for the construction of q
276 @param xq2 Second seed for the construction of q
277 @param xq_nbytes Size in byte of the large seed for the construction of q
278 @param xq large seed for the construction of q
279 @param fk Allocated context where the output constructed key is stored
280 @param np Pointer to the size in cc_unit of the buffer for the output prime factor p. Updated with actual size.
281 @param r_p Copy of the output prime factor p
282 @param nq Pointer to the size in cc_unit of the buffer for the output prime factor q. Updated with actual size.
283 @param r_q Copy of the output prime factor q
284 @param nm Pointer to the size in cc_unit of the buffer for the output modulus m=p*q. Updated with actual size.
285 @param r_m Copy of the output modulus m=p*q
286 @param nd Pointer to the size in cc_unit of the buffer for the output private exponent d. Updated with actual size.
287 @param r_d Copy of the output private exponent d
288 @result 0 iff successful.
289
290 @discussion
291 fk should be allocated using ccrsa_full_ctx_decl(ccn_sizeof(nbits), fk).
292 */
293
294 CC_NONNULL((3, 5, 7, 9, 11, 13, 15, 16))
295 int
296 ccrsa_make_fips186_key(size_t nbits,
297 const cc_size e_n, const cc_unit *e,
298 const cc_size xp1_nbytes, const cc_unit *xp1, const cc_size xp2_nbytes, const cc_unit *xp2,
299 const cc_size xp_nbytes, const cc_unit *xp,
300 const cc_size xq1_nbytes, const cc_unit *xq1, const cc_size xq2_nbytes, const cc_unit *xq2,
301 const cc_size xq_nbytes, const cc_unit *xq,
302 ccrsa_full_ctx_t fk,
303 cc_size *np, cc_unit *r_p,
304 cc_size *nq, cc_unit *r_q,
305 cc_size *nm, cc_unit *r_m,
306 cc_size *nd, cc_unit *r_d);
307
308 /*
309 Signing and Verification algorithms
310 */
311
312 /*!
313 @function ccrsa_sign_pss
314
315 @brief ccrsa_sign_pss() generates RSASSA-PSS signature in PKCS1-V2 format given an input digest
316
317 @param key The RSA key
318 @param hashAlgorithm The hash algorithm used to generate mHash from the original message. It is also used inside the PSS encoding function.
319 @param MgfHashAlgorithm The hash algorithm for thr mask generation function
320 @param rng Random number geberator to generate salt in PSS encoding
321 @param salt_nbytes Intended length of the salt
322 @param digest_nbytes Length of message hash . Must be equal to hashAlgorithm->output_size
323 @param digest The input that needs to be signed. This is the hash of message M with length of hLen
324 @param sig_nbytes The length of generated signature in bytes, which equals the size of the RSA modulus.
325 @param sig The signature output
326 @return 0:ok, non-zero:error
327
328 @discussion
329 note that in RSASSA-PSS, salt length is part of the signature as specified in ASN1
330 RSASSA-PSS-params ::= SEQUENCE {
331 hashAlgorithm [0] HashAlgorithm DEFAULT sha1,
332 maskGenAlgorithm [1] MaskGenAlgorithm DEFAULT mgf1SHA1,
333 saltLength [2] INTEGER DEFAULT 20,
334 trailerField [3] TrailerField DEFAULT trailerFieldBC
335
336 • If nlen = 1024 bits (i.e., 128 bytes), and the output length of the approved hash function output block is 512 bits (i.e., 64 bytes), then the length (in bytes) of the salt (sLen) shall satisfy 0 ≤ sLen ≤ hLen – 2,
337 • Otherwise, the length (in bytes) of the salt (sLen) shall satisfy 0 ≤ sLen ≤ hLen, where hLen is the length of the hash function output block (in bytes).
338 */
339 CC_NONNULL((1, 2, 3, 5, 7, 8, 9))
340 int ccrsa_sign_pss(ccrsa_full_ctx_t key,
341 const struct ccdigest_info* hashAlgorithm, const struct ccdigest_info* MgfHashAlgorithm,
342 size_t salt_nbytes, struct ccrng_state *rng,
343 size_t digest_nbytes, const uint8_t *digest,
344 size_t *sig_nbytes, uint8_t *sig);
345
346 /*!
347 @function ccrsa_sign_pss_msg
348
349 @brief ccrsa_sign_pss_msg() generates a RSASSA-PSS signature in PKCS1-V2 format given an input message
350
351 @param key The RSA key
352 @param hashAlgorithm The hash algorithm used to generate mHash from the input message. It is also used inside the PSS encoding function.
353 @param MgfHashAlgorithm The hash algorithm for thr mask generation function
354 @param rng Random number generator to generate salt in PSS encoding
355 @param salt_nbytes Intended length of the salt
356 @param msg_nbytes Length of message.
357 @param msg The input that needs to be signed. This will be hashed using `hashAlgorithm`
358 @param sig_nbytes The length of generated signature in bytes, which equals the size of the RSA modulus.
359 @param sig The signature output
360 @return 0:ok, non-zero:error
361
362 @discussion
363 note that in RSASSA-PSS, salt length is part of the signature as specified in ASN1
364 RSASSA-PSS-params ::= SEQUENCE {
365 hashAlgorithm [0] HashAlgorithm DEFAULT sha1,
366 maskGenAlgorithm [1] MaskGenAlgorithm DEFAULT mgf1SHA1,
367 saltLength [2] INTEGER DEFAULT 20,
368 trailerField [3] TrailerField DEFAULT trailerFieldBC
369
370 • If nlen = 1024 bits (i.e., 128 bytes), and the output length of the approved hash function output block is 512 bits (i.e., 64 bytes), then the length (in bytes) of the salt (sLen) shall satisfy 0 ≤ sLen ≤ hLen – 2,
371 • Otherwise, the length (in bytes) of the salt (sLen) shall satisfy 0 ≤ sLen ≤ hLen, where hLen is the length of the hash function output block (in bytes).
372 */
373 CC_NONNULL((1, 2, 3, 5, 7, 8, 9))
374 int ccrsa_sign_pss_msg(ccrsa_full_ctx_t key,
375 const struct ccdigest_info* hashAlgorithm, const struct ccdigest_info* MgfHashAlgorithm,
376 size_t salt_nbytes, struct ccrng_state *rng,
377 size_t msg_nbytes, const uint8_t *msg,
378 size_t *sig_nbytes, uint8_t *sig);
379
380 /*!
381 @function ccrsa_verify_pss
382
383 @brief ccrsa_verify_pss() verifies RSASSA-PSS signature in PKCS1-V2 format
384
385 @param key The RSA public key
386 @param hashAlgorithm The hash algorithm used to generate mHash from the original message. It is also used inside the PSS encoding function.
387 @param MgfHashAlgorithm The hash algorithm for the mask generation function
388 @param digest_nbytes Length of message hash . Must be equal to hashAlgorithm->output_size
389 @param digest The signed message hash
390 @param sig_nbytes The length of generated signature in bytes, which equals the size of the RSA modulus.
391 @param sig The signature to verify
392 @param salt_nbytes Length of the salt as used during signature generation. Mismatch would result in the signature being considered invalid
393 @param valid Input boolean used to indicate a valid signature.
394
395 @result 0 && valid == True indicates a valid signature. If return != 0 or valid == False, the signature is invalid.
396 */
397
398 CC_NONNULL((2, 3, 5, 7, 9))
399 int ccrsa_verify_pss(ccrsa_pub_ctx_t key,
400 const struct ccdigest_info* hashAlgorithm,
401 const struct ccdigest_info* MgfHashAlgorithm,
402 size_t digest_nbytes, const uint8_t *digest,
403 size_t sig_nbytes, const uint8_t *sig,
404 size_t salt_nbytes, bool *valid)
405 cc_deprecate_with_replacement("ccrsa_verify_pss_digest", 13.0, 10.15, 13.0, 6.0, 4.0);
406
407 /*!
408 @function ccrsa_verify_pss_digest
409
410 @brief ccrsa_verify_pss_digest() verifies RSASSA-PSS signature in PKCS1-V2 format, given the digest
411
412 @param key The RSA public key
413 @param di The hash algorithm used to generate the hash of the message.
414 @param mgfdi The hash algorithm for the mask generation function
415 @param digest_nbytes Length of digest. Must be equal to di->output_size
416 @param digest The signed message hash
417 @param sig_nbytes The length of generated signature in bytes, which equals the size of the RSA modulus.
418 @param sig The signature to verify
419 @param salt_nbytes Length of the salt as used during signature generation.
420 @param fault_canary_out OPTIONAL cc_fault_canary_t (see discussion)
421
422 @result CCERR_SIGNATURE_VALID on signature success.
423 CCERR_SIGNATURE_INVALID on signature failure.
424 other on some other signature verification issue.
425
426 @discussion If the fault_canary_out argument is not NULL, the value `CCRSA_PSS_FAULT_CANARY` will be placed into fault_canary_out
427 if the salted input hash is equal to the decoded hash (which strongly implies the signature is valid). Callers can then securely compare this output buffer against CCRSA_PSS_FAULT_CANARY, using CC_FAULT_CANARY_EQUAL, as an additional check of signature validity: if the two canary values are equal, the signature is valid otherwise it is not. If the signature is valid and the canary values are NOT equal this may indicate a potentially injected computational fault.
428 */
429
430 CC_NONNULL((1, 2, 3, 5, 7))
431 int ccrsa_verify_pss_digest(ccrsa_pub_ctx_t key,
432 const struct ccdigest_info* di,
433 const struct ccdigest_info* mgfdi,
434 size_t digest_nbytes, const uint8_t *digest,
435 size_t sig_nbytes, const uint8_t *sig,
436 size_t salt_nbytes, cc_fault_canary_t fault_canary_out);
437
438 /*!
439 @function ccrsa_verify_pss_msg
440
441 @brief ccrsa_verify_pss_msg() verifies RSASSA-PSS signature in PKCS1-V2 format, given the message
442
443 @param key The RSA public key
444 @param di The hash algorithm used to generate the hash of the message.
445 @param mgfdi The hash algorithm for the mask generation function
446 @param msg_nbytes Length of message
447 @param msg The signed message
448 @param sig_nbytes The length of generated signature in bytes, which equals the size of the RSA modulus.
449 @param sig The signature to verify
450 @param salt_nbytes Length of the salt as used during signature generation.
451 @param fault_canary_out OPTIONAL cc_fault_canary_t (see discussion)
452
453 @result CCERR_SIGNATURE_VALID on signature success.
454 CCERR_SIGNATURE_INVALID on signature failure.
455 other on some other signature verification issue.
456
457 @discussion If the fault_canary_out argument is not NULL, the value `CCRSA_PSS_FAULT_CANARY` will be placed into fault_canary_out
458 if the salted input hash is equal to the decoded hash (which strongly implies the signature is valid). Callers can then securely compare this output buffer against CCRSA_PSS_FAULT_CANARY, using CC_FAULT_CANARY_EQUAL, as an additional check of signature validity: if the two canary values are equal, the signature is valid otherwise it is not. If the signature is valid and the canary values are NOT equal this may indicate a potentially injected computational fault.
459 */
460
461 CC_NONNULL((1, 2, 3, 5, 7))
462 int ccrsa_verify_pss_msg(ccrsa_pub_ctx_t key,
463 const struct ccdigest_info* di,
464 const struct ccdigest_info* mgfdi,
465 size_t msg_nbytes, const uint8_t *msg,
466 size_t sig_nbytes, const uint8_t *sig,
467 size_t salt_nbytes, cc_fault_canary_t fault_canary_out);
468
469
470 /*!
471 @function ccrsa_sign_pkcs1v15
472 @abstract RSA signature with PKCS#1 v1.5 format per PKCS#1 v2.2
473
474 @param key Full key
475 @param oid OID describing the type of digest passed in
476 @param digest_len Byte length of the digest
477 @param digest Byte array of digest_len bytes containing the digest
478 @param sig_len Pointer to the number of bytes allocated for sig.
479 Output the exact size of the signature.
480 @param sig Pointer to the allocated buffer of size *sig_len
481 for the output signature
482
483 @result CCERR_OK iff successful.
484
485 @discussion Null OID is a special case, required to support RFC 4346 where the padding
486 is based on SHA1+MD5. In general it is not recommended to use a NULL OID,
487 except when strictly required for interoperability
488
489 */
490 CC_NONNULL((1, 4, 5, 6))
491 int ccrsa_sign_pkcs1v15(ccrsa_full_ctx_t key, const uint8_t *oid,
492 size_t digest_len, const uint8_t *digest,
493 size_t *sig_len, uint8_t *sig);
494
495 /*!
496 @function ccrsa_sign_pkcs1v15_msg
497 @abstract RSA signature with PKCS#1 v1.5 format per PKCS#1 v2.2
498
499 @param key Full key
500 @param di Digest context
501 @param msg_len Byte length of the message to sign
502 @param msg Byte array of msg_len bytes containing the message. Will be hashed with di.
503 @param sig_len Pointer to the number of bytes allocated for sig.
504 Output the exact size of the signature.
505 @param sig Pointer to the allocated buffer of size *sig_len
506 for the output signature
507
508 @result CCERR_OK iff successful.
509
510 @discussion Null OID is not supported by this API.
511
512 */
513 CC_NONNULL((1, 2, 4, 5, 6))
514 int ccrsa_sign_pkcs1v15_msg(ccrsa_full_ctx_t key, const struct ccdigest_info* di,
515 size_t msg_len, const uint8_t *msg,
516 size_t *sig_len, uint8_t *sig);
517
518
519 /*!
520 @function ccrsa_verify_pkcs1v15
521 @abstract RSA signature with PKCS#1 v1.5 format per PKCS#1 v2.2
522
523 @param key Public key
524 @param oid OID describing the type of digest passed in
525 @param digest_len Byte length of the digest
526 @param digest Byte array of digest_len bytes containing the digest
527 @param sig_len Number of bytes of the signature sig.
528 @param sig Pointer to the signature buffer of sig_len
529 @param valid Output boolean, true if the signature is valid.
530
531 @result A return value of 0 and valid = True indicates a valid signature.
532 A non-zero return value or valid = False indicates an invalid signature.
533
534 @discussion Null OID is a special case, required to support RFC 4346
535 where the padding is based on SHA1+MD5. In general it is not
536 recommended to use a NULL OID, except when strictly required for
537 interoperability.
538 */
539 CC_NONNULL((1, 4, 6, 7))
540 int ccrsa_verify_pkcs1v15(ccrsa_pub_ctx_t key, const uint8_t *oid,
541 size_t digest_len, const uint8_t *digest,
542 size_t sig_len, const uint8_t *sig,
543 bool *valid);
544
545 /*!
546 @function ccrsa_verify_pkcs1v15_digest
547 @abstract RSA signature with PKCS#1 v1.5 format per PKCS#1 v2.2, given a digest
548
549 @param key Public key
550 @param oid OID describing the type of digest passed in
551 @param digest_len Byte length of the digest
552 @param digest Byte array of digest_len bytes containing the digest
553 @param sig_len Number of bytes of the signature sig.
554 @param sig Pointer to the signature buffer of sig_len
555 @param fault_canary_out OPTIONAL cc_fault_canary_t
556
557 @result CCERR_VALID_SIGNATURE if a valid signature.
558 CCERR_INVALID_SIGNATURE if an invalid signature.
559 Other if the verification procedure failed.
560
561 @discussion If the fault_canary_out argument is not NULL, the value `CCRSA_PKCS1_FAULT_CANARY` will be placed into fault_canary_out
562 if the input hash is equal to the decoded hash (which strongly implies the signature is valid). Callers can then securely compare this output buffer against CCRSA_PKCS1_FAULT_CANARY, using CC_FAULT_CANARY_EQUAL, as an additional check of signature validity: if the two canary values are equal, the signature is valid otherwise it is not. If the signature is valid and the canary values are NOT equal this may indicate a potentially injected computational fault.
563 */
564 CC_NONNULL((1, 4, 6))
565 int ccrsa_verify_pkcs1v15_digest(ccrsa_pub_ctx_t key, const uint8_t *oid,
566 size_t digest_len, const uint8_t *digest,
567 size_t sig_len, const uint8_t *sig,
568 cc_fault_canary_t fault_canary_out);
569
570 /*!
571 @function ccrsa_verify_pkcs1v15_msg
572 @abstract RSA signature with PKCS#1 v1.5 format per PKCS#1 v2.2
573
574 @param key Public key
575 @param di Hash function
576 @param msg_len Byte length of the digest
577 @param msg Byte array of digest_len bytes containing the digest
578 @param sig_len Number of bytes of the signature sig.
579 @param sig Pointer to the signature buffer of sig_len
580 @param fault_canary_out OPTIONAL cc_fault_canary_t
581
582 @result CCERR_VALID_SIGNATURE if a valid signature.
583 CCERR_INVALID_SIGNATURE if an invalid signature.
584 Other if the verification procedure failed.
585
586 @discussion Null OID is not supported by this API.
587 If the fault_canary_out argument is not NULL, the value `CCRSA_PKCS1_FAULT_CANARY` will
588 be placed into fault_canary_out if the input hash is equal to the decoded hash (which strongly
589 implies the signature is valid). Callers can then securely compare this output buffer against CCRSA_PKCS1_FAULT_CANARY, using CC_FAULT_CANARY_EQUAL, as an additional check of signature validity: if the two canary values are equal, the signature is valid otherwise it is not. If the signature is valid and the canary values are NOT equal this may indicate a potentially injected computational fault.
590 */
591 CC_NONNULL((1, 2, 4, 6))
592 int ccrsa_verify_pkcs1v15_msg(ccrsa_pub_ctx_t key, const struct ccdigest_info* di,
593 size_t msg_len, const uint8_t *msg,
594 size_t sig_len, const uint8_t *sig,
595 cc_fault_canary_t fault_canary_out);
596
597 /*!
598 @function ccder_encode_rsa_pub_size
599 @abstract Calculate size of public key export format data package.
600
601 @param key Public key
602
603 @result Returns size required for encoding.
604 */
605
606 CC_NONNULL((1))
607 size_t ccder_encode_rsa_pub_size(const ccrsa_pub_ctx_t key);
608
609 /*!
610 @function ccrsa_export_priv_pkcs1
611 @abstract Export a public key.
612
613 @param key Public key
614 @param der Beginning of output DER buffer
615 @param der_end End of output DER buffer
616 */
617
618 CC_NONNULL((1, 2, 3))
619 uint8_t *ccder_encode_rsa_pub(const ccrsa_pub_ctx_t key, uint8_t *der, uint8_t *der_end);
620
621
622 /*!
623 @function ccder_encode_rsa_priv_size
624 @abstract Calculate size of full key exported in PKCS#1 format.
625
626 @param key Full key
627
628 @result Returns size required for encoding.
629 */
630
631 CC_NONNULL((1))
632 size_t ccder_encode_rsa_priv_size(const ccrsa_full_ctx_t key);
633
634 /*!
635 @function ccder_encode_rsa_priv
636 @abstract Export a full key in PKCS#1 format.
637
638 @param key Full key
639 @param der Beginning of output DER buffer
640 @param der_end End of output DER buffer
641 */
642
643 CC_NONNULL((1, 2, 3))
644 uint8_t *ccder_encode_rsa_priv(const ccrsa_full_ctx_t key, const uint8_t *der, uint8_t *der_end);
645
646 /*!
647 @function ccder_decode_rsa_pub_n
648 @abstract Calculate "n" for a public key imported from a data package.
649 PKCS #1 format
650
651 @param der Beginning of input DER buffer
652 @param der_end End of input DER buffer
653
654 @result the "n" of the RSA key that would result from the import. This can be used
655 to declare the key itself.
656 */
657
658 CC_NONNULL((1, 2))
659 cc_size ccder_decode_rsa_pub_n(const uint8_t *der, const uint8_t *der_end);
660
661 /*!
662 @function ccder_decode_rsa_pub
663 @abstract Import a public RSA key from a package in public key format.
664 PKCS #1 format
665
666 @param key Public key (n must be set)
667 @param der Beginning of input DER buffer
668 @param der_end End of input DER buffer
669
670 @result Key is initialized using the data in the public key message.
671 */
672
673 CC_NONNULL((1, 2, 3))
674 const uint8_t *ccder_decode_rsa_pub(const ccrsa_pub_ctx_t key, const uint8_t *der, const uint8_t *der_end);
675
676 /*!
677 @function ccder_decode_rsa_pub_x509_n
678 @abstract Calculate "n" for a public key imported from a data package in x509 format
679
680 @param der Beginning of input DER buffer
681 @param der_end End of input DER buffer
682
683 @result the "n" of the RSA key that would result from the import. This can be used
684 to declare the key itself.
685 */
686
687 CC_NONNULL((1, 2))
688 cc_size ccder_decode_rsa_pub_x509_n(const uint8_t *der, const uint8_t *der_end);
689
690 /*!
691 @function ccder_decode_rsa_pub_x509
692 @abstract Import a public RSA key from a package in x509 format.
693
694 @param key Public key (n must be set)
695 @param der Beginning of input DER buffer
696 @param der_end End of input DER buffer
697
698 @result Key is initialized using the data in the public key message.
699 */
700
701 CC_NONNULL((1, 2, 3))
702 const uint8_t *ccder_decode_rsa_pub_x509(const ccrsa_pub_ctx_t key, const uint8_t *der, const uint8_t *der_end);
703
704
705 /*!
706 @function ccder_decode_rsa_priv_n
707 @abstract Calculate "n" for a private key imported from a data package.
708
709 @param der Beginning of input DER buffer
710 @param der_end End of input DER buffer
711
712 @result the "n" of the RSA key that would result from the import. This can be used
713 to declare the key itself.
714 */
715
716 CC_NONNULL((1, 2))
717 cc_size ccder_decode_rsa_priv_n(const uint8_t *der, const uint8_t *der_end);
718
719 /*!
720 @function ccder_decode_rsa_priv
721 @abstract Import a private RSA key from a package in PKCS#1 format.
722
723 @param key Full key (n must be set)
724 @param der Beginning of input DER buffer
725 @param der_end End of input DER buffer
726
727 @result Key is initialized using the data in the public key message.
728 */
729
730 CC_NONNULL((1, 2, 3))
731 const uint8_t *ccder_decode_rsa_priv(const ccrsa_full_ctx_t key, const uint8_t *der, const uint8_t *der_end);
732
733 /*!
734 @function ccrsa_export_pub_size
735 @abstract Calculate size of public key exported data package.
736
737 @param key Public key
738
739 @result Returns size required for encoding.
740 */
741
742 CC_INLINE CC_NONNULL((1))
ccrsa_export_pub_size(const ccrsa_pub_ctx_t key)743 size_t ccrsa_export_pub_size(const ccrsa_pub_ctx_t key) {
744 return ccder_encode_rsa_pub_size(key);
745 }
746
747 /*!
748 @function ccrsa_export_pub
749 @abstract Export a public key in public key format.
750
751 @param key Public key
752 @param out_len Allocated size
753 @param out Output buffer
754 */
755
756 CC_NONNULL((1, 3))
757 int ccrsa_export_pub(const ccrsa_pub_ctx_t key, size_t out_len, uint8_t *out);
758 /*!
759 @function ccrsa_import_pub_n
760 @abstract Calculate "n" for a public key imported from a data package.
761
762 @param inlen Length of public key package data
763 @param der pointer to public key package data
764
765 @result the "n" of the RSA key that would result from the import. This can be used
766 to declare the key itself.
767 */
768
769 CC_INLINE CC_NONNULL((2))
ccrsa_import_pub_n(size_t inlen,const uint8_t * der)770 cc_size ccrsa_import_pub_n(size_t inlen, const uint8_t *der) {
771 cc_size size = ccder_decode_rsa_pub_x509_n(der, der + inlen);
772 if(size == 0) {
773 size = ccder_decode_rsa_pub_n(der, der + inlen);
774 }
775 return size;
776 }
777
778 /*!
779 @function ccrsa_import_pub
780 @abstract Import a public RSA key from a package in public key format.
781
782 @param key Public key (n must be set)
783 @param inlen Length of public key package data
784 @param der pointer to public key package data
785
786 @result Key is initialized using the data in the public key message.
787 */
788
789 CC_NONNULL((1, 3))
790 int ccrsa_import_pub(ccrsa_pub_ctx_t key, size_t inlen, const uint8_t *der);
791
792 /*!
793 @function ccrsa_export_priv_size
794 @abstract Calculate size of full key exported in PKCS#1 format.
795
796 @param key Full key
797
798 @result Returns size required for encoding.
799 */
800
801 CC_INLINE CC_NONNULL((1))
ccrsa_export_priv_size(const ccrsa_full_ctx_t key)802 size_t ccrsa_export_priv_size(const ccrsa_full_ctx_t key) {
803 return ccder_encode_rsa_priv_size(key);
804 }
805
806 /*!
807 @function ccrsa_export_priv
808 @abstract Export a full key in PKCS#1 format.
809
810 @param key Full key
811 @param out_len Allocated size
812 @param out Output buffer
813 */
814
815 CC_INLINE CC_NONNULL((1, 3))
ccrsa_export_priv(const ccrsa_full_ctx_t key,size_t out_len,uint8_t * out)816 int ccrsa_export_priv(const ccrsa_full_ctx_t key, size_t out_len, uint8_t *out) {
817 return (ccder_encode_rsa_priv(key, out, out+out_len) != out);
818 }
819
820 /*!
821 @function ccrsa_import_priv_n
822 @abstract Calculate size of full key exported in PKCS#1 format.
823
824 @param inlen Length of PKCS#1 package data
825 @param der pointer to PKCS#1 package data
826
827 @result the "n" of the RSA key that would result from the import. This can be used
828 to declare the key itself.
829 */
830
831 CC_INLINE CC_NONNULL((2))
ccrsa_import_priv_n(size_t inlen,const uint8_t * der)832 cc_size ccrsa_import_priv_n(size_t inlen, const uint8_t *der) {
833 return ccder_decode_rsa_priv_n(der, der + inlen);
834 }
835
836 /*!
837 @function ccrsa_import_priv
838 @abstract Import a full RSA key from a package in PKCS#1 format.
839
840 @param key Full key (n must be set)
841 @param inlen Length of PKCS#1 package data
842 @param der pointer to PKCS#1 package data
843
844 @result Key is initialized using the data in the PKCS#1 message.
845 */
846
847 CC_INLINE CC_NONNULL((1, 3))
ccrsa_import_priv(ccrsa_full_ctx_t key,size_t inlen,const uint8_t * der)848 int ccrsa_import_priv(ccrsa_full_ctx_t key, size_t inlen, const uint8_t *der) {
849 return (ccder_decode_rsa_priv(key, der, der+inlen) == NULL);
850 }
851
852 /*!
853 @function ccrsa_get_pubkey_components
854 @abstract Copy each component of the public key to the given buffers
855
856 @param pubkey Public key
857 @param modulus Buffer to the output buffer for the modulus
858 @param modulusLength Pointer to the byte size allocated for the modulus, updated with actual output size
859 @param exponent Buffer to the output buffer for the exponent
860 @param exponentLength Pointer to the byte size allocated for the exponent, updated with actual output size
861
862 @return 0 is success, not 0 in case of error
863
864 @discussion if either allocated buffer length is insufficient, the function returns an error
865 */
866 CC_NONNULL((1, 2))
867 int ccrsa_get_pubkey_components(const ccrsa_pub_ctx_t pubkey, uint8_t *modulus, size_t *modulusLength, uint8_t *exponent, size_t *exponentLength);
868
869 /*!
870 @function ccrsa_get_fullkey_components
871 @abstract Copy each component of the public key to the given buffers
872
873 @param key Full key
874 @param modulus Buffer to the output buffer for the modulus
875 @param modulusLength Pointer to the byte size allocated for the modulus, updated with actual output size
876 @param exponent Buffer to the output buffer for the exponent
877 @param exponentLength Pointer to the byte size allocated for the exponent, updated with actual output size
878 @param p Buffer to the output buffer for the first prime factor of the modulus
879 @param pLength Pointer to the byte size allocated for the prime factor, updated with actual output size
880 @param q Buffer to the output buffer for the second prime factor of the modulus
881 @param qLength Pointer to the byte size allocated for the prime factor, updated with actual output size
882
883 @return 0 is success, not 0 in case of error
884
885 @discussion if either allocated buffer length is insufficient, the function returns an error
886 */
887 CC_NONNULL((1, 2))
888 int ccrsa_get_fullkey_components(const ccrsa_full_ctx_t key, uint8_t *modulus, size_t *modulusLength, uint8_t *exponent, size_t *exponentLength,
889 uint8_t *p, size_t *pLength, uint8_t *q, size_t *qLength);
890
891
892 /*!
893 @function ccrsa_dump_public_key
894 @abstract Print a rsa public key in the console (printf)
895
896 @param key Public key
897 */
898 void ccrsa_dump_public_key(ccrsa_pub_ctx_t key);
899
900 /*!
901 @function ccrsa_dump_full_key
902 @abstract Print a rsa private key in the console (printf)
903
904 @param key Public key
905 */
906 void ccrsa_dump_full_key(ccrsa_full_ctx_t key);
907
908 #endif /* _CORECRYPTO_CCRSA_H_ */
909