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