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