1 /* Copyright (c) 1997,2003,2005-2006,2008 Apple Inc.
3 * cspwrap.h - wrappers to simplify access to CDSA
7 * 3 May 2000 Doug Mitchell
9 * 12 Aug 1997 Doug Mitchell at Apple
15 #include <Security/cssm.h>
22 * Bug/feature workaround flags
26 * Doing a WrapKey requires Access Creds, which should be
27 * optional. Looks like this is not a bug.
29 #define WRAP_KEY_REQUIRES_CREDS 1
32 * encrypt/decrypt - cook up a context handle
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.
39 const CSSM_KEY
*key1
, // for CSSM_ALGID_FEED only - must be the
41 const CSSM_DATA
*iv
, // optional
42 uint32 effectiveKeySizeInBits
, // 0 means skip this attribute
43 uint32 rounds
); // ditto
48 * Specifying a keySize of CSP_KEY_SIZE_DEFAULT results in using the default
49 * key size for the specified algorithm.
51 #define CSP_KEY_SIZE_DEFAULT 0
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)
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
78 * Generate key pair of arbitrary algorithm.
80 extern CSSM_RETURN
cspGenKeyPair(CSSM_CSP_HANDLE cspHand
,
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
99 * Generate FEE key pair with optional primeType, curveType, and seed (password) data.
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.
120 * Generate DSA key pair with optional generateAlgParams.
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.
137 CSSM_DATA_PTR paramData
); // optional
140 * Create a symmetric key.
142 extern CSSM_KEY_PTR
cspGenSymKey(CSSM_CSP_HANDLE cspHand
,
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
151 * Derive symmetric key using PBE.
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
,
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
167 * Encrypt/Decrypt - these work for both symmetric and asymmetric algorithms.
169 CSSM_RETURN
cspEncrypt(CSSM_CSP_HANDLE cspHand
,
170 uint32 algorithm
, // CSSM_ALGID_FEED, etc.
171 uint32 mode
, // CSSM_ALGMODE_CBC, etc. - only for
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
);
183 CSSM_RETURN
cspStagedEncrypt(CSSM_CSP_HANDLE cspHand
,
184 uint32 algorithm
, // CSSM_ALGID_FEED, etc.
185 uint32 mode
, // CSSM_ALGMODE_CBC, etc. - only for
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
198 CSSM_RETURN
cspDecrypt(CSSM_CSP_HANDLE cspHand
,
199 uint32 algorithm
, // CSSM_ALGID_FEED, etc.
200 uint32 mode
, // CSSM_ALGMODE_CBC, etc. - only for
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
);
212 CSSM_RETURN
cspStagedDecrypt(CSSM_CSP_HANDLE cspHand
,
213 uint32 algorithm
, // CSSM_ALGID_FEED, etc.
214 uint32 mode
, // CSSM_ALGMODE_CBC, etc. - only for
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
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
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
271 CSSM_BOOL multiUpdates
, // false:single update, true:multi updates
272 CSSM_DATA_PTR mac
); // RETURNED
273 CSSM_RETURN
cspMacVerify(CSSM_CSP_HANDLE cspHand
,
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
,
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
);
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
,
305 * Perform FEE Key exchange via CSSM_DeriveKey.
307 CSSM_RETURN
cspFeeKeyExchange(CSSM_CSP_HANDLE cspHand
,
308 CSSM_KEY_PTR privKey
,
310 CSSM_KEY_PTR derivedKey
, // mallocd by caller
312 /* remaining fields apply to derivedKey */
314 const char *keyLabel
,
315 unsigned keyLabelLen
,
316 uint32 keyUsage
, // CSSM_KEYUSE_ENCRYPT, etc.
317 uint32 keySizeInBits
);
320 * wrap/unwrap key functions.
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
);
344 /* generate a random and reasonable key size in bits for specified CSSM algorithm */
351 #define MAX_KEY_SIZE_RC245_BYTES 64 /* max bytes, RC2, RC4, RC5 */
353 uint32
randKeySizeBits(uint32 alg
, opType op
);
354 uint32
cspDefaultKeySize(uint32 alg
);
357 * Generate random key size, primeType, curveType for FEE key for specified op.
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
366 * Obtain strings for primeType and curveType.
368 const char *primeTypeStr(uint32 primeType
);
369 const char *curveTypeStr(uint32 curveType
);
372 * Given any key in either blob or reference format,
373 * obtain the associated SHA-1 hash.
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 */
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
387 * Convert ref key to raw key with specified format.
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
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
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.
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
415 * Add a DL/DB handle to a crypto context.
417 CSSM_RETURN
cspAddDlDbToContext(
418 CSSM_CC_HANDLE ccHand
,
419 CSSM_DL_HANDLE dlHand
,
420 CSSM_DB_HANDLE dbHand
);
423 * Look up a key by label and type.
432 CSSM_KEY_PTR
cspLookUpKeyByLabel(
433 CSSM_DL_HANDLE dlHand
,
434 CSSM_DB_HANDLE dbHand
,
435 const CSSM_DATA
*labelData
,
439 * Delete and free a key
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
,
449 #define CSSM_ALGID_FEECFILE (CSSM_ALGID_VENDOR_DEFINED + 102)
454 #endif /* _CSPWRAP_H_ */