1/* 2 * Copyright (c) 2002-2014 Apple Inc. All Rights Reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. Please obtain a copy of the License at 10 * http://www.opensource.apple.com/apsl/ and read it before using this 11 * file. 12 * 13 * The Original Code and all software distributed under the License are 14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18 * Please see the License for the specific language governing rights and 19 * limitations under the License. 20 * 21 * @APPLE_LICENSE_HEADER_END@ 22 */ 23 24/*! 25 @header SecKey 26 The functions provided in SecKey.h implement and manage a particular 27 type of keychain item that represents a key. A key can be stored in a 28 keychain, but a key can also be a transient object. 29 30 You can use a key as a keychain item in most functions. 31*/ 32 33#ifndef _SECURITY_SECKEY_H_ 34#define _SECURITY_SECKEY_H_ 35 36#include <dispatch/dispatch.h> 37#include <Security/SecBase.h> 38#include <Security/SecAccess.h> 39#include <Security/cssmtype.h> 40#include <CoreFoundation/CFDictionary.h> 41#include <sys/types.h> 42 43#if defined(__cplusplus) 44extern "C" { 45#endif 46 47/*! 48 @enum KeyItemAttributeConstants 49 @abstract Specifies keychain item attributes for keys. 50 @constant kSecKeyKeyClass type uint32 (CSSM_KEYCLASS), value 51 is one of CSSM_KEYCLASS_PUBLIC_KEY, CSSM_KEYCLASS_PRIVATE_KEY 52 or CSSM_KEYCLASS_SESSION_KEY. 53 @constant kSecKeyPrintName type blob, human readable name of 54 the key. Same as kSecLabelItemAttr for normal keychain items. 55 @constant kSecKeyAlias type blob, currently unused. 56 @constant kSecKeyPermanent type uint32, value is nonzero iff 57 this key is permanent (stored in some keychain). This is always 58 1. 59 @constant kSecKeyPrivate type uint32, value is nonzero iff this 60 key is protected by a user login or a password, or both. 61 @constant kSecKeyModifiable type uint32, value is nonzero iff 62 attributes of this key can be modified. 63 @constant kSecKeyLabel type blob, for private and public keys 64 this contains the hash of the public key. This is used to 65 associate certificates and keys. Its value matches the value 66 of the kSecPublicKeyHashItemAttr of a certificate and it's used 67 to construct an identity from a certificate and a key. 68 For symmetric keys this is whatever the creator of the key 69 passed in during the generate key call. 70 @constant kSecKeyApplicationTag type blob, currently unused. 71 @constant kSecKeyKeyCreator type data, the data points to a 72 CSSM_GUID structure representing the moduleid of the csp owning 73 this key. 74 @constant kSecKeyKeyType type uint32, value is a CSSM_ALGORITHMS 75 representing the algorithm associated with this key. 76 @constant kSecKeyKeySizeInBits type uint32, value is the number 77 of bits in this key. 78 @constant kSecKeyEffectiveKeySize type uint32, value is the 79 effective number of bits in this key. For example a des key 80 has a kSecKeyKeySizeInBits of 64 but a kSecKeyEffectiveKeySize 81 of 56. 82 @constant kSecKeyStartDate type CSSM_DATE. Earliest date from 83 which this key may be used. If the value is all zeros or not 84 present, no restriction applies. 85 @constant kSecKeyEndDate type CSSM_DATE. Latest date at 86 which this key may be used. If the value is all zeros or not 87 present, no restriction applies. 88 @constant kSecKeySensitive type uint32, iff value is nonzero 89 this key cannot be wrapped with CSSM_ALGID_NONE. 90 @constant kSecKeyAlwaysSensitive type uint32, value is nonzero 91 iff this key has always been marked sensitive. 92 @constant kSecKeyExtractable type uint32, value is nonzero iff 93 this key can be wrapped. 94 @constant kSecKeyNeverExtractable type uint32, value is nonzero 95 iff this key was never marked extractable. 96 @constant kSecKeyEncrypt type uint32, value is nonzero iff this 97 key can be used in an encrypt operation. 98 @constant kSecKeyDecrypt type uint32, value is nonzero iff this 99 key can be used in a decrypt operation. 100 @constant kSecKeyDerive type uint32, value is nonzero iff this 101 key can be used in a deriveKey operation. 102 @constant kSecKeySign type uint32, value is nonzero iff this 103 key can be used in a sign operation. 104 @constant kSecKeyVerify type uint32, value is nonzero iff this 105 key can be used in a verify operation. 106 @constant kSecKeySignRecover type uint32. 107 @constant kSecKeyVerifyRecover type uint32. 108 key can unwrap other keys. 109 @constant kSecKeyWrap type uint32, value is nonzero iff this 110 key can wrap other keys. 111 @constant kSecKeyUnwrap type uint32, value is nonzero iff this 112 key can unwrap other keys. 113 @discussion 114 The use of these enumerations has been deprecated. Please 115 use the equivalent items defined in SecItem.h 116 @@@. 117*/ 118enum 119{ 120 kSecKeyKeyClass = 0, 121 kSecKeyPrintName = 1, 122 kSecKeyAlias = 2, 123 kSecKeyPermanent = 3, 124 kSecKeyPrivate = 4, 125 kSecKeyModifiable = 5, 126 kSecKeyLabel = 6, 127 kSecKeyApplicationTag = 7, 128 kSecKeyKeyCreator = 8, 129 kSecKeyKeyType = 9, 130 kSecKeyKeySizeInBits = 10, 131 kSecKeyEffectiveKeySize = 11, 132 kSecKeyStartDate = 12, 133 kSecKeyEndDate = 13, 134 kSecKeySensitive = 14, 135 kSecKeyAlwaysSensitive = 15, 136 kSecKeyExtractable = 16, 137 kSecKeyNeverExtractable = 17, 138 kSecKeyEncrypt = 18, 139 kSecKeyDecrypt = 19, 140 kSecKeyDerive = 20, 141 kSecKeySign = 21, 142 kSecKeyVerify = 22, 143 kSecKeySignRecover = 23, 144 kSecKeyVerifyRecover = 24, 145 kSecKeyWrap = 25, 146 kSecKeyUnwrap = 26 147}; 148 149/*! 150 @typedef SecCredentialType 151 @abstract Determines the type of credential returned by SecKeyGetCredentials. 152*/ 153typedef uint32 SecCredentialType; 154 155/*! 156 @enum SecCredentialType 157 @abstract Determines the type of credential returned by SecKeyGetCredentials. 158 @constant kSecCredentialTypeWithUI Operations with this key are allowed to present UI if required. 159 @constant kSecCredentialTypeNoUI Operations with this key are not allowed to present UI, and will fail if UI is required. 160 @constant kSecCredentialTypeDefault The default setting for determining whether to present UI is used. This setting can be changed with a call to SecKeychainSetUserInteractionAllowed. 161*/ 162enum 163{ 164 kSecCredentialTypeDefault = 0, 165 kSecCredentialTypeWithUI, 166 kSecCredentialTypeNoUI 167}; 168 169/*! 170 @typedef SecPadding 171 @abstract Supported padding types. 172*/ 173typedef uint32_t SecPadding; 174enum 175{ 176 kSecPaddingNone = 0, 177 kSecPaddingPKCS1 = 1, 178 179 /* For SecKeyRawSign/SecKeyRawVerify only, data to be signed is an MD2 180 hash; standard ASN.1 padding will be done, as well as PKCS1 padding 181 of the underlying RSA operation. */ 182 kSecPaddingPKCS1MD2 = 0x8000, 183 184 /* For SecKeyRawSign/SecKeyRawVerify only, data to be signed is an MD5 185 hash; standard ASN.1 padding will be done, as well as PKCS1 padding 186 of the underlying RSA operation. */ 187 kSecPaddingPKCS1MD5 = 0x8001, 188 189 /* For SecKeyRawSign/SecKeyRawVerify only, data to be signed is a SHA1 190 hash; standard ASN.1 padding will be done, as well as PKCS1 padding 191 of the underlying RSA operation. */ 192 kSecPaddingPKCS1SHA1 = 0x8002, 193}; 194 195/*! 196 @typedef SecKeySizes 197 @abstract Supported key lengths. 198*/ 199typedef uint32_t SecKeySizes; 200enum 201{ 202 kSecDefaultKeySize = 0, 203 204 // Symmetric Keysizes - default is currently kSecAES128 for AES. 205 kSec3DES192 = 192, 206 kSecAES128 = 128, 207 kSecAES192 = 192, 208 kSecAES256 = 256, 209 210 // Supported ECC Keys for Suite-B from RFC 4492 section 5.1.1. 211 // default is currently kSecp256r1 212 kSecp192r1 = 192, 213 kSecp256r1 = 256, 214 kSecp384r1 = 384, 215 kSecp521r1 = 521, // Yes, 521 216 217 // Boundaries for RSA KeySizes - default is currently 2048 218 // RSA keysizes must be multiples of 8 219 kSecRSAMin = 1024, 220 kSecRSAMax = 4096 221}; 222 223/*! 224 @enum Key Parameter Constants 225 @discussion Predefined key constants used to get or set values in a dictionary. 226 These are used to provide explicit parameters to key generation functions 227 when non-default values are desired. See the description of the 228 SecKeyGeneratePair API for usage information. 229 @constant kSecPrivateKeyAttrs The value for this key is a CFDictionaryRef 230 containing attributes specific for the private key to be generated. 231 @constant kSecPublicKeyAttrs The value for this key is a CFDictionaryRef 232 containing attributes specific for the public key to be generated. 233*/ 234extern CFTypeRef kSecPrivateKeyAttrs 235 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_2_0); 236extern CFTypeRef kSecPublicKeyAttrs 237 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_2_0); 238 239 240/*! 241 @function SecKeyGetTypeID 242 @abstract Returns the type identifier of SecKey instances. 243 @result The CFTypeID of SecKey instances. 244*/ 245CFTypeID SecKeyGetTypeID(void) 246 __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0); 247 248/*! 249 @function SecKeyCreatePair 250 @abstract Creates an asymmetric key pair and stores it in a specified keychain. 251 @param keychainRef A reference to the keychain in which to store the private and public key items. Specify NULL for the default keychain. 252 @param algorithm An algorithm for the key pair. This parameter is ignored if a valid (non-zero) contextHandle is supplied. 253 @param keySizeInBits A key size for the key pair. This parameter is ignored if a valid (non-zero) contextHandle is supplied. 254 @param contextHandle (optional) A CSSM_CC_HANDLE, or 0. If this argument is supplied, the algorithm and keySizeInBits parameters are ignored. If extra parameters are needed to generate a key (some algorithms require this), you should create a context using CSSM_CSP_CreateKeyGenContext, using the CSPHandle obtained by calling SecKeychainGetCSPHandle. Then use CSSM_UpdateContextAttributes to add parameters, and dispose of the context using CSSM_DeleteContext after calling this function. 255 @param publicKeyUsage A bit mask indicating all permitted uses for the new public key. CSSM_KEYUSE bit mask values are defined in cssmtype.h. 256 @param publicKeyAttr A bit mask defining attribute values for the new public key. The bit mask values are equivalent to a CSSM_KEYATTR_FLAGS and are defined in cssmtype.h. 257 @param privateKeyUsage A bit mask indicating all permitted uses for the new private key. CSSM_KEYUSE bit mask values are defined in cssmtype.h. 258 @param privateKeyAttr A bit mask defining attribute values for the new private key. The bit mask values are equivalent to a CSSM_KEYATTR_FLAGS and are defined in cssmtype.h. 259 @param initialAccess (optional) A SecAccess object that determines the initial access rights to the private key. The public key is given "any/any" access rights by default. 260 @param publicKey (optional) On return, the keychain item reference of the generated public key. Use the SecKeyGetCSSMKey function to obtain the CSSM_KEY. The caller must call CFRelease on this value if it is returned. Pass NULL if a reference to this key is not required. 261 @param privateKey (optional) On return, the keychain item reference of the generated private key. Use the SecKeyGetCSSMKey function to obtain the CSSM_KEY. The caller must call CFRelease on this value if it is returned. Pass NULL if a reference to this key is not required. 262 @result A result code. See "Security Error Codes" (SecBase.h). 263 @discussion This API is deprecated for 10.7. Please use the SecKeyGeneratePair API instead. 264*/ 265OSStatus SecKeyCreatePair( 266 SecKeychainRef keychainRef, 267 CSSM_ALGORITHMS algorithm, 268 uint32 keySizeInBits, 269 CSSM_CC_HANDLE contextHandle, 270 CSSM_KEYUSE publicKeyUsage, 271 uint32 publicKeyAttr, 272 CSSM_KEYUSE privateKeyUsage, 273 uint32 privateKeyAttr, 274 SecAccessRef initialAccess, 275 SecKeyRef* publicKey, 276 SecKeyRef* privateKey) 277 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER; 278 279/*! 280 @function SecKeyGenerate 281 @abstract Creates a symmetric key and optionally stores it in a specified keychain. 282 @param keychainRef (optional) A reference to the keychain in which to store the generated key. Specify NULL to generate a transient key. 283 @param algorithm An algorithm for the symmetric key. This parameter is ignored if a valid (non-zero) contextHandle is supplied. 284 @param keySizeInBits A key size for the key pair. This parameter is ignored if a valid (non-zero) contextHandle is supplied. 285 @param contextHandle (optional) A CSSM_CC_HANDLE, or 0. If this argument is supplied, the algorithm and keySizeInBits parameters are ignored. If extra parameters are needed to generate a key (some algorithms require this), you should create a context using CSSM_CSP_CreateKeyGenContext, using the CSPHandle obtained by calling SecKeychainGetCSPHandle. Then use CSSM_UpdateContextAttributes to add parameters, and dispose of the context using CSSM_DeleteContext after calling this function. 286 @param keyUsage A bit mask indicating all permitted uses for the new key. CSSM_KEYUSE bit mask values are defined in cssmtype.h. 287 @param keyAttr A bit mask defining attribute values for the new key. The bit mask values are equivalent to a CSSM_KEYATTR_FLAGS and are defined in cssmtype.h. 288 @param initialAccess (optional) A SecAccess object that determines the initial access rights for the key. This parameter is ignored if the keychainRef is NULL. 289 @param keyRef On return, a reference to the generated key. Use the SecKeyGetCSSMKey function to obtain the CSSM_KEY. The caller must call CFRelease on this value if it is returned. 290 @result A result code. See "Security Error Codes" (SecBase.h). 291 @discussion This API is deprecated for 10.7. Please use the SecKeyGenerateSymmetric API instead. 292*/ 293OSStatus SecKeyGenerate( 294 SecKeychainRef keychainRef, 295 CSSM_ALGORITHMS algorithm, 296 uint32 keySizeInBits, 297 CSSM_CC_HANDLE contextHandle, 298 CSSM_KEYUSE keyUsage, 299 uint32 keyAttr, 300 SecAccessRef initialAccess, 301 SecKeyRef* keyRef) 302 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER; 303 304/*! 305 @function SecKeyGetCSSMKey 306 @abstract Returns a pointer to the CSSM_KEY for the given key item reference. 307 @param key A keychain key item reference. The key item must be of class type kSecPublicKeyItemClass, kSecPrivateKeyItemClass, or kSecSymmetricKeyItemClass. 308 @param cssmKey On return, a pointer to a CSSM_KEY structure for the given key. This pointer remains valid until the key reference is released. The caller should not attempt to modify or free this data. 309 @result A result code. See "Security Error Codes" (SecBase.h). 310 @discussion The CSSM_KEY is valid until the key item reference is released. This API is deprecated in 10.7. Its use should no longer be needed. 311*/ 312OSStatus SecKeyGetCSSMKey(SecKeyRef key, const CSSM_KEY **cssmKey) 313 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;; 314 315/*! 316 @function SecKeyGetCSPHandle 317 @abstract Returns the CSSM_CSP_HANDLE for the given key reference. The handle is valid until the key reference is released. 318 @param keyRef A key reference. 319 @param cspHandle On return, the CSSM_CSP_HANDLE for the given keychain. 320 @result A result code. See "Security Error Codes" (SecBase.h). 321 @discussion This API is deprecated in 10.7. Its use should no longer be needed. 322*/ 323OSStatus SecKeyGetCSPHandle(SecKeyRef keyRef, CSSM_CSP_HANDLE *cspHandle) 324 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER; 325 326/*! 327 @function SecKeyGetCredentials 328 @abstract For a given key, return a pointer to a CSSM_ACCESS_CREDENTIALS structure which will allow the key to be used. 329 @param keyRef The key for which a credential is requested. 330 @param operation The type of operation to be performed with this key. See "Authorization tag type" for defined operations (cssmtype.h). 331 @param credentialType The type of credential requested. 332 @param outCredentials On return, a pointer to a CSSM_ACCESS_CREDENTIALS structure. This pointer remains valid until the key reference is released. The caller should not attempt to modify or free this data. 333 @result A result code. See "Security Error Codes" (SecBase.h). 334*/ 335OSStatus SecKeyGetCredentials( 336 SecKeyRef keyRef, 337 CSSM_ACL_AUTHORIZATION_TAG operation, 338 SecCredentialType credentialType, 339 const CSSM_ACCESS_CREDENTIALS **outCredentials) 340 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER; 341 342/*! 343 @function SecKeyGetBlockSize 344 @abstract Decrypt a block of ciphertext. 345 @param key The key for which the block length is requested. 346 @result The block length of the key in bytes. 347 @discussion If for example key is an RSA key the value returned by 348 this function is the size of the modulus. 349 */ 350size_t SecKeyGetBlockSize(SecKeyRef key) 351 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0); 352 353/*! 354 @function SecKeyGenerateSymmetric 355 @abstract Generates a random symmetric key with the specified length 356 and algorithm type. 357 358 @param parameters A dictionary containing one or more key-value pairs. 359 See the discussion sections below for a complete overview of options. 360 @param error An optional pointer to a CFErrorRef. This value is set 361 if an error occurred. If not NULL, the caller is responsible for 362 releasing the CFErrorRef. 363 @result On return, a SecKeyRef reference to the symmetric key, or 364 NULL if the key could not be created. 365 366 @discussion In order to generate a symmetric key, the parameters dictionary 367 must at least contain the following keys: 368 369 * kSecAttrKeyType with a value of kSecAttrKeyTypeAES or any other 370 kSecAttrKeyType defined in SecItem.h 371 * kSecAttrKeySizeInBits with a value being a CFNumberRef containing 372 the requested key size in bits. Example sizes for AES keys are: 373 128, 192, 256, 512. 374 375 To store the generated symmetric key in a keychain, set these keys: 376 * kSecUseKeychain (value is a SecKeychainRef) 377 * kSecAttrLabel (a user-visible label whose value is a CFStringRef, 378 e.g. "My App's Encryption Key") 379 * kSecAttrApplicationLabel (a label defined by your application, whose 380 value is a CFStringRef and which can be used to find this key in a 381 subsequent call to SecItemCopyMatching, e.g. "ID-1234567890-9876-0151") 382 383 To specify the generated key's access control settings, set this key: 384 * kSecAttrAccess (value is a SecAccessRef) 385 386 The keys below may be optionally set in the parameters dictionary 387 (with a CFBooleanRef value) to override the default usage values: 388 389 * kSecAttrCanEncrypt (defaults to true if not explicitly specified) 390 * kSecAttrCanDecrypt (defaults to true if not explicitly specified) 391 * kSecAttrCanWrap (defaults to true if not explicitly specified) 392 * kSecAttrCanUnwrap (defaults to true if not explicitly specified) 393 394*/ 395SecKeyRef SecKeyGenerateSymmetric(CFDictionaryRef parameters, CFErrorRef *error) 396 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 397 398 399/*! 400 @function SecKeyCreateFromData 401 @abstract Creates a symmetric key with the given data and sets the 402 algorithm type specified. 403 404 @param parameters A dictionary containing one or more key-value pairs. 405 See the discussion sections below for a complete overview of options. 406 @result On return, a SecKeyRef reference to the symmetric key. 407 408 @discussion In order to generate a symmetric key the parameters dictionary must 409 at least contain the following keys: 410 411 * kSecAttrKeyType with a value of kSecAttrKeyTypeAES or any other 412 kSecAttrKeyType defined in SecItem.h 413 414 The keys below may be optionally set in the parameters dictionary 415 (with a CFBooleanRef value) to override the default usage values: 416 417 * kSecAttrCanEncrypt (defaults to true if not explicitly specified) 418 * kSecAttrCanDecrypt (defaults to true if not explicitly specified) 419 * kSecAttrCanWrap (defaults to true if not explicitly specified) 420 * kSecAttrCanUnwrap (defaults to true if not explicitly specified) 421 422*/ 423SecKeyRef SecKeyCreateFromData(CFDictionaryRef parameters, 424 CFDataRef keyData, CFErrorRef *error) 425 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 426 427 428/*! 429 @function SecKeyGeneratePair 430 @abstract Generate a private/public keypair. 431 @param parameters A dictionary containing one or more key-value pairs. 432 @result A result code. See "Security Error Codes" (SecBase.h). On success, 433 the result code will be errSecSuccess, and the output parameters will 434 contain the public SecKeyRef and private SecKeyRef. It is the caller's 435 responsibility to CFRelease these key references when finished with them. 436 437 @discussion In order to generate a keypair the parameters dictionary must 438 at least contain the following keys: 439 440 * kSecAttrKeyType with a value of kSecAttrKeyTypeRSA or any other 441 kSecAttrKeyType defined in SecItem.h 442 * kSecAttrKeySizeInBits with a value being a CFNumberRef containing 443 the requested key size in bits. Example sizes for RSA keys are: 444 512, 768, 1024, 2048. 445 446 The values below may be set either in the top-level dictionary or in a 447 dictionary that is the value of the kSecPrivateKeyAttrs or 448 kSecPublicKeyAttrs key in the top-level dictionary. Setting these 449 attributes explicitly will override the defaults below. See SecItem.h 450 for detailed information on these attributes including the types of 451 the values. 452 453 * kSecAttrLabel default NULL 454 * kSecUseKeychain default NULL, which specifies the default keychain 455 * kSecAttrApplicationTag default NULL 456 * kSecAttrEffectiveKeySize default NULL same as kSecAttrKeySizeInBits 457 * kSecAttrCanEncrypt default false for private keys, true for public keys 458 * kSecAttrCanDecrypt default true for private keys, false for public keys 459 * kSecAttrCanDerive default true 460 * kSecAttrCanSign default true for private keys, false for public keys 461 * kSecAttrCanVerify default false for private keys, true for public keys 462 * kSecAttrCanWrap default false for private keys, true for public keys 463 * kSecAttrCanUnwrap default true for private keys, false for public keys 464 465*/ 466OSStatus SecKeyGeneratePair(CFDictionaryRef parameters, 467 SecKeyRef *publicKey, SecKeyRef *privateKey) 468 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0); 469 470/*! 471 @typedef SecKeyGeneratePairBlock 472 @abstract Delivers the result from an asynchronous key pair generation. 473 @param publicKey - the public key generated. You must retain publicKey if you wish to use it after your block returns. 474 @param privateKey - the private key generated. You must retain publicKey if you wish to use it after your block returns. 475 @param error - Any errors returned. You must retain error if you wish to use it after your block returns. 476 */ 477 478#ifdef __BLOCKS__ 479typedef void (^SecKeyGeneratePairBlock)(SecKeyRef publicKey, SecKeyRef privateKey, CFErrorRef error); 480 481 482/*! 483 @function SecKeyGeneratePairAsync 484 @abstract Generate a private/public keypair returning the values in a callback. 485 @param parameters A dictionary containing one or more key-value pairs. 486 @param deliveryQueue A dispatch queue to be used to deliver the results. 487 @param result A callback function to result when the operation has completed. 488 @result On success the function returns NULL. 489 490 @discussion In order to generate a keypair the parameters dictionary must 491 at least contain the following keys: 492 493 * kSecAttrKeyType with a value being kSecAttrKeyTypeRSA or any other 494 kSecAttrKeyType defined in SecItem.h 495 * kSecAttrKeySizeInBits with a value being a CFNumberRef or CFStringRef 496 containing the requested key size in bits. Example sizes for RSA 497 keys are: 512, 768, 1024, 2048. 498 499 Setting the following attributes explicitly will override the defaults below. 500 See SecItem.h for detailed information on these attributes including the types 501 of the values. 502 503 * kSecAttrLabel default NULL 504 * kSecAttrIsPermanent if this key is present and has a Boolean 505 value of true, the key or key pair will be added to the default 506 keychain. 507 * kSecAttrApplicationTag default NULL 508 * kSecAttrEffectiveKeySize default NULL same as kSecAttrKeySizeInBits 509 * kSecAttrCanEncrypt default false for private keys, true for public keys 510 * kSecAttrCanDecrypt default true for private keys, false for public keys 511 * kSecAttrCanDerive default true 512 * kSecAttrCanSign default true for private keys, false for public keys 513 * kSecAttrCanVerify default false for private keys, true for public keys 514 * kSecAttrCanWrap default false for private keys, true for public keys 515 * kSecAttrCanUnwrap default true for private keys, false for public keys 516 517*/ 518void SecKeyGeneratePairAsync(CFDictionaryRef parameters, 519 dispatch_queue_t deliveryQueue, SecKeyGeneratePairBlock result) 520 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 521 522#endif /* __BLOCKS__ */ 523 524// Derive, Wrap, and Unwrap 525 526/*! 527 @function SecKeyDeriveFromPassword 528 @abstract Derives a symmetric key from a password. 529 530 @param password The password from which the keyis to be derived. 531 @param parameters A dictionary containing one or more key-value pairs. 532 @param error If the call fails this will contain the error code. 533 534 @discussion In order to derive a key the parameters dictionary must contain at least contain the following keys: 535 * kSecAttrSalt - a CFData for the salt value for mixing in the pseudo-random rounds. 536 * kSecAttrPRF - the algorithm to use for the pseudo-random-function. 537 If 0, this defaults to kSecAttrPRFHmacAlgSHA1. Possible values are: 538 539 * kSecAttrPRFHmacAlgSHA1 540 * kSecAttrPRFHmacAlgSHA224 541 * kSecAttrPRFHmacAlgSHA256 542 * kSecAttrPRFHmacAlgSHA384 543 * kSecAttrPRFHmacAlgSHA512 544 545 * kSecAttrRounds - the number of rounds to call the pseudo random function. 546 If 0, a count will be computed to average 1/10 of a second. 547 * kSecAttrKeySizeInBits with a value being a CFNumberRef 548 containing the requested key size in bits. Example sizes for RSA keys are: 549 512, 768, 1024, 2048. 550 551 @result On success a SecKeyRef is returned. On failure this result is NULL and the 552 error parameter contains the reason. 553 554*/ 555SecKeyRef SecKeyDeriveFromPassword(CFStringRef password, 556 CFDictionaryRef parameters, CFErrorRef *error) 557 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 558 559/*! 560 @function SecKeyWrapSymmetric 561 @abstract Wraps a symmetric key with a symmetric key. 562 563 @param keyToWrap The key which is to be wrapped. 564 @param wrappingKey The key wrapping key. 565 #param parameters The parameter list to use for wrapping the key. 566 @param error If the call fails this will contain the error code. 567 568 @result On success a CFDataRef is returned. On failure this result is NULL and the 569 error parameter contains the reason. 570 571 @discussion In order to wrap a key the parameters dictionary may contain the following key: 572 * kSecSalt - a CFData for the salt value for the encrypt. 573 574*/ 575CFDataRef SecKeyWrapSymmetric(SecKeyRef keyToWrap, 576 SecKeyRef wrappingKey, CFDictionaryRef parameters, CFErrorRef *error) 577 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 578 579/*! 580 @function SecKeyUnwrapSymmetric 581 @abstract Unwrap a wrapped symmetric key. 582 583 @param keyToUnwrap The wrapped key to unwrap. 584 @param unwrappingKey The key unwrapping key. 585 #param parameters The parameter list to use for unwrapping the key. 586 @param error If the call fails this will contain the error code. 587 588 @result On success a SecKeyRef is returned. On failure this result is NULL and the 589 error parameter contains the reason. 590 591 @discussion In order to unwrap a key the parameters dictionary may contain the following key: 592 * kSecSalt - a CFData for the salt value for the decrypt. 593 594*/ 595SecKeyRef SecKeyUnwrapSymmetric(CFDataRef *keyToUnwrap, 596 SecKeyRef unwrappingKey, CFDictionaryRef parameters, CFErrorRef *error) 597 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 598 599 600#if defined(__cplusplus) 601} 602#endif 603 604#endif /* !_SECURITY_SECKEY_H_ */ 605