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