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
18extern "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 */
34CSSM_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 */
80extern 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 */
101extern 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 */
122extern 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 */
142extern 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 */
153CSSM_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 */
169CSSM_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
183CSSM_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
198CSSM_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
212CSSM_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 */
230CSSM_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
235CSSM_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
241CSSM_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
248CSSM_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 */
260CSSM_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
265CSSM_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
273CSSM_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);
279CSSM_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 */
290CSSM_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);
295CSSM_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);
301CSSM_RETURN	cspFreeKey(CSSM_CSP_HANDLE cspHand,
302	CSSM_KEY_PTR key);
303
304/*
305 * Perform FEE Key exchange via CSSM_DeriveKey.
306 */
307CSSM_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 */
322CSSM_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
332CSSM_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 */
345typedef 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
353uint32 randKeySizeBits(uint32 alg, opType op);
354uint32 cspDefaultKeySize(uint32 alg);
355
356/*
357 * Generate random key size, primeType, curveType for FEE key for specified op.
358 */
359void 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 */
368const char *primeTypeStr(uint32 primeType);
369const char *curveTypeStr(uint32 curveType);
370
371/*
372 * Given any key in either blob or reference format,
373 * obtain the associated SHA-1 hash.
374 */
375CSSM_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 */
381CSSM_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 */
389CSSM_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 */
396CSSM_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 */
406CSSM_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 */
417CSSM_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 */
425typedef enum {
426	CKT_Public = 1,
427	CKT_Private = 2,
428	CKT_Session = 3
429	/* any others? */
430} CT_KeyType;
431
432CSSM_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 */
441CSSM_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_ */
455