Security/libsecurity_keychain/lib/SecKey.h

   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)
  44 extern "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 */
 118 enum
 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 */
 153 typedef 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 */
 162 enum
 163 {
 164         kSecCredentialTypeDefault = 0,
 165         kSecCredentialTypeWithUI,
 166         kSecCredentialTypeNoUI
 167 };
 168
 169 /*!
 170     @typedef SecPadding
 171     @abstract Supported padding types.
 172 */
 173 typedef uint32_t SecPadding;
 174 enum
 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 */
 199 typedef uint32_t SecKeySizes;
 200 enum
 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 */
 234 extern CFTypeRef kSecPrivateKeyAttrs
 235     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_2_0);
 236 extern 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 */
 245 CFTypeID 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 */
 265 OSStatus 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 */
 293 OSStatus 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 */
 312 OSStatus 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 */
 323 OSStatus 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 */
 335 OSStatus 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  */
 350 size_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 */
 395 SecKeyRef 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 */
 423 SecKeyRef 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 */
 466 OSStatus 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__
 479 typedef 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 */
 518 void 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 */
 555 SecKeyRef 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 */
 575 CFDataRef 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 */
 595 SecKeyRef 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_ */