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 <CoreFoundation/CFSet.h>
  43 #include <sys/types.h>
  44
  45 #if defined(__cplusplus)
  46 extern "C" {
  47 #endif
  48
  49 CF_ASSUME_NONNULL_BEGIN
  50 CF_IMPLICIT_BRIDGING_ENABLED
  51
  52 /*!
  53         @enum KeyItemAttributeConstants
  54         @abstract Specifies keychain item attributes for keys.
  55     @constant kSecKeyKeyClass type uint32 (CSSM_KEYCLASS), value
  56     is one of CSSM_KEYCLASS_PUBLIC_KEY, CSSM_KEYCLASS_PRIVATE_KEY
  57     or CSSM_KEYCLASS_SESSION_KEY.
  58     @constant kSecKeyPrintName type blob, human readable name of
  59     the key.  Same as kSecLabelItemAttr for normal keychain items.
  60     @constant kSecKeyAlias type blob, currently unused.
  61     @constant kSecKeyPermanent type uint32, value is nonzero iff
  62     this key is permanent (stored in some keychain).  This is always
  63     1.
  64     @constant kSecKeyPrivate type uint32, value is nonzero iff this
  65     key is protected by a user login or a password, or both.
  66     @constant kSecKeyModifiable type uint32, value is nonzero iff
  67     attributes of this key can be modified.
  68     @constant kSecKeyLabel type blob, for private and public keys
  69     this contains the hash of the public key.  This is used to
  70     associate certificates and keys.  Its value matches the value
  71     of the kSecPublicKeyHashItemAttr of a certificate and it's used
  72     to construct an identity from a certificate and a key.
  73     For symmetric keys this is whatever the creator of the key
  74     passed in during the generate key call.
  75     @constant kSecKeyApplicationTag type blob, currently unused.
  76     @constant kSecKeyKeyCreator type data, the data points to a
  77     CSSM_GUID structure representing the moduleid of the csp owning
  78     this key.
  79     @constant kSecKeyKeyType type uint32, value is a CSSM_ALGORITHMS
  80     representing the algorithm associated with this key.
  81     @constant kSecKeyKeySizeInBits type uint32, value is the number
  82     of bits in this key.
  83     @constant kSecKeyEffectiveKeySize type uint32, value is the
  84     effective number of bits in this key.  For example a des key
  85     has a kSecKeyKeySizeInBits of 64 but a kSecKeyEffectiveKeySize
  86     of 56.
  87     @constant kSecKeyStartDate type CSSM_DATE.  Earliest date from
  88     which this key may be used.  If the value is all zeros or not
  89     present, no restriction applies.
  90     @constant kSecKeyEndDate type CSSM_DATE.  Latest date at
  91     which this key may be used.  If the value is all zeros or not
  92     present, no restriction applies.
  93     @constant kSecKeySensitive type uint32, iff value is nonzero
  94     this key cannot be wrapped with CSSM_ALGID_NONE.
  95     @constant kSecKeyAlwaysSensitive type uint32, value is nonzero
  96     iff this key has always been marked sensitive.
  97     @constant kSecKeyExtractable type uint32, value is nonzero iff
  98     this key can be wrapped.
  99     @constant kSecKeyNeverExtractable type uint32, value is nonzero
 100     iff this key was never marked extractable.
 101     @constant kSecKeyEncrypt type uint32, value is nonzero iff this
 102     key can be used in an encrypt operation.
 103     @constant kSecKeyDecrypt type uint32, value is nonzero iff this
 104     key can be used in a decrypt operation.
 105     @constant kSecKeyDerive type uint32, value is nonzero iff this
 106     key can be used in a deriveKey operation.
 107     @constant kSecKeySign type uint32, value is nonzero iff this
 108     key can be used in a sign operation.
 109     @constant kSecKeyVerify type uint32, value is nonzero iff this
 110     key can be used in a verify operation.
 111     @constant kSecKeySignRecover type uint32.
 112     @constant kSecKeyVerifyRecover type uint32.
 113     key can unwrap other keys.
 114     @constant kSecKeyWrap type uint32, value is nonzero iff this
 115     key can wrap other keys.
 116     @constant kSecKeyUnwrap type uint32, value is nonzero iff this
 117     key can unwrap other keys.
 118         @discussion
 119         The use of these enumerations has been deprecated.  Please
 120         use the equivalent items defined in SecItem.h
 121         @@@.
 122 */
 123 CF_ENUM(int)
 124 {
 125     kSecKeyKeyClass =          0,
 126     kSecKeyPrintName =         1,
 127     kSecKeyAlias =             2,
 128     kSecKeyPermanent =         3,
 129     kSecKeyPrivate =           4,
 130     kSecKeyModifiable =        5,
 131     kSecKeyLabel =             6,
 132     kSecKeyApplicationTag =    7,
 133     kSecKeyKeyCreator =        8,
 134     kSecKeyKeyType =           9,
 135     kSecKeyKeySizeInBits =    10,
 136     kSecKeyEffectiveKeySize = 11,
 137     kSecKeyStartDate =        12,
 138     kSecKeyEndDate =          13,
 139     kSecKeySensitive =        14,
 140     kSecKeyAlwaysSensitive =  15,
 141     kSecKeyExtractable =      16,
 142     kSecKeyNeverExtractable = 17,
 143     kSecKeyEncrypt =          18,
 144     kSecKeyDecrypt =          19,
 145     kSecKeyDerive =           20,
 146     kSecKeySign =             21,
 147     kSecKeyVerify =           22,
 148     kSecKeySignRecover =      23,
 149     kSecKeyVerifyRecover =    24,
 150     kSecKeyWrap =             25,
 151     kSecKeyUnwrap =           26
 152 };
 153
 154     /*!
 155     @enum SecCredentialType
 156     @abstract Determines the type of credential returned by SecKeyGetCredentials.
 157     @constant kSecCredentialTypeWithUI Operations with this key are allowed to present UI if required.
 158     @constant kSecCredentialTypeNoUI Operations with this key are not allowed to present UI, and will fail if UI is required.
 159     @constant kSecCredentialTypeDefault The default setting for determining whether to present UI is used. This setting can be changed with a call to SecKeychainSetUserInteractionAllowed.
 160 */
 161 typedef CF_ENUM(uint32, SecCredentialType)
 162 {
 163         kSecCredentialTypeDefault = 0,
 164         kSecCredentialTypeWithUI,
 165         kSecCredentialTypeNoUI
 166 };
 167
 168 /*!
 169     @typedef SecPadding
 170     @abstract Supported padding types.
 171 */
 172 typedef CF_ENUM(uint32_t, SecPadding)
 173 {
 174     kSecPaddingNone      = 0,
 175     kSecPaddingPKCS1     = 1,
 176
 177     /* For SecKeyRawSign/SecKeyRawVerify only,
 178      ECDSA signature is raw byte format {r,s}, big endian.
 179      First half is r, second half is s */
 180     kSecPaddingSigRaw  = 0x4000,
 181
 182     /* For SecKeyRawSign/SecKeyRawVerify only, data to be signed is an MD2
 183        hash; standard ASN.1 padding will be done, as well as PKCS1 padding
 184        of the underlying RSA operation. */
 185     kSecPaddingPKCS1MD2  = 0x8000,
 186
 187     /* For SecKeyRawSign/SecKeyRawVerify only, data to be signed is an MD5
 188        hash; standard ASN.1 padding will be done, as well as PKCS1 padding
 189        of the underlying RSA operation. */
 190     kSecPaddingPKCS1MD5  = 0x8001,
 191
 192     /* For SecKeyRawSign/SecKeyRawVerify only, data to be signed is a SHA1
 193        hash; standard ASN.1 padding will be done, as well as PKCS1 padding
 194        of the underlying RSA operation. */
 195     kSecPaddingPKCS1SHA1 = 0x8002,
 196 };
 197
 198 /*!
 199     @typedef SecKeySizes
 200     @abstract Supported key lengths.
 201 */
 202 typedef CF_ENUM(uint32_t, SecKeySizes)
 203 {
 204     kSecDefaultKeySize  = 0,
 205
 206     // Symmetric Keysizes - default is currently kSecAES128 for AES.
 207     kSec3DES192         = 192,
 208     kSecAES128          = 128,
 209     kSecAES192          = 192,
 210     kSecAES256          = 256,
 211
 212     // Supported ECC Keys for Suite-B from RFC 4492 section 5.1.1.
 213     // default is currently kSecp256r1
 214     kSecp192r1          = 192,
 215     kSecp256r1          = 256,
 216     kSecp384r1          = 384,
 217     kSecp521r1          = 521,  // Yes, 521
 218
 219     // Boundaries for RSA KeySizes - default is currently 2048
 220     // RSA keysizes must be multiples of 8
 221     kSecRSAMin          = 1024,
 222     kSecRSAMax          = 4096
 223 };
 224
 225 /*!
 226         @enum Key Parameter Constants
 227         @discussion Predefined key constants used to get or set values in a dictionary.
 228         These are used to provide explicit parameters to key generation functions
 229         when non-default values are desired. See the description of the
 230         SecKeyGeneratePair API for usage information.
 231         @constant kSecPrivateKeyAttrs The value for this key is a CFDictionaryRef
 232          containing attributes specific for the private key to be generated.
 233         @constant kSecPublicKeyAttrs The value for this key is a CFDictionaryRef
 234          containing attributes specific for the public key to be generated.
 235 */
 236 extern const CFStringRef kSecPrivateKeyAttrs
 237     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_2_0);
 238 extern const CFStringRef kSecPublicKeyAttrs
 239     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_2_0);
 240
 241
 242 /*!
 243         @function SecKeyGetTypeID
 244         @abstract Returns the type identifier of SecKey instances.
 245         @result The CFTypeID of SecKey instances.
 246 */
 247 CFTypeID SecKeyGetTypeID(void)
 248         __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);
 249
 250 /*!
 251         @function SecKeyCreatePair
 252         @abstract Creates an asymmetric key pair and stores it in a specified keychain.
 253         @param keychainRef A reference to the keychain in which to store the private and public key items. Specify NULL for the default keychain.
 254         @param algorithm An algorithm for the key pair. This parameter is ignored if a valid (non-zero) contextHandle is supplied.
 255         @param keySizeInBits A key size for the key pair. This parameter is ignored if a valid (non-zero) contextHandle is supplied.
 256         @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.
 257         @param publicKeyUsage A bit mask indicating all permitted uses for the new public key. CSSM_KEYUSE bit mask values are defined in cssmtype.h.
 258         @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.
 259         @param privateKeyUsage A bit mask indicating all permitted uses for the new private key. CSSM_KEYUSE bit mask values are defined in cssmtype.h.
 260         @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.
 261         @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.
 262         @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.
 263         @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.
 264         @result A result code. See "Security Error Codes" (SecBase.h).
 265         @discussion This API is deprecated for 10.7. Please use the SecKeyGeneratePair API instead.
 266 */
 267 OSStatus SecKeyCreatePair(
 268         SecKeychainRef _Nullable keychainRef,
 269         CSSM_ALGORITHMS algorithm,
 270         uint32 keySizeInBits,
 271         CSSM_CC_HANDLE contextHandle,
 272         CSSM_KEYUSE publicKeyUsage,
 273         uint32 publicKeyAttr,
 274         CSSM_KEYUSE privateKeyUsage,
 275         uint32 privateKeyAttr,
 276         SecAccessRef _Nullable initialAccess,
 277         SecKeyRef* _Nullable CF_RETURNS_RETAINED publicKey,
 278         SecKeyRef* _Nullable CF_RETURNS_RETAINED privateKey)
 279                 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 280
 281 /*!
 282         @function SecKeyGenerate
 283         @abstract Creates a symmetric key and optionally stores it in a specified keychain.
 284         @param keychainRef (optional) A reference to the keychain in which to store the generated key. Specify NULL to generate a transient key.
 285         @param algorithm An algorithm for the symmetric key. This parameter is ignored if a valid (non-zero) contextHandle is supplied.
 286         @param keySizeInBits A key size for the key pair. This parameter is ignored if a valid (non-zero) contextHandle is supplied.
 287         @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.
 288         @param keyUsage A bit mask indicating all permitted uses for the new key. CSSM_KEYUSE bit mask values are defined in cssmtype.h.
 289         @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.
 290         @param initialAccess (optional) A SecAccess object that determines the initial access rights for the key. This parameter is ignored if the keychainRef is NULL.
 291         @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.
 292         @result A result code.  See "Security Error Codes" (SecBase.h).
 293         @discussion This API is deprecated for 10.7.  Please use the SecKeyGenerateSymmetric API instead.
 294 */
 295 OSStatus SecKeyGenerate(
 296         SecKeychainRef _Nullable keychainRef,
 297         CSSM_ALGORITHMS algorithm,
 298         uint32 keySizeInBits,
 299         CSSM_CC_HANDLE contextHandle,
 300         CSSM_KEYUSE keyUsage,
 301         uint32 keyAttr,
 302         SecAccessRef _Nullable initialAccess,
 303         SecKeyRef* _Nullable CF_RETURNS_RETAINED keyRef)
 304                 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 305
 306 /*!
 307     @function SecKeyGetCSSMKey
 308     @abstract Returns a pointer to the CSSM_KEY for the given key item reference.
 309     @param key A keychain key item reference. The key item must be of class type kSecPublicKeyItemClass, kSecPrivateKeyItemClass, or kSecSymmetricKeyItemClass.
 310     @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.
 311     @result A result code. See "Security Error Codes" (SecBase.h).
 312     @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.
 313 */
 314 OSStatus SecKeyGetCSSMKey(SecKeyRef key, const CSSM_KEY * _Nullable * __nonnull cssmKey)
 315         DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;;
 316
 317 /*!
 318     @function SecKeyGetCSPHandle
 319     @abstract Returns the CSSM_CSP_HANDLE for the given key reference. The handle is valid until the key reference is released.
 320     @param keyRef A key reference.
 321     @param cspHandle On return, the CSSM_CSP_HANDLE for the given keychain.
 322     @result A result code. See "Security Error Codes" (SecBase.h).
 323         @discussion This API is deprecated in 10.7. Its use should no longer be needed.
 324 */
 325 OSStatus SecKeyGetCSPHandle(SecKeyRef keyRef, CSSM_CSP_HANDLE *cspHandle)
 326         DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 327
 328 /*!
 329     @function SecKeyGetCredentials
 330     @abstract For a given key, return a pointer to a CSSM_ACCESS_CREDENTIALS structure which will allow the key to be used.
 331     @param keyRef The key for which a credential is requested.
 332     @param operation The type of operation to be performed with this key. See "Authorization tag type" for defined operations (cssmtype.h).
 333     @param credentialType The type of credential requested.
 334     @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.
 335     @result A result code. See "Security Error Codes" (SecBase.h).
 336 */
 337 OSStatus SecKeyGetCredentials(
 338         SecKeyRef keyRef,
 339         CSSM_ACL_AUTHORIZATION_TAG operation,
 340         SecCredentialType credentialType,
 341         const CSSM_ACCESS_CREDENTIALS * _Nullable * __nonnull outCredentials)
 342                 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 343
 344 /*!
 345     @function SecKeyGetBlockSize
 346     @abstract Decrypt a block of ciphertext.
 347     @param key The key for which the block length is requested.
 348     @result The block length of the key in bytes.
 349     @discussion If for example key is an RSA key the value returned by
 350     this function is the size of the modulus.
 351  */
 352 size_t SecKeyGetBlockSize(SecKeyRef key)
 353         __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 354
 355 /*!
 356  @function      SecKeyGenerateSymmetric
 357  @abstract      Generates a random symmetric key with the specified length
 358  and algorithm type.
 359
 360  @param parameters A dictionary containing one or more key-value pairs.
 361  See the discussion sections below for a complete overview of options.
 362  @param error An optional pointer to a CFErrorRef. This value is set
 363  if an error occurred. If not NULL, the caller is responsible for
 364  releasing the CFErrorRef.
 365  @result On return, a SecKeyRef reference to the symmetric key, or
 366  NULL if the key could not be created.
 367
 368  @discussion In order to generate a symmetric key, the parameters dictionary
 369  must at least contain the following keys:
 370
 371  * kSecAttrKeyType with a value of kSecAttrKeyTypeAES or any other
 372  kSecAttrKeyType defined in SecItem.h
 373  * kSecAttrKeySizeInBits with a value being a CFNumberRef containing
 374  the requested key size in bits.  Example sizes for AES keys are:
 375  128, 192, 256, 512.
 376
 377  To store the generated symmetric key in a keychain, set these keys:
 378  * kSecUseKeychain (value is a SecKeychainRef)
 379  * kSecAttrLabel (a user-visible label whose value is a CFStringRef,
 380  e.g. "My App's Encryption Key")
 381  * kSecAttrApplicationLabel (a label defined by your application, whose
 382  value is a CFDataRef and which can be used to find this key in a
 383  subsequent call to SecItemCopyMatching, e.g. "ID-1234567890-9876-0151")
 384
 385  To specify the generated key's access control settings, set this key:
 386  * kSecAttrAccess (value is a SecAccessRef)
 387
 388  The keys below may be optionally set in the parameters dictionary
 389  (with a CFBooleanRef value) to override the default usage values:
 390
 391  * kSecAttrCanEncrypt (defaults to true if not explicitly specified)
 392  * kSecAttrCanDecrypt (defaults to true if not explicitly specified)
 393  * kSecAttrCanWrap (defaults to true if not explicitly specified)
 394  * kSecAttrCanUnwrap (defaults to true if not explicitly specified)
 395
 396 */
 397 _Nullable
 398 SecKeyRef SecKeyGenerateSymmetric(CFDictionaryRef parameters, CFErrorRef *error)
 399         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 400
 401
 402 /*!
 403  @function SecKeyCreateFromData
 404  @abstract Creates a symmetric key with the given data and sets the
 405  algorithm type specified.
 406
 407  @param parameters A dictionary containing one or more key-value pairs.
 408  See the discussion sections below for a complete overview of options.
 409  @result On return, a SecKeyRef reference to the symmetric key.
 410
 411  @discussion In order to generate a symmetric key the parameters dictionary must
 412  at least contain the following keys:
 413
 414  * kSecAttrKeyType with a value of kSecAttrKeyTypeAES or any other
 415  kSecAttrKeyType defined in SecItem.h
 416
 417  The keys below may be optionally set in the parameters dictionary
 418  (with a CFBooleanRef value) to override the default usage values:
 419
 420  * kSecAttrCanEncrypt (defaults to true if not explicitly specified)
 421  * kSecAttrCanDecrypt (defaults to true if not explicitly specified)
 422  * kSecAttrCanWrap (defaults to true if not explicitly specified)
 423  * kSecAttrCanUnwrap (defaults to true if not explicitly specified)
 424
 425 */
 426 _Nullable
 427 SecKeyRef SecKeyCreateFromData(CFDictionaryRef parameters,
 428         CFDataRef keyData, CFErrorRef *error)
 429         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 430
 431
 432 /*!
 433  @function SecKeyGeneratePair
 434  @abstract Generate a private/public keypair.
 435  @param parameters A dictionary containing one or more key-value pairs.
 436  @result A result code. See "Security Error Codes" (SecBase.h). On success,
 437  the result code will be errSecSuccess, and the output parameters will
 438  contain the public SecKeyRef and private SecKeyRef. It is the caller's
 439  responsibility to CFRelease these key references when finished with them.
 440
 441  @discussion In order to generate a keypair the parameters dictionary must
 442  at least contain the following keys:
 443
 444  * kSecAttrKeyType with a value of kSecAttrKeyTypeRSA or any other
 445  kSecAttrKeyType defined in SecItem.h
 446  * kSecAttrKeySizeInBits with a value being a CFNumberRef containing
 447  the requested key size in bits.  Example sizes for RSA keys are:
 448  512, 768, 1024, 2048.
 449
 450  The values below may be set either in the top-level dictionary or in a
 451  dictionary that is the value of the kSecPrivateKeyAttrs or
 452  kSecPublicKeyAttrs key in the top-level dictionary.  Setting these
 453  attributes explicitly will override the defaults below.  See SecItem.h
 454  for detailed information on these attributes including the types of
 455  the values.
 456
 457  * kSecAttrLabel default NULL
 458  * kSecUseKeychain default NULL, which specifies the default keychain
 459  * kSecAttrApplicationTag default NULL
 460  * kSecAttrEffectiveKeySize default NULL same as kSecAttrKeySizeInBits
 461  * kSecAttrCanEncrypt default false for private keys, true for public keys
 462  * kSecAttrCanDecrypt default true for private keys, false for public keys
 463  * kSecAttrCanDerive default true
 464  * kSecAttrCanSign default true for private keys, false for public keys
 465  * kSecAttrCanVerify default false for private keys, true for public keys
 466  * kSecAttrCanWrap default false for private keys, true for public keys
 467  * kSecAttrCanUnwrap default true for private keys, false for public keys
 468
 469 */
 470 OSStatus SecKeyGeneratePair(CFDictionaryRef parameters,
 471         SecKeyRef * _Nullable CF_RETURNS_RETAINED publicKey, SecKeyRef * _Nullable CF_RETURNS_RETAINED privateKey)
 472         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
 473
 474 /*!
 475  @typedef SecKeyGeneratePairBlock
 476  @abstract Delivers the result from an asynchronous key pair generation.
 477  @param publicKey - the public key generated.   You must retain publicKey if you wish to use it after your block returns.
 478  @param privateKey - the private key generated.  You must retain publicKey if you wish to use it after your block returns.
 479  @param error - Any errors returned.   You must retain error if you wish to use it after your block returns.
 480  */
 481
 482 #ifdef __BLOCKS__
 483 typedef void (^SecKeyGeneratePairBlock)(SecKeyRef publicKey, SecKeyRef privateKey,  CFErrorRef error);
 484
 485
 486 /*!
 487  @function SecKeyGeneratePairAsync
 488  @abstract Generate a private/public keypair returning the values in a callback.
 489  @param parameters A dictionary containing one or more key-value pairs.
 490  @param deliveryQueue A dispatch queue to be used to deliver the results.
 491  @param result A callback function to result when the operation has completed.
 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 CF_RETURNS_RETAINED
 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 /*!
 606  @function SecKeyCreateRandomKey
 607  @abstract Generates a new public/private key pair.
 608  @param parameters A dictionary containing one or more key-value pairs.
 609         See the discussion sections below for a complete overview of options.
 610  @param error On error, will be populated with an error object describing the failure.
 611  See "Security Error Codes" (SecBase.h).
 612  @return Newly generated private key.  To get associated public key, use SecKeyCopyPublicKey().
 613  @discussion In order to generate a keypair the parameters dictionary must
 614         at least contain the following keys:
 615
 616  * kSecAttrKeyType with a value being kSecAttrKeyTypeRSA or any other
 617  kSecAttrKeyType defined in SecItem.h
 618  * kSecAttrKeySizeInBits with a value being a CFNumberRef or CFStringRef
 619  containing the requested key size in bits.  Example sizes for RSA
 620  keys are: 512, 768, 1024, 2048.
 621
 622  The values below may be set either in the top-level dictionary or in a
 623  dictionary that is the value of the kSecPrivateKeyAttrs or
 624  kSecPublicKeyAttrs key in the top-level dictionary.  Setting these
 625  attributes explicitly will override the defaults below.  See SecItem.h
 626  for detailed information on these attributes including the types of
 627  the values.
 628
 629  * kSecAttrLabel default NULL
 630  * kSecAttrIsPermanent if this key is present and has a Boolean value of true,
 631    the key or key pair will be added to the default keychain.
 632  * kSecAttrTokenID if this key should be generated on specified token.  This
 633    attribute can contain CFStringRef and can be present only in the top-level
 634    parameters dictionary.
 635  * kSecAttrApplicationTag default NULL
 636  * kSecAttrEffectiveKeySize default NULL same as kSecAttrKeySizeInBits
 637  * kSecAttrCanEncrypt default false for private keys, true for public keys
 638  * kSecAttrCanDecrypt default true for private keys, false for public keys
 639  * kSecAttrCanDerive default true
 640  * kSecAttrCanSign default true for private keys, false for public keys
 641  * kSecAttrCanVerify default false for private keys, true for public keys
 642  * kSecAttrCanWrap default false for private keys, true for public keys
 643  * kSecAttrCanUnwrap default true for private keys, false for public keys
 644  */
 645 SecKeyRef _Nullable SecKeyCreateRandomKey(CFDictionaryRef parameters, CFErrorRef *error)
 646 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 647
 648 /*!
 649         @function SecKeyCreateWithData
 650         @abstract Create a SecKey from a well-defined external representation.
 651         @param keyData CFData representing the key. The format of the data depends on the type of key being created.
 652         @param attributes Dictionary containing attributes describing the key to be imported. The keys in this dictionary
 653         are kSecAttr* constants from SecItem.h.  Mandatory attributes are:
 654          * kSecAttrKeyType
 655          * kSecAttrKeyClass
 656          * kSecAttrKeySizeInBits
 657         @param error On error, will be populated with an error object describing the failure.
 658         See "Security Error Codes" (SecBase.h).
 659         @result A SecKey object representing the key, or NULL on failure.
 660         @discussion This function does not add keys to any keychain, but the SecKey object it returns can be added
 661         to keychain using the SecItemAdd function.
 662         The requested data format depend on the type of key (kSecAttrKeyType) being created:
 663          * kSecAttrKeyTypeRSA               PKCS#1 format
 664          * kSecAttrKeyTypeECSECPrimeRandom  SEC1 format (www.secg.org)
 665  */
 666 SecKeyRef _Nullable SecKeyCreateWithData(CFDataRef keyData, CFDictionaryRef attributes, CFErrorRef *error)
 667 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 668
 669 /*!
 670         @function SecKeyCopyExternalRepresentation
 671         @abstract Create an external representation for the given key suitable for the key's type.
 672         @param key The key to be exported.
 673         @param error On error, will be populated with an error object describing the failure.
 674         See "Security Error Codes" (SecBase.h).
 675         @result A CFData representing the key in a format suitable for that key type.
 676         @discussion This function may fail if the key is not exportable (e.g., bound to a smart card or Secure Enclave).
 677         The format in which the key will be exported depends on the type of key:
 678         * kSecAttrKeyTypeRSA                 PKCS#1 format
 679         * kSecAttrKeyTypeECSECPrimeRandom    SEC1 format (www.secg.org)
 680  */
 681 CFDataRef _Nullable SecKeyCopyExternalRepresentation(SecKeyRef key, CFErrorRef *error)
 682 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 683
 684 /*!
 685         @function SecKeyCopyAttributes
 686         @abstract Retrieve keychain attributes of a key.
 687         @param key The key whose attributes are to be retrieved.
 688         @result Dictionary containing attributes of the key. The keys that populate this dictionary are defined
 689         and discussed in SecItem.h.
 690         @discussion The attributes provided by this function are:
 691         * kSecAttrCanEncrypt
 692         * kSecAttrCanDecrypt
 693         * kSecAttrCanDerive
 694         * kSecAttrCanSign
 695         * kSecAttrCanVerify
 696         * kSecAttrKeyClass
 697         * kSecAttrKeyType
 698         * kSecAttrKeySizeInBits
 699         * kSecAttrTokenID
 700         * kSecAttrApplicationLabel
 701         Other values returned in that dictionary are RFU.
 702  */
 703 CFDictionaryRef _Nullable SecKeyCopyAttributes(SecKeyRef key)
 704 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 705
 706 /*!
 707         @function SecKeyCopyPublicKey
 708         @abstract Retrieve the public key from a key pair or private key.
 709         @param key The key from which to retrieve a public key.
 710         @result The public key or NULL if public key is not available for specified key.
 711         @discussion Fails if key does not contain a public key or no public key can be computed from it.
 712  */
 713 SecKeyRef _Nullable SecKeyCopyPublicKey(SecKeyRef key)
 714 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 715
 716 /*!
 717         @enum SecKeyAlgorithm
 718         @abstract Available algorithms for performing cryptographic operations with SecKey object.  String representation
 719         of constant can be used for logging or debugging purposes, because they contain human readable names of the algorithm.
 720
 721         @constant kSecKeyAlgorithmRSASignatureRaw
 722         Raw RSA sign/verify operation, size of input data must be the same as value returned by SecKeyGetBlockSize().
 723
 724         @constant kSecKeyAlgorithmRSASignatureDigestPKCS1v15Raw
 725         RSA sign/verify operation, assumes that input data is digest and OID and digest algorithm as specified in PKCS# v1.5.
 726         This algorithm is typically not used directly, instead use algorithm with specified digest, like
 727         kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA256.
 728
 729         @constant kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA1
 730         RSA signature with PKCS#1 padding, input data must be SHA-1 generated digest.
 731
 732         @constant kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA224
 733         RSA signature with PKCS#1 padding, input data must be SHA-224 generated digest.
 734
 735         @constant kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA256
 736         RSA signature with PKCS#1 padding, input data must be SHA-256 generated digest.
 737
 738         @constant kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA384
 739         RSA signature with PKCS#1 padding, input data must be SHA-384 generated digest.
 740
 741         @constant kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA512
 742         RSA signature with PKCS#1 padding, input data must be SHA-512 generated digest.
 743
 744         @constant kSecKeyAlgorithmRSASignatureMessagePKCS1v15SHA1
 745         RSA signature with PKCS#1 padding, SHA-1 digest is generated from input data of any size.
 746
 747         @constant kSecKeyAlgorithmRSASignatureMessagePKCS1v15SHA224
 748         RSA signature with PKCS#1 padding, SHA-224 digest is generated from input data of any size.
 749
 750         @constant kSecKeyAlgorithmRSASignatureMessagePKCS1v15SHA256
 751         RSA signature with PKCS#1 padding, SHA-256 digest is generated from input data of any size.
 752
 753         @constant kSecKeyAlgorithmRSASignatureMessagePKCS1v15SHA384
 754         RSA signature with PKCS#1 padding, SHA-384 digest is generated from input data of any size.
 755
 756         @constant kSecKeyAlgorithmRSASignatureMessagePKCS1v15SHA512
 757         RSA signature with PKCS#1 padding, SHA-512 digest is generated from input data of any size.
 758
 759         @constant kSecKeyAlgorithmECDSASignatureRFC4754
 760         ECDSA algorithm, signature is concatenated r and s, big endian, data is message digest.
 761
 762         @constant kSecKeyAlgorithmECDSASignatureDigestX962
 763         ECDSA algorithm, signature is in DER x9.62 encoding, input data is message digest.
 764
 765         @constant kSecKeyAlgorithmECDSASignatureDigestX962SHA1
 766         ECDSA algorithm, signature is in DER x9.62 encoding, input data is message digest created by SHA1 algorithm.
 767
 768         @constant kSecKeyAlgorithmECDSASignatureDigestX962SHA1
 769         ECDSA algorithm, signature is in DER x9.62 encoding, input data is message digest created by SHA224 algorithm.
 770
 771         @constant kSecKeyAlgorithmECDSASignatureDigestX962SHA1
 772         ECDSA algorithm, signature is in DER x9.62 encoding, input data is message digest created by SHA256 algorithm.
 773
 774         @constant kSecKeyAlgorithmECDSASignatureDigestX962SHA1
 775         ECDSA algorithm, signature is in DER x9.62 encoding, input data is message digest created by SHA384 algorithm.
 776
 777         @constant kSecKeyAlgorithmECDSASignatureDigestX962SHA1
 778         ECDSA algorithm, signature is in DER x9.62 encoding, input data is message digest created by SHA512 algorithm.
 779
 780         @constant kSecKeyAlgorithmECDSASignatureMessageX962SHA1
 781         ECDSA algorithm, signature is in DER x9.62 encoding, SHA-1 digest is generated from input data of any size.
 782
 783         @constant kSecKeyAlgorithmECDSASignatureMessageX962SHA224
 784         ECDSA algorithm, signature is in DER x9.62 encoding, SHA-224 digest is generated from input data of any size.
 785
 786         @constant kSecKeyAlgorithmECDSASignatureMessageX962SHA256
 787         ECDSA algorithm, signature is in DER x9.62 encoding, SHA-256 digest is generated from input data of any size.
 788
 789         @constant kSecKeyAlgorithmECDSASignatureMessageX962SHA384
 790         ECDSA algorithm, signature is in DER x9.62 encoding, SHA-384 digest is generated from input data of any size.
 791
 792         @constant kSecKeyAlgorithmECDSASignatureMessageX962SHA512
 793         ECDSA algorithm, signature is in DER x9.62 encoding, SHA-512 digest is generated from input data of any size.
 794
 795         @constant kSecKeyAlgorithmRSAEncryptionRaw
 796         Raw RSA encryption or decryption, size of data must match RSA key modulus size.  Note that direct
 797         use of this algorithm without padding is cryptographically very weak, it is important to always introduce
 798         some kind of padding.  Input data size must be less or equal to the key block size and returned block has always
 799         the same size as block size, as returned by SecKeyGetBlockSize().
 800
 801         @constant kSecKeyAlgorithmRSAEncryptionPKCS1
 802         RSA encryption or decryption, data is padded using PKCS#1 padding scheme.  This algorithm should be used only for
 803         backward compatibility with existing protocols and data. New implementations should choose cryptographically
 804         stronger algorithm instead (see kSecKeyAlgorithmRSAEncryptionOAEP).  Input data must be at most
 805         "key block size - 11" bytes long and returned block has always the same size as block size, as returned
 806         by SecKeyGetBlockSize().
 807
 808         @constant kSecKeyAlgorithmRSAEncryptionOAEPSHA1
 809         RSA encryption or decryption, data is padded using OAEP padding scheme internally using SHA1. Input data must be at most
 810         "key block size - 42" bytes long and returned block has always the same size as block size, as returned
 811         by SecKeyGetBlockSize().  Use kSecKeyAlgorithmRSAEncryptionOAEPSHA1AESGCM to be able to encrypt and decrypt arbitrary long data.
 812
 813         @constant kSecKeyAlgorithmRSAEncryptionOAEPSHA224
 814         RSA encryption or decryption, data is padded using OAEP padding scheme internally using SHA224. Input data must be at most
 815         "key block size - 58" bytes long and returned block has always the same size as block size, as returned
 816         by SecKeyGetBlockSize().  Use kSecKeyAlgorithmRSAEncryptionOAEPSHA224AESGCM to be able to encrypt and decrypt arbitrary long data.
 817
 818         @constant kSecKeyAlgorithmRSAEncryptionOAEPSHA256
 819         RSA encryption or decryption, data is padded using OAEP padding scheme internally using SHA256. Input data must be at most
 820         "key block size - 66" bytes long and returned block has always the same size as block size, as returned
 821         by SecKeyGetBlockSize().  Use kSecKeyAlgorithmRSAEncryptionOAEPSHA256AESGCM to be able to encrypt and decrypt arbitrary long data.
 822
 823         @constant kSecKeyAlgorithmRSAEncryptionOAEPSHA384
 824         RSA encryption or decryption, data is padded using OAEP padding scheme internally using SHA384. Input data must be at most
 825         "key block size - 98" bytes long and returned block has always the same size as block size, as returned
 826         by SecKeyGetBlockSize().  Use kSecKeyAlgorithmRSAEncryptionOAEPSHA384AESGCM to be able to encrypt and decrypt arbitrary long data.
 827
 828         @constant kSecKeyAlgorithmRSAEncryptionOAEPSHA512
 829         RSA encryption or decryption, data is padded using OAEP padding scheme internally using SHA512. Input data must be at most
 830         "key block size - 130" bytes long and returned block has always the same size as block size, as returned
 831         by SecKeyGetBlockSize().  Use kSecKeyAlgorithmRSAEncryptionOAEPSHA512AESGCM to be able to encrypt and decrypt arbitrary long data.
 832
 833         @constant kSecKeyAlgorithmRSAEncryptionOAEPSHA1AESGCM
 834         Randomly generated AES session key is encrypted by RSA with OAEP padding.  User data are encrypted using session key in GCM
 835         mode with all-zero 16 bytes long IV (initialization vector).  Finally 16 byte AES-GCM tag is appended to ciphertext.
 836         256bit AES key is used if RSA key is 4096bit or bigger, otherwise 128bit AES key is used.  Raw public key data is used
 837         as authentication data for AES-GCM encryption.
 838
 839         @constant kSecKeyAlgorithmRSAEncryptionOAEPSHA224AESGCM
 840         Randomly generated AES session key is encrypted by RSA with OAEP padding.  User data are encrypted using session key in GCM
 841         mode with all-zero 16 bytes long IV (initialization vector).  Finally 16 byte AES-GCM tag is appended to ciphertext.
 842         256bit AES key is used if RSA key is 4096bit or bigger, otherwise 128bit AES key is used.  Raw public key data is used
 843         as authentication data for AES-GCM encryption.
 844
 845         @constant kSecKeyAlgorithmRSAEncryptionOAEPSHA256AESGCM
 846         Randomly generated AES session key is encrypted by RSA with OAEP padding.  User data are encrypted using session key in GCM
 847         mode with all-zero 16 bytes long IV (initialization vector).  Finally 16 byte AES-GCM tag is appended to ciphertext.
 848         256bit AES key is used if RSA key is 4096bit or bigger, otherwise 128bit AES key is used.  Raw public key data is used
 849         as authentication data for AES-GCM encryption.
 850
 851         @constant kSecKeyAlgorithmRSAEncryptionOAEPSHA384AESGCM
 852         Randomly generated AES session key is encrypted by RSA with OAEP padding.  User data are encrypted using session key in GCM
 853         mode with all-zero 16 bytes long IV (initialization vector).  Finally 16 byte AES-GCM tag is appended to ciphertext.
 854         256bit AES key is used if RSA key is 4096bit or bigger, otherwise 128bit AES key is used.  Raw public key data is used
 855         as authentication data for AES-GCM encryption.
 856
 857         @constant kSecKeyAlgorithmRSAEncryptionOAEPSHA512AESGCM
 858         Randomly generated AES session key is encrypted by RSA with OAEP padding.  User data are encrypted using session key in GCM
 859         mode with all-zero 16 bytes long IV (initialization vector).  Finally 16 byte AES-GCM tag is appended to ciphertext.
 860         256bit AES key is used if RSA key is 4096bit or bigger, otherwise 128bit AES key is used.  Raw public key data is used
 861         as authentication data for AES-GCM encryption.
 862
 863         @constant kSecKeyAlgorithmECIESEncryptionStandardX963SHA1AESGCM
 864         ECIES encryption or decryption.  This algorithm does not limit the size of the message to be encrypted or decrypted.
 865         Encryption is done using AES-GCM with key negotiated by kSecKeyAlgorithmECDHKeyExchangeStandardX963SHA1.  AES Key size
 866         is 128bit for EC keys <=256bit and 256bit for bigger EC keys.  Ephemeral public key data is used as sharedInfo for KDF,
 867         and static public key data is used as authenticationData for AES-GCM processing.  AES-GCM uses 16 bytes long TAG and
 868         all-zero 16 byte long IV (initialization vector).
 869
 870         @constant kSecKeyAlgorithmECIESEncryptionStandardX963SHA224AESGCM
 871         ECIES encryption or decryption.  This algorithm does not limit the size of the message to be encrypted or decrypted.
 872         Encryption is done using AES-GCM with key negotiated by kSecKeyAlgorithmECDHKeyExchangeStandardX963SHA1.  AES Key size
 873         is 128bit for EC keys <=256bit and 256bit for bigger EC keys.  Ephemeral public key data is used as sharedInfo for KDF,
 874         and static public key data is used as authenticationData for AES-GCM processing.  AES-GCM uses 16 bytes long TAG and
 875         all-zero 16 byte long IV (initialization vector).
 876
 877         @constant kSecKeyAlgorithmECIESEncryptionStandardX963SHA256AESGCM
 878         ECIES encryption or decryption.  This algorithm does not limit the size of the message to be encrypted or decrypted.
 879         Encryption is done using AES-GCM with key negotiated by kSecKeyAlgorithmECDHKeyExchangeStandardX963SHA1.  AES Key size
 880         is 128bit for EC keys <=256bit and 256bit for bigger EC keys.  Ephemeral public key data is used as sharedInfo for KDF,
 881         and static public key data is used as authenticationData for AES-GCM processing.  AES-GCM uses 16 bytes long TAG and
 882         all-zero 16 byte long IV (initialization vector).
 883
 884         @constant kSecKeyAlgorithmECIESEncryptionStandardX963SHA384AESGCM
 885         ECIES encryption or decryption.  This algorithm does not limit the size of the message to be encrypted or decrypted.
 886         Encryption is done using AES-GCM with key negotiated by kSecKeyAlgorithmECDHKeyExchangeStandardX963SHA1.  AES Key size
 887         is 128bit for EC keys <=256bit and 256bit for bigger EC keys.  Ephemeral public key data is used as sharedInfo for KDF,
 888         and static public key data is used as authenticationData for AES-GCM processing.  AES-GCM uses 16 bytes long TAG and
 889         all-zero 16 byte long IV (initialization vector).
 890
 891         @constant kSecKeyAlgorithmECIESEncryptionStandardX963SHA512AESGCM
 892         ECIES encryption or decryption.  This algorithm does not limit the size of the message to be encrypted or decrypted.
 893         Encryption is done using AES-GCM with key negotiated by kSecKeyAlgorithmECDHKeyExchangeStandardX963SHA1.  AES Key size
 894         is 128bit for EC keys <=256bit and 256bit for bigger EC keys.  Ephemeral public key data is used as sharedInfo for KDF,
 895         and static public key data is used as authenticationData for AES-GCM processing.  AES-GCM uses 16 bytes long TAG and
 896         all-zero 16 byte long IV (initialization vector).
 897
 898         @constant kSecKeyAlgorithmECIESEncryptionCofactorX963SHA1AESGCM
 899         ECIES encryption or decryption.  This algorithm does not limit the size of the message to be encrypted or decrypted.
 900         Encryption is done using AES-GCM with key negotiated by kSecKeyAlgorithmECDHKeyExchangeCofactorX963SHA1.  AES Key size
 901         is 128bit for EC keys <=256bit and 256bit for bigger EC keys.  Ephemeral public key data is used as sharedInfo for KDF,
 902         and static public key data is used as authenticationData for AES-GCM processing.  AES-GCM uses 16 bytes long TAG and
 903         all-zero 16 byte long IV (initialization vector).
 904
 905         @constant kSecKeyAlgorithmECIESEncryptionCofactorX963SHA224AESGCM
 906         ECIES encryption or decryption.  This algorithm does not limit the size of the message to be encrypted or decrypted.
 907         Encryption is done using AES-GCM with key negotiated by kSecKeyAlgorithmECDHKeyExchangeCofactorX963SHA1.  AES Key size
 908         is 128bit for EC keys <=256bit and 256bit for bigger EC keys.  Ephemeral public key data is used as sharedInfo for KDF,
 909         and static public key data is used as authenticationData for AES-GCM processing.  AES-GCM uses 16 bytes long TAG and
 910         all-zero 16 byte long IV (initialization vector).
 911
 912         @constant kSecKeyAlgorithmECIESEncryptionCofactorX963SHA256AESGCM
 913         ECIES encryption or decryption.  This algorithm does not limit the size of the message to be encrypted or decrypted.
 914         Encryption is done using AES-GCM with key negotiated by kSecKeyAlgorithmECDHKeyExchangeCofactorX963SHA1.  AES Key size
 915         is 128bit for EC keys <=256bit and 256bit for bigger EC keys.  Ephemeral public key data is used as sharedInfo for KDF,
 916         and static public key data is used as authenticationData for AES-GCM processing.  AES-GCM uses 16 bytes long TAG and
 917         all-zero 16 byte long IV (initialization vector).
 918
 919         @constant kSecKeyAlgorithmECIESEncryptionCofactorX963SHA384AESGCM
 920         ECIES encryption or decryption.  This algorithm does not limit the size of the message to be encrypted or decrypted.
 921         Encryption is done using AES-GCM with key negotiated by kSecKeyAlgorithmECDHKeyExchangeCofactorX963SHA1.  AES Key size
 922         is 128bit for EC keys <=256bit and 256bit for bigger EC keys.  Ephemeral public key data is used as sharedInfo for KDF,
 923         and static public key data is used as authenticationData for AES-GCM processing.  AES-GCM uses 16 bytes long TAG and
 924         all-zero 16 byte long IV (initialization vector).
 925
 926         @constant kSecKeyAlgorithmECIESEncryptionCofactorX963SHA512AESGCM
 927         ECIES encryption or decryption.  This algorithm does not limit the size of the message to be encrypted or decrypted.
 928         Encryption is done using AES-GCM with key negotiated by kSecKeyAlgorithmECDHKeyExchangeCofactorX963SHA1.  AES Key size
 929         is 128bit for EC keys <=256bit and 256bit for bigger EC keys.  Ephemeral public key data is used as sharedInfo for KDF,
 930         and static public key data is used as authenticationData for AES-GCM processing.  AES-GCM uses 16 bytes long TAG and
 931         all-zero 16 byte long IV (initialization vector).
 932
 933         @constant kSecKeyAlgorithmECDHKeyExchangeCofactor
 934         Compute shared secret using ECDH cofactor algorithm, suitable only for kSecAttrKeyTypeECSECPrimeRandom keys.
 935         This algorithm does not accept any parameters, length of output raw shared secret is given by the length of the key.
 936
 937         @constant kSecKeyAlgorithmECDHKeyExchangeCofactorX963SHA1
 938         Compute shared secret using ECDH cofactor algorithm, suitable only for kSecAttrKeyTypeECSECPrimeRandom keys
 939         and apply ANSI X9.63 KDF with SHA1 as hashing function.  Requires kSecKeyKeyExchangeParameterRequestedSize and allows
 940         kSecKeyKeyExchangeParameterSharedInfo parameters to be used.
 941
 942         @constant kSecKeyAlgorithmECDHKeyExchangeCofactorX963SHA224
 943         Compute shared secret using ECDH cofactor algorithm, suitable only for kSecAttrKeyTypeECSECPrimeRandom keys
 944         and apply ANSI X9.63 KDF with SHA224 as hashing function.  Requires kSecKeyKeyExchangeParameterRequestedSize and allows
 945         kSecKeyKeyExchangeParameterSharedInfo parameters to be used.
 946
 947         @constant kSecKeyAlgorithmECDHKeyExchangeCofactorX963SHA256
 948         Compute shared secret using ECDH cofactor algorithm, suitable only for kSecAttrKeyTypeECSECPrimeRandom keys
 949         and apply ANSI X9.63 KDF with SHA256 as hashing function.  Requires kSecKeyKeyExchangeParameterRequestedSize and allows
 950         kSecKeyKeyExchangeParameterSharedInfo parameters to be used.
 951
 952         @constant kSecKeyAlgorithmECDHKeyExchangeCofactorX963SHA384
 953         Compute shared secret using ECDH cofactor algorithm, suitable only for kSecAttrKeyTypeECSECPrimeRandom keys
 954         and apply ANSI X9.63 KDF with SHA384 as hashing function.  Requires kSecKeyKeyExchangeParameterRequestedSize and allows
 955         kSecKeyKeyExchangeParameterSharedInfo parameters to be used.
 956
 957         @constant kSecKeyAlgorithmECDHKeyExchangeCofactorX963SHA512
 958         Compute shared secret using ECDH cofactor algorithm, suitable only for kSecAttrKeyTypeECSECPrimeRandom keys
 959         and apply ANSI X9.63 KDF with SHA512 as hashing function.  Requires kSecKeyKeyExchangeParameterRequestedSize and allows
 960         kSecKeyKeyExchangeParameterSharedInfo parameters to be used.
 961
 962         @constant kSecKeyAlgorithmECDHKeyExchangeStandard
 963         Compute shared secret using ECDH algorithm without cofactor, suitable only for kSecAttrKeyTypeECSECPrimeRandom keys.
 964         This algorithm does not accept any parameters, length of output raw shared secret is given by the length of the key.
 965
 966         @constant kSecKeyAlgorithmECDHKeyExchangeStandardX963SHA1
 967         Compute shared secret using ECDH algorithm without cofactor, suitable only for kSecAttrKeyTypeECSECPrimeRandom keys
 968         and apply ANSI X9.63 KDF with SHA1 as hashing function.  Requires kSecKeyKeyExchangeParameterRequestedSize and allows
 969         kSecKeyKeyExchangeParameterSharedInfo parameters to be used.
 970
 971         @constant kSecKeyAlgorithmECDHKeyExchangeStandardX963SHA224
 972         Compute shared secret using ECDH algorithm without cofactor, suitable only for kSecAttrKeyTypeECSECPrimeRandom keys
 973         and apply ANSI X9.63 KDF with SHA224 as hashing function.  Requires kSecKeyKeyExchangeParameterRequestedSize and allows
 974         kSecKeyKeyExchangeParameterSharedInfo parameters to be used.
 975
 976         @constant kSecKeyAlgorithmECDHKeyExchangeStandardX963SHA256
 977         Compute shared secret using ECDH algorithm without cofactor, suitable only for kSecAttrKeyTypeECSECPrimeRandom keys
 978         and apply ANSI X9.63 KDF with SHA256 as hashing function.  Requires kSecKeyKeyExchangeParameterRequestedSize and allows
 979         kSecKeyKeyExchangeParameterSharedInfo parameters to be used.
 980
 981         @constant kSecKeyAlgorithmECDHKeyExchangeStandardX963SHA384
 982         Compute shared secret using ECDH algorithm without cofactor, suitable only for kSecAttrKeyTypeECSECPrimeRandom keys
 983         and apply ANSI X9.63 KDF with SHA384 as hashing function.  Requires kSecKeyKeyExchangeParameterRequestedSize and allows
 984         kSecKeyKeyExchangeParameterSharedInfo parameters to be used.
 985
 986         @constant kSecKeyAlgorithmECDHKeyExchangeStandardX963SHA512
 987         Compute shared secret using ECDH algorithm without cofactor, suitable only for kSecAttrKeyTypeECSECPrimeRandom keys
 988         and apply ANSI X9.63 KDF with SHA512 as hashing function.  Requires kSecKeyKeyExchangeParameterRequestedSize and allows
 989         kSecKeyKeyExchangeParameterSharedInfo parameters to be used.
 990   */
 991
 992 typedef CFStringRef SecKeyAlgorithm CF_STRING_ENUM
 993 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 994
 995 extern const SecKeyAlgorithm kSecKeyAlgorithmRSASignatureRaw
 996 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 997
 998 extern const SecKeyAlgorithm kSecKeyAlgorithmRSASignatureDigestPKCS1v15Raw
 999 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1000
1001 extern const SecKeyAlgorithm kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA1
1002 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1003 extern const SecKeyAlgorithm kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA224
1004 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1005 extern const SecKeyAlgorithm kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA256
1006 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1007 extern const SecKeyAlgorithm kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA384
1008 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1009 extern const SecKeyAlgorithm kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA512
1010 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1011
1012 extern const SecKeyAlgorithm kSecKeyAlgorithmRSASignatureMessagePKCS1v15SHA1
1013 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1014 extern const SecKeyAlgorithm kSecKeyAlgorithmRSASignatureMessagePKCS1v15SHA224
1015 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1016 extern const SecKeyAlgorithm kSecKeyAlgorithmRSASignatureMessagePKCS1v15SHA256
1017 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1018 extern const SecKeyAlgorithm kSecKeyAlgorithmRSASignatureMessagePKCS1v15SHA384
1019 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1020 extern const SecKeyAlgorithm kSecKeyAlgorithmRSASignatureMessagePKCS1v15SHA512
1021 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1022
1023 extern const SecKeyAlgorithm kSecKeyAlgorithmECDSASignatureRFC4754
1024 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1025
1026 extern const SecKeyAlgorithm kSecKeyAlgorithmECDSASignatureDigestX962
1027 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1028 extern const SecKeyAlgorithm kSecKeyAlgorithmECDSASignatureDigestX962SHA1
1029 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1030 extern const SecKeyAlgorithm kSecKeyAlgorithmECDSASignatureDigestX962SHA224
1031 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1032 extern const SecKeyAlgorithm kSecKeyAlgorithmECDSASignatureDigestX962SHA256
1033 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1034 extern const SecKeyAlgorithm kSecKeyAlgorithmECDSASignatureDigestX962SHA384
1035 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1036 extern const SecKeyAlgorithm kSecKeyAlgorithmECDSASignatureDigestX962SHA512
1037 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1038
1039 extern const SecKeyAlgorithm kSecKeyAlgorithmECDSASignatureMessageX962SHA1
1040 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1041 extern const SecKeyAlgorithm kSecKeyAlgorithmECDSASignatureMessageX962SHA224
1042 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1043 extern const SecKeyAlgorithm kSecKeyAlgorithmECDSASignatureMessageX962SHA256
1044 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1045 extern const SecKeyAlgorithm kSecKeyAlgorithmECDSASignatureMessageX962SHA384
1046 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1047 extern const SecKeyAlgorithm kSecKeyAlgorithmECDSASignatureMessageX962SHA512
1048 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1049
1050 extern const SecKeyAlgorithm kSecKeyAlgorithmRSAEncryptionRaw
1051 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1052 extern const SecKeyAlgorithm kSecKeyAlgorithmRSAEncryptionPKCS1
1053 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1054 extern const SecKeyAlgorithm kSecKeyAlgorithmRSAEncryptionOAEPSHA1
1055 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1056 extern const SecKeyAlgorithm kSecKeyAlgorithmRSAEncryptionOAEPSHA224
1057 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1058 extern const SecKeyAlgorithm kSecKeyAlgorithmRSAEncryptionOAEPSHA256
1059 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1060 extern const SecKeyAlgorithm kSecKeyAlgorithmRSAEncryptionOAEPSHA384
1061 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1062 extern const SecKeyAlgorithm kSecKeyAlgorithmRSAEncryptionOAEPSHA512
1063 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1064
1065 extern const SecKeyAlgorithm kSecKeyAlgorithmRSAEncryptionOAEPSHA1AESGCM
1066 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1067 extern const SecKeyAlgorithm kSecKeyAlgorithmRSAEncryptionOAEPSHA224AESGCM
1068 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1069 extern const SecKeyAlgorithm kSecKeyAlgorithmRSAEncryptionOAEPSHA256AESGCM
1070 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1071 extern const SecKeyAlgorithm kSecKeyAlgorithmRSAEncryptionOAEPSHA384AESGCM
1072 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1073 extern const SecKeyAlgorithm kSecKeyAlgorithmRSAEncryptionOAEPSHA512AESGCM
1074 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1075
1076 extern const SecKeyAlgorithm kSecKeyAlgorithmECIESEncryptionStandardX963SHA1AESGCM
1077 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1078 extern const SecKeyAlgorithm kSecKeyAlgorithmECIESEncryptionStandardX963SHA224AESGCM
1079 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1080 extern const SecKeyAlgorithm kSecKeyAlgorithmECIESEncryptionStandardX963SHA256AESGCM
1081 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1082 extern const SecKeyAlgorithm kSecKeyAlgorithmECIESEncryptionStandardX963SHA384AESGCM
1083 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1084 extern const SecKeyAlgorithm kSecKeyAlgorithmECIESEncryptionStandardX963SHA512AESGCM
1085 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1086
1087 extern const SecKeyAlgorithm kSecKeyAlgorithmECIESEncryptionCofactorX963SHA1AESGCM
1088 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1089 extern const SecKeyAlgorithm kSecKeyAlgorithmECIESEncryptionCofactorX963SHA224AESGCM
1090 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1091 extern const SecKeyAlgorithm kSecKeyAlgorithmECIESEncryptionCofactorX963SHA256AESGCM
1092 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1093 extern const SecKeyAlgorithm kSecKeyAlgorithmECIESEncryptionCofactorX963SHA384AESGCM
1094 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1095 extern const SecKeyAlgorithm kSecKeyAlgorithmECIESEncryptionCofactorX963SHA512AESGCM
1096 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1097
1098 extern const SecKeyAlgorithm kSecKeyAlgorithmECDHKeyExchangeStandard
1099 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1100 extern const SecKeyAlgorithm kSecKeyAlgorithmECDHKeyExchangeStandardX963SHA1
1101 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1102 extern const SecKeyAlgorithm kSecKeyAlgorithmECDHKeyExchangeStandardX963SHA224
1103 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1104 extern const SecKeyAlgorithm kSecKeyAlgorithmECDHKeyExchangeStandardX963SHA256
1105 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1106 extern const SecKeyAlgorithm kSecKeyAlgorithmECDHKeyExchangeStandardX963SHA384
1107 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1108 extern const SecKeyAlgorithm kSecKeyAlgorithmECDHKeyExchangeStandardX963SHA512
1109 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1110
1111 extern const SecKeyAlgorithm kSecKeyAlgorithmECDHKeyExchangeCofactor
1112 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1113 extern const SecKeyAlgorithm kSecKeyAlgorithmECDHKeyExchangeCofactorX963SHA1
1114 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1115 extern const SecKeyAlgorithm kSecKeyAlgorithmECDHKeyExchangeCofactorX963SHA224
1116 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1117 extern const SecKeyAlgorithm kSecKeyAlgorithmECDHKeyExchangeCofactorX963SHA256
1118 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1119 extern const SecKeyAlgorithm kSecKeyAlgorithmECDHKeyExchangeCofactorX963SHA384
1120 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1121 extern const SecKeyAlgorithm kSecKeyAlgorithmECDHKeyExchangeCofactorX963SHA512
1122 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1123
1124 /*!
1125         @function SecKeyCreateSignature
1126         @abstract Given a private key and data to sign, generate a digital signature.
1127         @param key Private key with which to sign.
1128         @param algorithm One of SecKeyAlgorithm constants suitable to generate signature with this key.
1129         @param dataToSign The data to be signed, typically the digest of the actual data.
1130         @param error On error, will be populated with an error object describing the failure.
1131         See "Security Error Codes" (SecBase.h).
1132         @result The signature over dataToSign represented as a CFData, or NULL on failure.
1133         @discussion Computes digital signature using specified key over input data.  The operation algorithm
1134         further defines the exact format of input data, operation to be performed and output signature.
1135  */
1136 CFDataRef _Nullable SecKeyCreateSignature(SecKeyRef key, SecKeyAlgorithm algorithm, CFDataRef dataToSign, CFErrorRef *error)
1137 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1138
1139 /*!
1140         @function SecKeyVerifySignature
1141         @abstract Given a public key, data which has been signed, and a signature, verify the signature.
1142         @param key Public key with which to verify the signature.
1143         @param algorithm One of SecKeyAlgorithm constants suitable to verify signature with this key.
1144         @param signedData The data over which sig is being verified, typically the digest of the actual data.
1145         @param signature The signature to verify.
1146         @param error On error, will be populated with an error object describing the failure.
1147         See "Security Error Codes" (SecBase.h).
1148         @result True if the signature was valid, False otherwise.
1149         @discussion Verifies digital signature operation using specified key and signed data.  The operation algorithm
1150         further defines the exact format of input data, signature and operation to be performed.
1151  */
1152 Boolean SecKeyVerifySignature(SecKeyRef key, SecKeyAlgorithm algorithm, CFDataRef signedData, CFDataRef signature, CFErrorRef *error)
1153 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1154
1155 /*!
1156         @function SecKeyCreateEncryptedData
1157         @abstract Encrypt a block of plaintext.
1158         @param key Public key with which to encrypt the data.
1159         @param algorithm One of SecKeyAlgorithm constants suitable to perform encryption with this key.
1160         @param plaintext The data to encrypt. The length and format of the data must conform to chosen algorithm,
1161         typically be less or equal to the value returned by SecKeyGetBlockSize().
1162         @param error On error, will be populated with an error object describing the failure.
1163         See "Security Error Codes" (SecBase.h).
1164         @result The ciphertext represented as a CFData, or NULL on failure.
1165         @discussion Encrypts plaintext data using specified key.  The exact type of the operation including the format
1166         of input and output data is specified by encryption algorithm.
1167  */
1168 CFDataRef _Nullable SecKeyCreateEncryptedData(SecKeyRef key, SecKeyAlgorithm algorithm, CFDataRef plaintext,
1169                                                CFErrorRef *error)
1170 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1171
1172 /*!
1173         @function SecKeyCreateDecryptedData
1174         @abstract Decrypt a block of ciphertext.
1175         @param key Private key with which to decrypt the data.
1176         @param algorithm One of SecKeyAlgorithm constants suitable to perform decryption with this key.
1177         @param ciphertext The data to decrypt. The length and format of the data must conform to chosen algorithm,
1178         typically be less or equal to the value returned by SecKeyGetBlockSize().
1179         @param error On error, will be populated with an error object describing the failure.
1180         See "Security Error Codes" (SecBase.h).
1181         @result The plaintext represented as a CFData, or NULL on failure.
1182         @discussion Decrypts ciphertext data using specified key.  The exact type of the operation including the format
1183         of input and output data is specified by decryption algorithm.
1184  */
1185 CFDataRef _Nullable SecKeyCreateDecryptedData(SecKeyRef key, SecKeyAlgorithm algorithm, CFDataRef ciphertext,
1186                                                CFErrorRef *error)
1187 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1188
1189 /*!
1190         @enum SecKeyKeyExchangeParameter SecKey Key Exchange parameters
1191         @constant kSecKeyKeyExchangeParameterRequestedSize Contains CFNumberRef with requested result size in bytes.
1192         @constant kSecKeyKeyExchangeParameterSharedInfo Contains CFDataRef with additional shared info
1193         for KDF (key derivation function).
1194  */
1195 typedef CFStringRef SecKeyKeyExchangeParameter CF_STRING_ENUM
1196 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1197 extern const SecKeyKeyExchangeParameter kSecKeyKeyExchangeParameterRequestedSize
1198 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1199 extern const SecKeyKeyExchangeParameter kSecKeyKeyExchangeParameterSharedInfo
1200 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1201
1202 /*!
1203         @function SecKeyCopyKeyExchangeResult
1204         @abstract Perform Diffie-Hellman style of key exchange operation, optionally with additional key-derivation steps.
1205         @param algorithm One of SecKeyAlgorithm constants suitable to perform this operation.
1206         @param publicKey Remote party's public key.
1207         @param parameters Dictionary with parameters, see SecKeyKeyExchangeParameter constants.  Used algorithm
1208         determines the set of required and optional parameters to be used.
1209         @param error Pointer to an error object on failure.
1210         See "Security Error Codes" (SecBase.h).
1211         @result Result of key exchange operation as a CFDataRef, or NULL on failure.
1212  */
1213 CFDataRef _Nullable SecKeyCopyKeyExchangeResult(SecKeyRef privateKey, SecKeyAlgorithm algorithm, SecKeyRef publicKey, CFDictionaryRef parameters, CFErrorRef *error)
1214 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1215
1216 /*!
1217         @enum SecKeyOperationType
1218         @abstract Defines types of cryptographic operations available with SecKey instance.
1219
1220         @constant kSecKeyOperationTypeSign
1221         Represents SecKeyCreateSignature()
1222
1223         @constant kSecKeyOperationTypeVerify
1224         Represents SecKeyVerifySignature()
1225
1226         @constant kSecKeyOperationTypeEncrypt
1227         Represents SecKeyCreateEncryptedData()
1228
1229         @constant kSecKeyOperationTypeDecrypt
1230         Represents SecKeyCreateDecryptedData()
1231
1232         @constant kSecKeyOperationTypeKeyExchange
1233         Represents SecKeyCopyKeyExchangeResult()
1234  */
1235 typedef CF_ENUM(CFIndex, SecKeyOperationType) {
1236     kSecKeyOperationTypeSign        = 0,
1237     kSecKeyOperationTypeVerify      = 1,
1238     kSecKeyOperationTypeEncrypt     = 2,
1239     kSecKeyOperationTypeDecrypt     = 3,
1240     kSecKeyOperationTypeKeyExchange = 4,
1241 } __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1242
1243 /*!
1244         @function SecKeyIsAlgorithmSupported
1245         @abstract Checks whether key supports specified algorithm for specified operation.
1246         @param key Key to query
1247         @param operation Operation type for which the key is queried
1248         @param algorithm Algorithm which is queried
1249         @return True if key supports specified algorithm for specified operation, False otherwise.
1250  */
1251 Boolean SecKeyIsAlgorithmSupported(SecKeyRef key, SecKeyOperationType operation, SecKeyAlgorithm algorithm)
1252 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
1253
1254 CF_IMPLICIT_BRIDGING_DISABLED
1255 CF_ASSUME_NONNULL_END
1256
1257 #if defined(__cplusplus)
1258 }
1259 #endif
1260
1261 #endif /* !_SECURITY_SECKEY_H_ */