]> git.saurik.com Git - apple/security.git/blob - SecurityTests/cspxutils/utilLib/cspwrap.h
Security-57740.31.2.tar.gz
[apple/security.git] / SecurityTests / cspxutils / utilLib / cspwrap.h
1 /* Copyright (c) 1997,2003,2005-2006,2008 Apple Inc.
2 *
3 * cspwrap.h - wrappers to simplify access to CDSA
4 *
5 * Revision History
6 * ----------------
7 * 3 May 2000 Doug Mitchell
8 * Ported to X/CDSA2.
9 * 12 Aug 1997 Doug Mitchell at Apple
10 * Created.
11 */
12
13 #ifndef _CSPWRAP_H_
14 #define _CSPWRAP_H_
15 #include <Security/cssm.h>
16
17 #ifdef __cplusplus
18 extern "C" {
19 #endif
20
21 /*
22 * Bug/feature workaround flags
23 */
24
25 /*
26 * Doing a WrapKey requires Access Creds, which should be
27 * optional. Looks like this is not a bug.
28 */
29 #define WRAP_KEY_REQUIRES_CREDS 1
30
31 /*
32 * encrypt/decrypt - cook up a context handle
33 */
34 CSSM_CC_HANDLE genCryptHandle(CSSM_CSP_HANDLE cspHand,
35 uint32 algorithm, // CSSM_ALGID_FEED, etc.
36 uint32 mode, // CSSM_ALGMODE_CBC, etc. - only for symmetric algs
37 CSSM_PADDING padding, // CSSM_PADDING_PKCS1, etc.
38 const CSSM_KEY *key0,
39 const CSSM_KEY *key1, // for CSSM_ALGID_FEED only - must be the
40 // public key
41 const CSSM_DATA *iv, // optional
42 uint32 effectiveKeySizeInBits, // 0 means skip this attribute
43 uint32 rounds); // ditto
44 /*
45 * Key generation
46 */
47 /*
48 * Specifying a keySize of CSP_KEY_SIZE_DEFAULT results in using the default
49 * key size for the specified algorithm.
50 */
51 #define CSP_KEY_SIZE_DEFAULT 0
52
53 /* symmetric key sizes in bits */
54 #define CSP_ASC_KEY_SIZE_DEFAULT (16 * 8)
55 #define CSP_DES_KEY_SIZE_DEFAULT (8 * 8)
56 #define CSP_DES3_KEY_SIZE_DEFAULT (24 * 8)
57 #define CSP_RC2_KEY_SIZE_DEFAULT (10 * 8)
58 #define CSP_RC4_KEY_SIZE_DEFAULT (10 * 8)
59 #define CSP_RC5_KEY_SIZE_DEFAULT (10 * 8)
60 #define CSP_AES_KEY_SIZE_DEFAULT 128
61 #define CSP_BFISH_KEY_SIZE_DEFAULT 128
62 #define CSP_CAST_KEY_SIZE_DEFAULT 128
63 #define CSP_IDEA_KEY_SIZE_DEFAULT 128 /* fixed */
64 #define CSP_HMAC_SHA_KEY_SIZE_DEFAULT (20 * 8)
65 #define CSP_HMAC_MD5_KEY_SIZE_DEFAULT (16 * 8)
66 #define CSP_NULL_CRYPT_KEY_SIZE_DEF (16 * 8)
67
68 /* asymmetric key sizes in bits */
69 /* note: we now use AI_RSAStrongKeyGen for RSA key pair
70 * generate; this requires at least 512 bits and also that
71 * the key size be a multiple of 16. */
72 #define CSP_FEE_KEY_SIZE_DEFAULT 128
73 #define CSP_ECDSA_KEY_SIZE_DEFAULT 256
74 #define CSP_RSA_KEY_SIZE_DEFAULT 1024 /* min for SHA512/RSA */
75 #define CSP_DSA_KEY_SIZE_DEFAULT 512
76
77 /*
78 * Generate key pair of arbitrary algorithm.
79 */
80 extern CSSM_RETURN cspGenKeyPair(CSSM_CSP_HANDLE cspHand,
81 uint32 algorithm,
82 const char *keyLabel,
83 unsigned keyLabelLen,
84 uint32 keySizeInBits,
85 CSSM_KEY_PTR pubKey, // mallocd by caller
86 CSSM_BOOL pubIsRef, // true - reference key, false - data
87 uint32 pubKeyUsage, // CSSM_KEYUSE_ENCRYPT, etc.
88 CSSM_KEYBLOB_FORMAT pubFormat, // Optional. Specify 0 or CSSM_KEYBLOB_RAW_FORMAT_NONE
89 // to get the default format.
90 CSSM_KEY_PTR privKey, // mallocd by caller - always returned as ref
91 CSSM_BOOL privIsRef, // true - reference key, false - data
92 uint32 privKeyUsage, // CSSM_KEYUSE_DECRYPT, etc.
93 CSSM_KEYBLOB_FORMAT privFormat, // optional 0 ==> default
94 CSSM_BOOL genSeed); // FEE only. True: we generate seed and CSP
95 // will hash it. False: CSP generates random
96 // seed.
97
98 /*
99 * Generate FEE key pair with optional primeType, curveType, and seed (password) data.
100 */
101 extern CSSM_RETURN cspGenFEEKeyPair(CSSM_CSP_HANDLE cspHand,
102 const char *keyLabel,
103 unsigned keyLabelLen,
104 uint32 keySize, // in bits
105 uint32 primeType, // CSSM_FEE_PRIME_TYPE_MERSENNE, etc.
106 uint32 curveType, // CSSM_FEE_CURVE_TYPE_MONTGOMERY, etc.
107 CSSM_KEY_PTR pubKey, // mallocd by caller
108 CSSM_BOOL pubIsRef, // true - reference key, false - data
109 uint32 pubKeyUsage, // CSSM_KEYUSE_ENCRYPT, etc.
110 CSSM_KEYBLOB_FORMAT pubFormat, // Optional. Specify 0 or CSSM_KEYBLOB_RAW_FORMAT_NONE
111 // to get the default format.
112 CSSM_KEY_PTR privKey, // mallocd by caller
113 CSSM_BOOL privIsRef, // true - reference key, false - data
114 uint32 privKeyUsage, // CSSM_KEYUSE_DECRYPT, etc.
115 CSSM_KEYBLOB_FORMAT privFormat, // optional 0 ==> default
116 const CSSM_DATA *seedData); // Present: CSP will hash this for private data.
117 // NULL: CSP generates random seed.
118
119 /*
120 * Generate DSA key pair with optional generateAlgParams.
121 */
122 extern CSSM_RETURN cspGenDSAKeyPair(CSSM_CSP_HANDLE cspHand,
123 const char *keyLabel,
124 unsigned keyLabelLen,
125 uint32 keySize, // in bits
126 CSSM_KEY_PTR pubKey, // mallocd by caller
127 CSSM_BOOL pubIsRef, // true - reference key, false - data
128 uint32 pubKeyUsage, // CSSM_KEYUSE_ENCRYPT, etc.
129 CSSM_KEYBLOB_FORMAT pubFormat, // Optional. Specify 0 or CSSM_KEYBLOB_RAW_FORMAT_NONE
130 // to get the default format.
131 CSSM_KEY_PTR privKey, // mallocd by caller
132 CSSM_BOOL privIsRef, // true - reference key, false - data
133 uint32 privKeyUsage, // CSSM_KEYUSE_DECRYPT, etc.
134 CSSM_KEYBLOB_FORMAT privFormat, // Optional. Specify 0 or CSSM_KEYBLOB_RAW_FORMAT_NONE
135 // to get the default format.
136 CSSM_BOOL genParams,
137 CSSM_DATA_PTR paramData); // optional
138
139 /*
140 * Create a symmetric key.
141 */
142 extern CSSM_KEY_PTR cspGenSymKey(CSSM_CSP_HANDLE cspHand,
143 uint32 alg,
144 const char *keyLabel,
145 unsigned keyLabelLen,
146 uint32 keyUsage, // CSSM_KEYUSE_ENCRYPT, etc.
147 uint32 keySizeInBits,
148 CSSM_BOOL refKey); // true - reference key, false - data
149
150 /*
151 * Derive symmetric key using PBE.
152 */
153 CSSM_KEY_PTR cspDeriveKey(CSSM_CSP_HANDLE cspHand,
154 uint32 deriveAlg, // CSSM_ALGID_MD5_PBE, etc.
155 uint32 keyAlg, // CSSM_ALGID_RC5, etc.
156 const char *keyLabel,
157 unsigned keyLabelLen,
158 uint32 keyUsage, // CSSM_KEYUSE_ENCRYPT, etc.
159 uint32 keySizeInBits,
160 CSSM_BOOL isRefKey,
161 CSSM_DATA_PTR password, // in PKCS-5 lingo
162 CSSM_DATA_PTR salt, // ditto
163 uint32 iterationCnt, // ditto
164 CSSM_DATA_PTR initVector); // mallocd & RETURNED
165
166 /*
167 * Encrypt/Decrypt - these work for both symmetric and asymmetric algorithms.
168 */
169 CSSM_RETURN cspEncrypt(CSSM_CSP_HANDLE cspHand,
170 uint32 algorithm, // CSSM_ALGID_FEED, etc.
171 uint32 mode, // CSSM_ALGMODE_CBC, etc. - only for
172 // symmetric algs
173 CSSM_PADDING padding, // CSSM_PADDING_PKCS1, etc.
174 const CSSM_KEY *key, // public or session key
175 const CSSM_KEY *pubKey, // for CSSM_ALGID_{FEED,FEECFILE} only
176 uint32 effectiveKeySizeInBits, // 0 means skip this attribute
177 uint32 rounds, // ditto
178 const CSSM_DATA *iv, // init vector, optional
179 const CSSM_DATA *ptext,
180 CSSM_DATA_PTR ctext, // RETURNED
181 CSSM_BOOL mallocCtext);
182
183 CSSM_RETURN cspStagedEncrypt(CSSM_CSP_HANDLE cspHand,
184 uint32 algorithm, // CSSM_ALGID_FEED, etc.
185 uint32 mode, // CSSM_ALGMODE_CBC, etc. - only for
186 // symmetric algs
187 CSSM_PADDING padding, // CSSM_PADDING_PKCS1, etc.
188 const CSSM_KEY *key, // public or session key
189 const CSSM_KEY *pubKey, // for CSSM_ALGID_{FEED,FEECFILE} only
190 uint32 effectiveKeySizeInBits, // 0 means skip this attribute
191 uint32 cipherBlockSize, // ditto, block size in bytes
192 uint32 rounds, // ditto
193 const CSSM_DATA *iv, // init vector, optional
194 const CSSM_DATA *ptext,
195 CSSM_DATA_PTR ctext, // RETURNED, we malloc
196 CSSM_BOOL multiUpdates); // false:single update, true:multi updates
197
198 CSSM_RETURN cspDecrypt(CSSM_CSP_HANDLE cspHand,
199 uint32 algorithm, // CSSM_ALGID_FEED, etc.
200 uint32 mode, // CSSM_ALGMODE_CBC, etc. - only for
201 // symmetric algs
202 CSSM_PADDING padding, // CSSM_PADDING_PKCS1, etc.
203 const CSSM_KEY *key, // private or session key
204 const CSSM_KEY *pubKey, // for CSSM_ALGID_{FEED,FEECFILE} only
205 uint32 effectiveKeySizeInBits, // 0 means skip this attribute
206 uint32 rounds, // ditto
207 const CSSM_DATA *iv, // init vector, optional
208 const CSSM_DATA *ctext,
209 CSSM_DATA_PTR ptext, // RETURNED
210 CSSM_BOOL mallocPtext);
211
212 CSSM_RETURN cspStagedDecrypt(CSSM_CSP_HANDLE cspHand,
213 uint32 algorithm, // CSSM_ALGID_FEED, etc.
214 uint32 mode, // CSSM_ALGMODE_CBC, etc. - only for
215 // symmetric algs
216 CSSM_PADDING padding, // CSSM_PADDING_PKCS1, etc.
217 const CSSM_KEY *key, // private or session key
218 const CSSM_KEY *pubKey, // for CSSM_ALGID_{FEED,FEECFILE} only
219 uint32 effectiveKeySizeInBits, // 0 means skip this attribute
220 uint32 cipherBlockSize, // ditto, block size in bytes
221 uint32 rounds, // ditto
222 const CSSM_DATA *iv, // init vector, optional
223 const CSSM_DATA *ctext,
224 CSSM_DATA_PTR ptext, // RETURNED, we malloc
225 CSSM_BOOL multiUpdates); // false:single update, true:multi updates
226
227 /*
228 * Signature routines
229 */
230 CSSM_RETURN cspSign(CSSM_CSP_HANDLE cspHand,
231 uint32 algorithm, // CSSM_ALGID_FEE_MD5, etc.
232 CSSM_KEY_PTR key, // private key
233 const CSSM_DATA *text,
234 CSSM_DATA_PTR sig); // RETURNED
235 CSSM_RETURN cspStagedSign(CSSM_CSP_HANDLE cspHand,
236 uint32 algorithm, // CSSM_ALGID_FEE_MD5, etc.
237 CSSM_KEY_PTR key, // private key
238 const CSSM_DATA *text,
239 CSSM_BOOL multiUpdates, // false:single update, true:multi updates
240 CSSM_DATA_PTR sig); // RETURNED
241 CSSM_RETURN cspSigVerify(CSSM_CSP_HANDLE cspHand,
242 uint32 algorithm, // CSSM_ALGID_FEE_MD5, etc.
243 CSSM_KEY_PTR key, // public key
244 const CSSM_DATA *text,
245 const CSSM_DATA *sig,
246 CSSM_RETURN expectResult); // expected result is verify failure
247 // CSSM_OK - expect success
248 CSSM_RETURN cspStagedSigVerify(CSSM_CSP_HANDLE cspHand,
249 uint32 algorithm, // CSSM_ALGID_FEE_MD5, etc.
250 CSSM_KEY_PTR key, // private key
251 const CSSM_DATA *text,
252 const CSSM_DATA *sig,
253 CSSM_BOOL multiUpdates, // false:single update, true:multi updates
254 CSSM_RETURN expectResult); // expected result is verify failure
255 // CSSM_OK - expect success
256
257 /*
258 * MAC routines
259 */
260 CSSM_RETURN cspGenMac(CSSM_CSP_HANDLE cspHand,
261 uint32 algorithm, // CSSM_ALGID_DES, etc.
262 CSSM_KEY_PTR key, // session key
263 const CSSM_DATA *text,
264 CSSM_DATA_PTR mac); // RETURNED
265 CSSM_RETURN cspStagedGenMac(CSSM_CSP_HANDLE cspHand,
266 uint32 algorithm, // CSSM_ALGID_FEE_MD5, etc.
267 CSSM_KEY_PTR key, // private key
268 const CSSM_DATA *text,
269 CSSM_BOOL mallocMac, // if true and digest->Length = 0, we'll
270 // malloc
271 CSSM_BOOL multiUpdates, // false:single update, true:multi updates
272 CSSM_DATA_PTR mac); // RETURNED
273 CSSM_RETURN cspMacVerify(CSSM_CSP_HANDLE cspHand,
274 uint32 algorithm,
275 CSSM_KEY_PTR key, // public key
276 const CSSM_DATA *text,
277 const CSSM_DATA_PTR mac,
278 CSSM_RETURN expectResult);
279 CSSM_RETURN cspStagedMacVerify(CSSM_CSP_HANDLE cspHand,
280 uint32 algorithm,
281 CSSM_KEY_PTR key, // private key
282 const CSSM_DATA *text,
283 const CSSM_DATA_PTR mac,
284 CSSM_BOOL multiUpdates, // false:single update, true:multi updates
285 CSSM_RETURN expectResult);
286
287 /*
288 * Digest functions
289 */
290 CSSM_RETURN cspDigest(CSSM_CSP_HANDLE cspHand,
291 uint32 algorithm, // CSSM_ALGID_MD5, etc.
292 CSSM_BOOL mallocDigest, // if true and digest->Length = 0, we'll malloc
293 const CSSM_DATA *text,
294 CSSM_DATA_PTR digest);
295 CSSM_RETURN cspStagedDigest(CSSM_CSP_HANDLE cspHand,
296 uint32 algorithm, // CSSM_ALGID_MD5, etc.
297 CSSM_BOOL mallocDigest, // if true and digest->Length = 0, we'll malloc
298 CSSM_BOOL multiUpdates, // false:single update, true:multi updates
299 const CSSM_DATA *text,
300 CSSM_DATA_PTR digest);
301 CSSM_RETURN cspFreeKey(CSSM_CSP_HANDLE cspHand,
302 CSSM_KEY_PTR key);
303
304 /*
305 * Perform FEE Key exchange via CSSM_DeriveKey.
306 */
307 CSSM_RETURN cspFeeKeyExchange(CSSM_CSP_HANDLE cspHand,
308 CSSM_KEY_PTR privKey,
309 CSSM_KEY_PTR pubKey,
310 CSSM_KEY_PTR derivedKey, // mallocd by caller
311
312 /* remaining fields apply to derivedKey */
313 uint32 keyAlg,
314 const char *keyLabel,
315 unsigned keyLabelLen,
316 uint32 keyUsage, // CSSM_KEYUSE_ENCRYPT, etc.
317 uint32 keySizeInBits);
318
319 /*
320 * wrap/unwrap key functions.
321 */
322 CSSM_RETURN cspWrapKey(CSSM_CSP_HANDLE cspHand,
323 const CSSM_KEY *unwrappedKey,
324 const CSSM_KEY *wrappingKey,
325 CSSM_ALGORITHMS wrapAlg,
326 CSSM_ENCRYPT_MODE wrapMode,
327 CSSM_KEYBLOB_FORMAT wrapFormat, // NONE, PKCS7, PKCS8
328 CSSM_PADDING wrapPad,
329 CSSM_DATA_PTR initVector, // for some wrapping algs
330 CSSM_DATA_PTR descrData, // optional
331 CSSM_KEY_PTR wrappedKey); // RETURNED
332 CSSM_RETURN cspUnwrapKey(CSSM_CSP_HANDLE cspHand,
333 const CSSM_KEY *wrappedKey,
334 const CSSM_KEY *unwrappingKey,
335 CSSM_ALGORITHMS unwrapAlg,
336 CSSM_ENCRYPT_MODE unwrapMode,
337 CSSM_PADDING unwrapPad,
338 CSSM_DATA_PTR initVector, // for some wrapping algs
339 CSSM_KEY_PTR unwrappedKey, // RETURNED
340 CSSM_DATA_PTR descrData, // required
341 const char *keyLabel,
342 unsigned keyLabelLen);
343
344 /* generate a random and reasonable key size in bits for specified CSSM algorithm */
345 typedef enum {
346 OT_Sign,
347 OT_Encrypt,
348 OT_KeyExch
349 } opType;
350
351 #define MAX_KEY_SIZE_RC245_BYTES 64 /* max bytes, RC2, RC4, RC5 */
352
353 uint32 randKeySizeBits(uint32 alg, opType op);
354 uint32 cspDefaultKeySize(uint32 alg);
355
356 /*
357 * Generate random key size, primeType, curveType for FEE key for specified op.
358 */
359 void randFeeKeyParams(
360 CSSM_ALGORITHMS alg, // ALGID_FEED, CSSM_ALGID_FEE_MD5, etc.
361 uint32 *keySizeInBits, // RETURNED
362 uint32 *primeType, // CSSM_FEE_PRIME_TYPE_xxx, RETURNED
363 uint32 *curveType); // CSSM_FEE_CURVE_TYPE_xxx, RETURNED
364
365 /*
366 * Obtain strings for primeType and curveType.
367 */
368 const char *primeTypeStr(uint32 primeType);
369 const char *curveTypeStr(uint32 curveType);
370
371 /*
372 * Given any key in either blob or reference format,
373 * obtain the associated SHA-1 hash.
374 */
375 CSSM_RETURN cspKeyHash(
376 CSSM_CSP_HANDLE cspHand,
377 const CSSM_KEY_PTR key, /* public key */
378 CSSM_DATA_PTR *hashData); /* hash mallocd and RETURNED here */
379
380 /* wrap ref key --> raw key */
381 CSSM_RETURN cspRefKeyToRaw(
382 CSSM_CSP_HANDLE cspHand,
383 const CSSM_KEY *refKey,
384 CSSM_KEY_PTR rawKey); // init'd and RETURNED
385
386 /*
387 * Convert ref key to raw key with specified format.
388 */
389 CSSM_RETURN cspRefKeyToRawWithFormat(
390 CSSM_CSP_HANDLE cspHand,
391 const CSSM_KEY *refKey,
392 CSSM_KEYBLOB_FORMAT format,
393 CSSM_KEY_PTR rawKey); // init'd and RETURNED
394
395 /* unwrap raw key --> ref */
396 CSSM_RETURN cspRawKeyToRef(
397 CSSM_CSP_HANDLE cspHand,
398 const CSSM_KEY *rawKey,
399 CSSM_KEY_PTR refKey); // init'd and RETURNED
400
401 /*
402 * Cook up a symmetric key with specified key bits and other
403 * params. Currently the CSPDL can only deal with reference keys except when
404 * doing wrap/unwrap, so we manually cook up a raw key, then we null-unwrap it.
405 */
406 CSSM_RETURN cspGenSymKeyWithBits(
407 CSSM_CSP_HANDLE cspHand,
408 CSSM_ALGORITHMS keyAlg,
409 CSSM_KEYUSE keyUsage,
410 const CSSM_DATA *keyBits,
411 unsigned keySizeInBytes,
412 CSSM_KEY_PTR refKey); // init'd and RETURNED
413
414 /*
415 * Add a DL/DB handle to a crypto context.
416 */
417 CSSM_RETURN cspAddDlDbToContext(
418 CSSM_CC_HANDLE ccHand,
419 CSSM_DL_HANDLE dlHand,
420 CSSM_DB_HANDLE dbHand);
421
422 /*
423 * Look up a key by label and type.
424 */
425 typedef enum {
426 CKT_Public = 1,
427 CKT_Private = 2,
428 CKT_Session = 3
429 /* any others? */
430 } CT_KeyType;
431
432 CSSM_KEY_PTR cspLookUpKeyByLabel(
433 CSSM_DL_HANDLE dlHand,
434 CSSM_DB_HANDLE dbHand,
435 const CSSM_DATA *labelData,
436 CT_KeyType keyType);
437
438 /*
439 * Delete and free a key
440 */
441 CSSM_RETURN cspDeleteKey(
442 CSSM_CSP_HANDLE cspHand, // for free
443 CSSM_DL_HANDLE dlHand, // for delete
444 CSSM_DB_HANDLE dbHand, // ditto
445 const CSSM_DATA *labelData,
446 CSSM_KEY_PTR key);
447
448 // temp hack
449 #define CSSM_ALGID_FEECFILE (CSSM_ALGID_VENDOR_DEFINED + 102)
450
451 #ifdef __cplusplus
452 }
453 #endif
454 #endif /* _CSPWRAP_H_ */