OSX/sec/Security/SecItem.h

   1 /*
   2  * Copyright (c) 2006-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 SecItem
  26     SecItem defines CoreFoundation-based constants and functions for
  27     access to Security items (certificates, keys, identities, and
  28     passwords.)
  29 */
  30
  31 #ifndef _SECURITY_SECITEM_H_
  32 #define _SECURITY_SECITEM_H_
  33
  34 #include <Security/SecBase.h>
  35 #include <CoreFoundation/CFArray.h>
  36 #include <CoreFoundation/CFDictionary.h>
  37
  38 __BEGIN_DECLS
  39
  40 CF_ASSUME_NONNULL_BEGIN
  41 CF_IMPLICIT_BRIDGING_ENABLED
  42
  43 /*!
  44     @enum Class Key Constant
  45     @discussion Predefined key constant used to get or set item class values in
  46         a dictionary. Its value is one of the constants defined in the Value
  47         Constants for kSecClass.
  48     @constant kSecClass Specifies a dictionary key whose value is the item's
  49         class code.  You use this key to get or set a value of type CFTypeRef
  50         that contains the item class code.
  51 */
  52 extern const CFStringRef kSecClass
  53     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
  54
  55 /*!
  56     @enum Class Value Constants
  57     @discussion Predefined item class constants used to get or set values in
  58         a dictionary. The kSecClass constant is the key and its value is one
  59         of the constants defined here.
  60     @constant kSecClassGenericPassword Specifies generic password items.
  61     @constant kSecClassInternetPassword Specifies Internet password items.
  62     @constant kSecClassCertificate Specifies certificate items.
  63     @constant kSecClassKey Specifies key items.
  64     @constant kSecClassIdentity Specifies identity items.
  65 */
  66 extern const CFStringRef kSecClassGenericPassword
  67     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
  68 extern const CFStringRef kSecClassInternetPassword
  69     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
  70 extern const CFStringRef kSecClassCertificate
  71     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
  72 extern const CFStringRef kSecClassKey
  73     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
  74 extern const CFStringRef kSecClassIdentity
  75     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
  76
  77
  78 /*!
  79     @enum Attribute Key Constants
  80     @discussion Predefined item attribute keys used to get or set values in a
  81         dictionary. Not all attributes apply to each item class. The table
  82         below lists the currently defined attributes for each item class:
  83
  84     kSecClassGenericPassword item attributes:
  85         kSecAttrAccessible
  86         kSecAttrAccessControl
  87         kSecAttrAccessGroup
  88         kSecAttrCreationDate
  89         kSecAttrModificationDate
  90         kSecAttrDescription
  91         kSecAttrComment
  92         kSecAttrCreator
  93         kSecAttrType
  94         kSecAttrLabel
  95         kSecAttrIsInvisible
  96         kSecAttrIsNegative
  97         kSecAttrAccount
  98         kSecAttrService
  99         kSecAttrGeneric
 100         kSecAttrSynchronizable
 101
 102     kSecClassInternetPassword item attributes:
 103         kSecAttrAccessible
 104         kSecAttrAccessControl
 105         kSecAttrAccessGroup
 106         kSecAttrCreationDate
 107         kSecAttrModificationDate
 108         kSecAttrDescription
 109         kSecAttrComment
 110         kSecAttrCreator
 111         kSecAttrType
 112         kSecAttrLabel
 113         kSecAttrIsInvisible
 114         kSecAttrIsNegative
 115         kSecAttrAccount
 116         kSecAttrSecurityDomain
 117         kSecAttrServer
 118         kSecAttrProtocol
 119         kSecAttrAuthenticationType
 120         kSecAttrPort
 121         kSecAttrPath
 122         kSecAttrSynchronizable
 123
 124     kSecClassCertificate item attributes:
 125         kSecAttrAccessible
 126         kSecAttrAccessControl
 127         kSecAttrAccessGroup
 128         kSecAttrCertificateType
 129         kSecAttrCertificateEncoding
 130         kSecAttrLabel
 131         kSecAttrSubject
 132         kSecAttrIssuer
 133         kSecAttrSerialNumber
 134         kSecAttrSubjectKeyID
 135         kSecAttrPublicKeyHash
 136         kSecAttrSynchronizable
 137
 138     kSecClassKey item attributes:
 139         kSecAttrAccessible
 140         kSecAttrAccessControl
 141         kSecAttrAccessGroup
 142         kSecAttrKeyClass
 143         kSecAttrLabel
 144         kSecAttrApplicationLabel
 145         kSecAttrIsPermanent
 146         kSecAttrApplicationTag
 147         kSecAttrKeyType
 148         kSecAttrKeySizeInBits
 149         kSecAttrEffectiveKeySize
 150         kSecAttrCanEncrypt
 151         kSecAttrCanDecrypt
 152         kSecAttrCanDerive
 153         kSecAttrCanSign
 154         kSecAttrCanVerify
 155         kSecAttrCanWrap
 156         kSecAttrCanUnwrap
 157         kSecAttrSynchronizable
 158
 159     kSecClassIdentity item attributes:
 160         Since an identity is the combination of a private key and a
 161         certificate, this class shares attributes of both kSecClassKey and
 162         kSecClassCertificate.
 163
 164      @constant kSecAttrAccessible Specifies a dictionary key whose value
 165      indicates when your application needs access to an item's data.  You
 166      should choose the most restrictive option that meets your application's
 167      needs to allow the system to protect that item in the best way possible.
 168      See the "kSecAttrAccessible Value Constants" section for a list of
 169      values which can be specified.
 170      IMPORTANT: This attribute is currently not supported for OS X keychain
 171      items, unless the kSecAttrSynchronizable attribute is also present. If
 172      both attributes are specified on either OS X or iOS, the value for the
 173      kSecAttrAccessible key may only be one whose name does not end with
 174      "ThisDeviceOnly", as those cannot sync to another device.
 175
 176      @constant kSecAttrAccessControl Specifies a dictionary key whose value
 177      is SecAccessControl instance which contains access control conditions
 178      for item.
 179
 180      @constant kSecAttrAccessGroup Specifies a dictionary key whose value is
 181      a CFStringRef indicating which access group a item is in.  The access
 182      groups that a particular application has membership in are determined by
 183      two entitlements for that application.  The application-identifier
 184      entitlement contains the application's single access group, unless
 185      there is a keychain-access-groups entitlement present.  The latter
 186      has as its value a list of access groups; the first item in this list
 187      is the default access group. Unless a specific access group is provided
 188      as the value of kSecAttrAccessGroup when SecItemAdd is called, new items
 189      are created in the application's default access group.  Specifying this
 190      attribute in SecItemCopyMatching, SecItemUpdate, or SecItemDelete calls
 191      limits the search to the specified access group (of which the calling
 192      application must be a member to obtain matching results.)  To share
 193      keychain items between multiple applications, each application must have
 194      a common group listed in its keychain-access-groups entitlement, and each
 195      must specify this shared access group name as the value for the
 196      kSecAttrAccessGroup key in the dictionary passed to SecItem functions.
 197
 198      @constant kSecAttrSynchronizable Specifies a dictionary key whose value is
 199      a CFBooleanRef indicating whether the item in question can be synchronized.
 200      To add a new item which can be synced to other devices, or to obtain
 201      synchronizable results from a query, supply this key with a value of
 202      kCFBooleanTrue. If the key is not supplied, or has a value of
 203      kCFBooleanFalse, then no synchronizable items will be added or returned.
 204      A predefined value, kSecAttrSynchronizableAny, may be provided instead of
 205      kCFBooleanTrue if both synchronizable and non-synchronizable results are
 206      desired.
 207
 208      IMPORTANT: Specifying the kSecAttrSynchronizable key has several caveats:
 209
 210          - Updating or deleting items using the kSecAttrSynchronizable key will
 211            affect all copies of the item, not just the one on your local device.
 212            Be sure that it makes sense to use the same password on all devices
 213            before deciding to make a password synchronizable.
 214          - Only password items can currently be synchronized. Keychain syncing
 215            is not supported for certificates or cryptographic keys.
 216          - Items stored or obtained using the kSecAttrSynchronizable key cannot
 217            specify SecAccessRef-based access control with kSecAttrAccess. If a
 218            password is intended to be shared between multiple applications, the
 219            kSecAttrAccessGroup key must be specified, and each application
 220            using this password must have a 'keychain-access-groups' entitlement
 221            with the specified access group value.
 222          - Items stored or obtained using the kSecAttrSynchronizable key may
 223            not also specify a kSecAttrAccessible value which is incompatible
 224            with syncing (namely, those whose names end with "ThisDeviceOnly".)
 225          - Items stored or obtained using the kSecAttrSynchronizable key cannot
 226            be specified by reference. You must pass kSecReturnAttributes and/or
 227            kSecReturnData to retrieve results; kSecReturnRef is currently not
 228            supported for synchronizable items.
 229          - Persistent references to synchronizable items should be avoided;
 230            while they may work locally, they cannot be moved between devices,
 231            and may not resolve if the item is modified on some other device.
 232          - When specifying a query that uses the kSecAttrSynchronizable key,
 233            search keys are limited to the item's class and attributes.
 234            The only search constant which may be used is kSecMatchLimit; other
 235            constants using the kSecMatch prefix are not supported at this time.
 236
 237     @constant kSecAttrCreationDate (read-only) Specifies a dictionary key whose
 238         value is the item's creation date. You use this key to get a value
 239         of type CFDateRef that represents the date the item was created.
 240     @constant kSecAttrModificationDate (read-only) Specifies a dictionary key
 241         whose value is the item's modification date. You use this key to get
 242         a value of type CFDateRef that represents the last time the item was
 243         updated.
 244     @constant kSecAttrDescription Specifies a dictionary key whose value is
 245         the item's description attribute. You use this key to set or get a
 246         value of type CFStringRef that represents a user-visible string
 247         describing this particular kind of item (e.g., "disk image password").
 248     @constant kSecAttrComment Specifies a dictionary key whose value is the
 249         item's comment attribute. You use this key to set or get a value of
 250         type CFStringRef containing the user-editable comment for this item.
 251     @constant kSecAttrCreator Specifies a dictionary key whose value is the
 252         item's creator attribute. You use this key to set or get a value of
 253         type CFNumberRef that represents the item's creator. This number is
 254         the unsigned integer representation of a four-character code (e.g.,
 255         'aCrt').
 256     @constant kSecAttrType Specifies a dictionary key whose value is the item's
 257         type attribute. You use this key to set or get a value of type
 258         CFNumberRef that represents the item's type. This number is the
 259         unsigned integer representation of a four-character code (e.g.,
 260         'aTyp').
 261     @constant kSecAttrLabel Specifies a dictionary key whose value is the
 262         item's label attribute. You use this key to set or get a value of
 263         type CFStringRef containing the user-visible label for this item.
 264     @constant kSecAttrIsInvisible Specifies a dictionary key whose value is the
 265         item's invisible attribute. You use this key to set or get a value
 266         of type CFBooleanRef that indicates whether the item is invisible
 267         (i.e., should not be displayed.)
 268     @constant kSecAttrIsNegative Specifies a dictionary key whose value is the
 269         item's negative attribute. You use this key to set or get a value of
 270         type CFBooleanRef that indicates whether there is a valid password
 271         associated with this keychain item. This is useful if your application
 272         doesn't want a password for some particular service to be stored in
 273         the keychain, but prefers that it always be entered by the user.
 274     @constant kSecAttrAccount Specifies a dictionary key whose value is the
 275         item's account attribute. You use this key to set or get a CFStringRef
 276         that contains an account name. (Items of class
 277         kSecClassGenericPassword, kSecClassInternetPassword have this
 278         attribute.)
 279     @constant kSecAttrService Specifies a dictionary key whose value is the
 280         item's service attribute. You use this key to set or get a CFStringRef
 281         that represents the service associated with this item. (Items of class
 282         kSecClassGenericPassword have this attribute.)
 283     @constant kSecAttrGeneric Specifies a dictionary key whose value is the
 284         item's generic attribute. You use this key to set or get a value of
 285         CFDataRef that contains a user-defined attribute. (Items of class
 286         kSecClassGenericPassword have this attribute.)
 287     @constant kSecAttrSecurityDomain Specifies a dictionary key whose value
 288         is the item's security domain attribute. You use this key to set or
 289         get a CFStringRef value that represents the Internet security domain.
 290         (Items of class kSecClassInternetPassword have this attribute.)
 291     @constant kSecAttrServer Specifies a dictionary key whose value is the
 292         item's server attribute. You use this key to set or get a value of
 293         type CFStringRef that contains the server's domain name or IP address.
 294         (Items of class kSecClassInternetPassword have this attribute.)
 295     @constant kSecAttrProtocol Specifies a dictionary key whose value is the
 296         item's protocol attribute. You use this key to set or get a value of
 297         type CFNumberRef that denotes the protocol for this item (see the
 298         SecProtocolType enum in SecKeychainItem.h). (Items of class
 299         kSecClassInternetPassword have this attribute.)
 300     @constant kSecAttrAuthenticationType Specifies a dictionary key whose value
 301         is the item's authentication type attribute. You use this key to set
 302         or get a value of type CFNumberRef that denotes the authentication
 303         scheme for this item (see the kSecAttrAuthenticationType value
 304         constants below).
 305     @constant kSecAttrPort Specifies a dictionary key whose value is the item's
 306         port attribute. You use this key to set or get a CFNumberRef value
 307         that represents an Internet port number. (Items of class
 308         kSecClassInternetPassword have this attribute.)
 309     @constant kSecAttrPath Specifies a dictionary key whose value is the item's
 310         path attribute, typically this is the path component of the URL.  You use
 311         this key to set or get a CFStringRef value that represents a path. (Items
 312         of class kSecClassInternetPassword have this attribute.)
 313     @constant kSecAttrSubject (read-only) Specifies a dictionary key whose
 314         value is the item's subject. You use this key to get a value of type
 315         CFDataRef that contains the X.500 subject name of a certificate.
 316         (Items of class kSecClassCertificate have this attribute.)
 317     @constant kSecAttrIssuer (read-only) Specifies a dictionary key whose value
 318         is the item's issuer. You use this key to get a value of type
 319         CFDataRef that contains the X.500 issuer name of a certificate. (Items
 320         of class kSecClassCertificate have this attribute.)
 321     @constant kSecAttrSerialNumber (read-only) Specifies a dictionary key whose
 322         value is the item's serial number.  You use this key to get a value
 323         of type CFDataRef that contains the serial number data of a
 324         certificate. (Items of class kSecClassCertificate have this
 325         attribute.)
 326     @constant kSecAttrSubjectKeyID (read-only) Specifies a dictionary key whose
 327         value is the item's subject key ID. You use this key to get a value
 328         of type CFDataRef that contains the subject key ID of a certificate.
 329         (Items of class kSecClassCertificate have this attribute.)
 330     @constant kSecAttrPublicKeyHash (read-only) Specifies a dictionary key
 331         whose value is the item's public key hash. You use this key to get a
 332         value of type CFDataRef that contains the hash of a certificate's
 333         public key. (Items of class kSecClassCertificate have this attribute.)
 334     @constant kSecAttrCertificateType (read-only) Specifies a dictionary key
 335         whose value is the item's certificate type. You use this key to get
 336         a value of type CFNumberRef that denotes the certificate type
 337         (Currently only the value of this attribute must be equal to the
 338         version of the X509 certificate.  So 1 for v1 2 for v2 and 3 for v3
 339         certificates). Only items of class kSecClassCertificate have this
 340         attribute.
 341     @constant kSecAttrCertificateEncoding (read-only) Specifies a dictionary
 342         key whose value is the item's certificate encoding. You use this key
 343         to get a value of type CFNumberRef that denotes the certificate
 344         encoding (Currently only the value 3 meaning
 345         kSecAttrCertificateEncodingDER is supported). Only items of class
 346         kSecClassCertificate have this attribute.
 347     @constant kSecAttrKeyClass (read only) Specifies a dictionary key whose
 348         value is one of kSecAttrKeyClassPublic, kSecAttrKeyClassPrivate or
 349         kSecAttrKeyClassSymmetric.
 350     @constant kSecAttrApplicationLabel Specifies a dictionary key whose value
 351         is the key's application label attribute. This is different from the
 352         kSecAttrLabel (which is intended to be human-readable). This attribute
 353         is used to look up a key programmatically; in particular, for keys of
 354         class kSecAttrKeyClassPublic and kSecAttrKeyClassPrivate, the value of
 355         this attribute is the hash of the public key. This item is a type of CFDataRef.
 356         Legacy keys may contain a UUID in this field as a CFStringRef.
 357     @constant kSecAttrIsPermanent Specifies a dictionary key whose value is a
 358         CFBooleanRef indicating whether the key in question will be stored
 359         permanently.
 360     @constant kSecAttrApplicationTag Specifies a dictionary key whose value is a
 361         CFDataRef containing private tag data.
 362     @constant kSecAttrKeyType Specifies a dictionary key whose value is a
 363         CFNumberRef indicating the algorithm associated with this key
 364         (Currently only the value 42 is supported, alternatively you can use
 365         kSecAttrKeyTypeRSA).
 366     @constant kSecAttrKeySizeInBits Specifies a dictionary key whose value
 367         is a CFNumberRef indicating the number of bits in this key.
 368     @constant kSecAttrEffectiveKeySize Specifies a dictionary key whose value
 369         is a CFNumberRef indicating the effective number of bits in this key.
 370         For example, a DES key has a kSecAttrKeySizeInBits of 64, but a
 371         kSecAttrEffectiveKeySize of 56 bits.
 372     @constant kSecAttrCanEncrypt Specifies a dictionary key whole value is a
 373         CFBooleanRef indicating whether the key in question can be used to
 374         encrypt data.
 375     @constant kSecAttrCanDecrypt Specifies a dictionary key whose value is a
 376         CFBooleanRef indicating whether the key in question can be used to
 377         decrypt data.
 378     @constant kSecAttrCanDerive Specifies a dictionary key whole value is a
 379         CFBooleanRef indicating whether the key in question can be used to
 380         derive another key.
 381     @constant kSecAttrCanSign Specifies a dictionary key whole value is a
 382         CFBooleanRef indicating whether the key in question can be used to
 383         create a digital signature.
 384     @constant kSecAttrCanVerify Specifies a dictionary key whole value is a
 385         CFBooleanRef indicating whether the key in question can be used to
 386         verify a digital signature.
 387     @constant kSecAttrCanWrap Specifies a dictionary key whole value is a
 388         CFBooleanRef indicating whether the key in question can be used to
 389         wrap another key.
 390     @constant kSecAttrCanUnwrap Specifies a dictionary key whole value is a
 391         CFBooleanRef indicating whether the key in question can be used to
 392         unwrap another key.
 393     @constant kSecAttrSyncViewHint Specifies a dictionary key whose value is
 394         a CFStringRef. This value is part of the primary key of each item, and
 395         can be used to help distiguish Sync Views when defining their
 396         queries.
 397     @constant kSecAttrTokenID Specifies a dictionary key whose presence
 398         indicates that item is backed by external token. Value of this attribute
 399         is CFStringRef uniquely identifying containing token. When this attribute
 400         is not present, item is stored in internal keychain database.
 401         Note that once item is created, this attribute cannot be changed - in other
 402         words it is not possible to migrate existing items to, from or between tokens.
 403         Currently the only available value for this attribute is
 404         kSecAttrTokenIDSecureEnclave, which indicates that item (private key) is
 405         backed by device's Secure Enclave.
 406  */
 407 extern const CFStringRef kSecAttrAccessible
 408     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_4_0);
 409 extern const CFStringRef kSecAttrAccessControl
 410     __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0);
 411 extern const CFStringRef kSecAttrAccessGroup
 412     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_3_0);
 413 extern const CFStringRef kSecAttrSynchronizable
 414     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 415 extern const CFStringRef kSecAttrCreationDate
 416     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 417 extern const CFStringRef kSecAttrModificationDate
 418     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 419 extern const CFStringRef kSecAttrDescription
 420     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 421 extern const CFStringRef kSecAttrComment
 422     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 423 extern const CFStringRef kSecAttrCreator
 424     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 425 extern const CFStringRef kSecAttrType
 426     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 427 extern const CFStringRef kSecAttrLabel
 428     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 429 extern const CFStringRef kSecAttrIsInvisible
 430     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 431 extern const CFStringRef kSecAttrIsNegative
 432     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 433 extern const CFStringRef kSecAttrAccount
 434     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 435 extern const CFStringRef kSecAttrService
 436     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 437 extern const CFStringRef kSecAttrGeneric
 438     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 439 extern const CFStringRef kSecAttrSecurityDomain
 440     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 441 extern const CFStringRef kSecAttrServer
 442     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 443 extern const CFStringRef kSecAttrProtocol
 444     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 445 extern const CFStringRef kSecAttrAuthenticationType
 446     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 447 extern const CFStringRef kSecAttrPort
 448     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 449 extern const CFStringRef kSecAttrPath
 450     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 451 extern const CFStringRef kSecAttrSubject
 452     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 453 extern const CFStringRef kSecAttrIssuer
 454     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 455 extern const CFStringRef kSecAttrSerialNumber
 456     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 457 extern const CFStringRef kSecAttrSubjectKeyID
 458     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 459 extern const CFStringRef kSecAttrPublicKeyHash
 460     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 461 extern const CFStringRef kSecAttrCertificateType
 462     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 463 extern const CFStringRef kSecAttrCertificateEncoding
 464     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 465 extern const CFStringRef kSecAttrKeyClass
 466     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 467 extern const CFStringRef kSecAttrApplicationLabel
 468     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 469 extern const CFStringRef kSecAttrIsPermanent
 470     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 471 extern const CFStringRef kSecAttrApplicationTag
 472     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 473 extern const CFStringRef kSecAttrKeyType
 474     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 475 extern const CFStringRef kSecAttrKeySizeInBits
 476     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 477 extern const CFStringRef kSecAttrEffectiveKeySize
 478     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 479 extern const CFStringRef kSecAttrCanEncrypt
 480     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 481 extern const CFStringRef kSecAttrCanDecrypt
 482     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 483 extern const CFStringRef kSecAttrCanDerive
 484     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 485 extern const CFStringRef kSecAttrCanSign
 486     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 487 extern const CFStringRef kSecAttrCanVerify
 488     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 489 extern const CFStringRef kSecAttrCanWrap
 490     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 491 extern const CFStringRef kSecAttrCanUnwrap
 492     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 493 extern const CFStringRef kSecAttrSyncViewHint
 494     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);
 495 extern const CFStringRef kSecAttrTokenID
 496     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_9_0);
 497
 498 /*!
 499     @enum kSecAttrAccessible Value Constants
 500     @discussion Predefined item attribute constants used to get or set values
 501         in a dictionary. The kSecAttrAccessible constant is the key and its
 502         value is one of the constants defined here.
 503         When asking SecItemCopyMatching to return the item's data, the error
 504         errSecInteractionNotAllowed will be returned if the item's data is not
 505         available until a device unlock occurs.
 506     @constant kSecAttrAccessibleWhenUnlocked Item data can only be accessed
 507         while the device is unlocked. This is recommended for items that only
 508         need be accesible while the application is in the foreground.  Items
 509         with this attribute will migrate to a new device when using encrypted
 510         backups.
 511     @constant kSecAttrAccessibleAfterFirstUnlock Item data can only be
 512         accessed once the device has been unlocked after a restart.  This is
 513         recommended for items that need to be accesible by background
 514         applications. Items with this attribute will migrate to a new device
 515         when using encrypted backups.
 516     @constant kSecAttrAccessibleAlways Item data can always be accessed
 517         regardless of the lock state of the device.  This is not recommended
 518         for anything except system use. Items with this attribute will migrate
 519         to a new device when using encrypted backups.
 520     @constant kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly Item data can
 521          only be accessed while the device is unlocked. This class is only
 522          available if a passcode is set on the device. This is recommended for
 523          items that only need to be accessible while the application is in the
 524          foreground. Items with this attribute will never migrate to a new
 525          device, so after a backup is restored to a new device, these items
 526          will be missing. No items can be stored in this class on devices
 527          without a passcode. Disabling the device passcode will cause all
 528          items in this class to be deleted.
 529     @constant kSecAttrAccessibleWhenUnlockedThisDeviceOnly Item data can only
 530         be accessed while the device is unlocked. This is recommended for items
 531         that only need be accesible while the application is in the foreground.
 532         Items with this attribute will never migrate to a new device, so after
 533         a backup is restored to a new device, these items will be missing.
 534     @constant kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly Item data can
 535         only be accessed once the device has been unlocked after a restart.
 536         This is recommended for items that need to be accessible by background
 537         applications. Items with this attribute will never migrate to a new
 538         device, so after a backup is restored to a new device these items will
 539         be missing.
 540     @constant kSecAttrAccessibleAlwaysThisDeviceOnly Item data can always
 541         be accessed regardless of the lock state of the device.  This option
 542         is not recommended for anything except system use. Items with this
 543         attribute will never migrate to a new device, so after a backup is
 544         restored to a new device, these items will be missing.
 545 */
 546 extern const CFStringRef kSecAttrAccessibleWhenUnlocked
 547     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_4_0);
 548 extern const CFStringRef kSecAttrAccessibleAfterFirstUnlock
 549     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_4_0);
 550 extern const CFStringRef kSecAttrAccessibleAlways
 551     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_4_0);
 552 extern const CFStringRef kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly
 553     __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0);
 554 extern const CFStringRef kSecAttrAccessibleWhenUnlockedThisDeviceOnly
 555     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_4_0);
 556 extern const CFStringRef kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
 557     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_4_0);
 558 extern const CFStringRef kSecAttrAccessibleAlwaysThisDeviceOnly
 559     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_4_0);
 560
 561 /*!
 562     @enum kSecAttrProtocol Value Constants
 563     @discussion Predefined item attribute constants used to get or set values
 564                 in a dictionary. The kSecAttrProtocol constant is the key and its
 565                 value is one of the constants defined here.
 566     @constant kSecAttrProtocolFTP.
 567     @constant kSecAttrProtocolFTPAccount.
 568     @constant kSecAttrProtocolHTTP.
 569     @constant kSecAttrProtocolIRC.
 570     @constant kSecAttrProtocolNNTP.
 571     @constant kSecAttrProtocolPOP3.
 572     @constant kSecAttrProtocolSMTP.
 573     @constant kSecAttrProtocolSOCKS.
 574     @constant kSecAttrProtocolIMAP.
 575     @constant kSecAttrProtocolLDAP.
 576     @constant kSecAttrProtocolAppleTalk.
 577     @constant kSecAttrProtocolAFP.
 578     @constant kSecAttrProtocolTelnet.
 579     @constant kSecAttrProtocolSSH.
 580     @constant kSecAttrProtocolFTPS.
 581     @constant kSecAttrProtocolHTTPS.
 582     @constant kSecAttrProtocolHTTPProxy.
 583     @constant kSecAttrProtocolHTTPSProxy.
 584     @constant kSecAttrProtocolFTPProxy.
 585     @constant kSecAttrProtocolSMB.
 586     @constant kSecAttrProtocolRTSP.
 587     @constant kSecAttrProtocolRTSPProxy.
 588     @constant kSecAttrProtocolDAAP.
 589     @constant kSecAttrProtocolEPPC.
 590     @constant kSecAttrProtocolIPP.
 591     @constant kSecAttrProtocolNNTPS.
 592     @constant kSecAttrProtocolLDAPS.
 593     @constant kSecAttrProtocolTelnetS.
 594     @constant kSecAttrProtocolIMAPS.
 595     @constant kSecAttrProtocolIRCS.
 596     @constant kSecAttrProtocolPOP3S.
 597 */
 598 extern const CFStringRef kSecAttrProtocolFTP
 599     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 600 extern const CFStringRef kSecAttrProtocolFTPAccount
 601     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 602 extern const CFStringRef kSecAttrProtocolHTTP
 603     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 604 extern const CFStringRef kSecAttrProtocolIRC
 605     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 606 extern const CFStringRef kSecAttrProtocolNNTP
 607     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 608 extern const CFStringRef kSecAttrProtocolPOP3
 609     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 610 extern const CFStringRef kSecAttrProtocolSMTP
 611     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 612 extern const CFStringRef kSecAttrProtocolSOCKS
 613     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 614 extern const CFStringRef kSecAttrProtocolIMAP
 615     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 616 extern const CFStringRef kSecAttrProtocolLDAP
 617     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 618 extern const CFStringRef kSecAttrProtocolAppleTalk
 619     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 620 extern const CFStringRef kSecAttrProtocolAFP
 621     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 622 extern const CFStringRef kSecAttrProtocolTelnet
 623     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 624 extern const CFStringRef kSecAttrProtocolSSH
 625     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 626 extern const CFStringRef kSecAttrProtocolFTPS
 627     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 628 extern const CFStringRef kSecAttrProtocolHTTPS
 629     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 630 extern const CFStringRef kSecAttrProtocolHTTPProxy
 631     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 632 extern const CFStringRef kSecAttrProtocolHTTPSProxy
 633     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 634 extern const CFStringRef kSecAttrProtocolFTPProxy
 635     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 636 extern const CFStringRef kSecAttrProtocolSMB
 637     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 638 extern const CFStringRef kSecAttrProtocolRTSP
 639     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 640 extern const CFStringRef kSecAttrProtocolRTSPProxy
 641     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 642 extern const CFStringRef kSecAttrProtocolDAAP
 643     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 644 extern const CFStringRef kSecAttrProtocolEPPC
 645     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 646 extern const CFStringRef kSecAttrProtocolIPP
 647     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 648 extern const CFStringRef kSecAttrProtocolNNTPS
 649     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 650 extern const CFStringRef kSecAttrProtocolLDAPS
 651     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 652 extern const CFStringRef kSecAttrProtocolTelnetS
 653     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 654 extern const CFStringRef kSecAttrProtocolIMAPS
 655     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 656 extern const CFStringRef kSecAttrProtocolIRCS
 657     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 658 extern const CFStringRef kSecAttrProtocolPOP3S
 659     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 660
 661 /*!
 662     @enum kSecAttrAuthenticationType Value Constants
 663     @discussion Predefined item attribute constants used to get or set values
 664                 in a dictionary. The kSecAttrAuthenticationType constant is the key
 665                 and its value is one of the constants defined here.
 666     @constant kSecAttrAuthenticationTypeNTLM.
 667     @constant kSecAttrAuthenticationTypeMSN.
 668     @constant kSecAttrAuthenticationTypeDPA.
 669     @constant kSecAttrAuthenticationTypeRPA.
 670     @constant kSecAttrAuthenticationTypeHTTPBasic.
 671     @constant kSecAttrAuthenticationTypeHTTPDigest.
 672     @constant kSecAttrAuthenticationTypeHTMLForm.
 673     @constant kSecAttrAuthenticationTypeDefault.
 674 */
 675 extern const CFStringRef kSecAttrAuthenticationTypeNTLM
 676     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 677 extern const CFStringRef kSecAttrAuthenticationTypeMSN
 678     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 679 extern const CFStringRef kSecAttrAuthenticationTypeDPA
 680     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 681 extern const CFStringRef kSecAttrAuthenticationTypeRPA
 682     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 683 extern const CFStringRef kSecAttrAuthenticationTypeHTTPBasic
 684     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 685 extern const CFStringRef kSecAttrAuthenticationTypeHTTPDigest
 686     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 687 extern const CFStringRef kSecAttrAuthenticationTypeHTMLForm
 688     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 689 extern const CFStringRef kSecAttrAuthenticationTypeDefault
 690     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 691
 692 /*!
 693     @enum kSecAttrKeyClass Value Constants
 694     @discussion Predefined item attribute constants used to get or set values
 695                 in a dictionary. The kSecAttrKeyClass constant is the key
 696                 and its value is one of the constants defined here.
 697     @constant kSecAttrKeyClassPublic.
 698     @constant kSecAttrKeyClassPrivate.
 699     @constant kSecAttrKeyClassSymmetric.
 700 */
 701 extern const CFStringRef kSecAttrKeyClassPublic
 702     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
 703 extern const CFStringRef kSecAttrKeyClassPrivate
 704     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
 705 extern const CFStringRef kSecAttrKeyClassSymmetric
 706     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
 707
 708 /*!
 709     @enum kSecAttrKeyType Value Constants
 710     @discussion Predefined item attribute constants used to get or set values
 711                 in a dictionary. The kSecAttrKeyType constant is the key
 712                 and its value is one of the constants defined here.
 713     @constant kSecAttrKeyTypeRSA.
 714     @constant kSecAttrKeyTypeECSECPrimeRandom.
 715     @constant kSecAttrKeyTypeEC This is legacy name for kSecAttrKeyTypeECSECPrimeRandom, new applications should not use it.
 716 */
 717 extern const CFStringRef kSecAttrKeyTypeRSA
 718     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
 719 extern const CFStringRef kSecAttrKeyTypeEC
 720     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_4_0);
 721 extern const CFStringRef kSecAttrKeyTypeECSECPrimeRandom
 722     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0);
 723
 724 /*!
 725     @enum kSecAttrSynchronizable Value Constants
 726     @discussion Predefined item attribute constants used to get or set values
 727                 in a dictionary. The kSecAttrSynchronizable constant is the key
 728                 and its value is one of the constants defined here.
 729     @constant kSecAttrSynchronizableAny Specifies that both synchronizable and
 730         non-synchronizable results should be returned from this query. This may
 731         be used as a value for the kSecAttrSynchronizable dictionary key in a
 732         call to SecItemCopyMatching, SecItemUpdate, or SecItemDelete.
 733 */
 734 extern const CFStringRef kSecAttrSynchronizableAny
 735     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 736
 737 /*!
 738     @enum Search Constants
 739     @discussion Predefined search constants used to set values in a query
 740         dictionary. You can specify a combination of search attributes and
 741         item attributes when looking for matching items with the
 742         SecItemCopyMatching function.
 743     @constant kSecMatchPolicy Specifies a dictionary key whose value is a
 744         SecPolicyRef. If provided, returned certificates or identities must
 745         verify with this policy.
 746     @constant kSecMatchIssuers Specifies a dictionary key whose value is a
 747         CFArray of X.500 names (of type CFDataRef). If provided, returned
 748         certificates or identities will be limited to those whose
 749         certificate chain contains one of the issuers provided in this list.
 750     @constant kSecMatchEmailAddressIfPresent Specifies a dictionary key whose
 751         value is a CFStringRef containing an RFC822 email address. If
 752         provided, returned certificates or identities will be limited to those
 753         that contain the address, or do not contain any email address.
 754     @constant kSecMatchSubjectContains Specifies a dictionary key whose value
 755         is a CFStringRef. If provided, returned certificates or identities
 756         will be limited to those containing this string in the subject.
 757     @constant kSecMatchCaseInsensitive Specifies a dictionary key whose value
 758         is a CFBooleanRef. If this value is kCFBooleanFalse, or is not
 759         provided, then case-sensitive string matching is performed.
 760     @constant kSecMatchTrustedOnly Specifies a dictionary key whose value is
 761         a CFBooleanRef. If provided with a value of kCFBooleanTrue, only
 762         certificates which can be verified back to a trusted anchor will be
 763         returned. If this value is kCFBooleanFalse, or is not provided, then
 764         both trusted and untrusted certificates may be returned.
 765     @constant kSecMatchValidOnDate Specifies a dictionary key whose value is
 766         of type CFDateRef. If provided, returned keys, certificates or
 767         identities will be limited to those which are valid for the given date.
 768         Pass a value of kCFNull to indicate the current date.
 769     @constant kSecMatchLimit Specifies a dictionary key whose value is a
 770         CFNumberRef. If provided, this value specifies the maximum number of
 771         results to return. If not provided, results are limited to the first
 772         item found. Predefined values are provided for a single item
 773         (kSecMatchLimitOne) and all matching items (kSecMatchLimitAll).
 774     @constant kSecMatchLimitOne Specifies that results are limited to the first
 775         item found; used as a value for the kSecMatchLimit dictionary key.
 776     @constant kSecMatchLimitAll Specifies that an unlimited number of results
 777         may be returned; used as a value for the kSecMatchLimit dictionary
 778         key.
 779 */
 780 extern const CFStringRef kSecMatchPolicy
 781     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 782 extern const CFStringRef kSecMatchItemList
 783     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 784 extern const CFStringRef kSecMatchSearchList
 785     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 786 extern const CFStringRef kSecMatchIssuers
 787     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 788 extern const CFStringRef kSecMatchEmailAddressIfPresent
 789     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 790 extern const CFStringRef kSecMatchSubjectContains
 791     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 792 extern const CFStringRef kSecMatchCaseInsensitive
 793     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 794 extern const CFStringRef kSecMatchTrustedOnly
 795     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 796 extern const CFStringRef kSecMatchValidOnDate
 797     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 798 extern const CFStringRef kSecMatchLimit
 799     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 800 extern const CFStringRef kSecMatchLimitOne
 801     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 802 extern const CFStringRef kSecMatchLimitAll
 803     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 804
 805
 806 /*!
 807     @enum Return Type Key Constants
 808     @discussion Predefined return type keys used to set values in a dictionary.
 809         You use these keys to specify the type of results which should be
 810         returned by the SecItemCopyMatching or SecItemAdd function. You can
 811         specify zero or more of these return types. If more than one of these
 812         result types is specified, the result is returned as a CFDictionaryRef
 813         whose keys are the result types and values are the requested data.
 814     @constant kSecReturnData Specifies a dictionary key whose value is of type
 815         CFBooleanRef. A value of kCFBooleanTrue indicates that the data of
 816         an item (CFDataRef) should be returned. For keys and password
 817         items, data is secret (encrypted) and may require the user to enter
 818         a password for access.
 819     @constant kSecReturnAttributes Specifies a dictionary key whose value is
 820         of type CFBooleanRef. A value of kCFBooleanTrue indicates that the
 821         (non-encrypted) attributes of an item (CFDictionaryRef) should be
 822         returned.
 823     @constant kSecReturnRef Specifies a dictionary key whose value is a
 824         CFBooleanRef. A value of kCFBooleanTrue indicates that a reference
 825         should be returned. Depending on the item class requested, the
 826         returned reference(s) may be of type SecKeychainItemRef, SecKeyRef,
 827         SecCertificateRef, or SecIdentityRef.
 828     @constant kSecReturnPersistentRef Specifies a dictionary key whose value
 829         is of type CFBooleanRef. A value of kCFBooleanTrue indicates that a
 830         persistent reference to an item (CFDataRef) should be returned.
 831 */
 832 extern const CFStringRef kSecReturnData
 833     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 834 extern const CFStringRef kSecReturnAttributes
 835     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 836 extern const CFStringRef kSecReturnRef
 837     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 838 extern const CFStringRef kSecReturnPersistentRef
 839     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 840
 841
 842 /*!
 843     @enum Value Type Key Constants
 844     @discussion Predefined value type keys used to pass values in a dictionary.
 845         You can specify zero or more of these types depending on the function
 846         you are calling.  For SecItemCopyMatching or SecItemAdd these are
 847         used as keys in the results dictionary.
 848     @constant kSecValueData Specifies a dictionary key whose value is of type
 849         CFDataRef.  For keys and password items, data is secret (encrypted)
 850         and may require the user to enter a password for access.
 851     @constant kSecValueRef Specifies a dictionary key whose value, depending
 852         on the item class requested, is of type SecKeychainItemRef, SecKeyRef,
 853         SecCertificateRef, or SecIdentityRef.
 854     @constant kSecValuePersistentRef Specifies a dictionary key whose value
 855         is of type CFDataRef.  The bytes in this CFDataRef can be stored by
 856         the caller and used on a subsequent invocation of the application (or
 857         even a different application) to retrieve the item referenced by it.
 858 */
 859 extern const CFStringRef kSecValueData
 860     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 861 extern const CFStringRef kSecValueRef
 862     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 863 extern const CFStringRef kSecValuePersistentRef
 864     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 865
 866
 867 /*!
 868     @enum Other Constants
 869     @discussion Predefined constants used to set values in a dictionary.
 870     @constant kSecUseItemList Specifies a dictionary key whose value is a
 871         CFArray of items. If provided, this array is treated as the set of
 872         all possible items to search, or add if the API being called is
 873         SecItemAdd. The items in this array may be of type SecKeyRef,
 874         SecCertificateRef, SecIdentityRef, or CFDataRef (for a persistent
 875         item reference.) The items in the array must all be of the same
 876         type. When this attribute is provided, no keychains are searched.
 877     @constant kSecUseOperationPrompt Specifies a dictionary key whose value
 878         is a CFStringRef that represents a user-visible string describing
 879         the operation for which the application is attempting to authenticate.
 880         The application is responsible for the text localization.
 881     @constant kSecUseNoAuthenticationUI Specifies a dictionary key whose value
 882         is a CFBooleanRef. If provided with a value of kCFBooleanTrue, the error
 883         errSecInteractionNotAllowed will be returned if the item is attempting
 884         to authenticate with UI.
 885     @constant kSecUseAuthenticationUI Specifies a dictionary key whose value
 886         is one of kSecUseAuthenticationUIAllow, kSecUseAuthenticationUIFail, kSecUseAuthenticationUISkip.
 887     @constant kSecUseAuthenticationContext Specifies a dictionary key whose value
 888         is LAContext to be used for keychain item authentication.
 889         * If the item requires authentication and this key is omitted, a new context
 890           will be created just for the purpose of the single call.
 891         * If the specified context has been previously authenticated, the operation
 892           will succeed without asking user for authentication.
 893         * If the specified context has not been previously authenticated, the new
 894           authentication will be started on this context, allowing caller to
 895           eventually reuse the sucessfully authenticated context in subsequent
 896           keychain operations.
 897 */
 898 extern const CFStringRef kSecUseItemList
 899     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 900 extern const CFStringRef kSecUseOperationPrompt
 901     __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0);
 902 extern const CFStringRef kSecUseNoAuthenticationUI
 903     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_10, __MAC_10_11, __IPHONE_8_0, __IPHONE_9_0, "Use a kSecUseAuthenticationUI instead.");
 904 extern const CFStringRef kSecUseAuthenticationUI
 905     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);
 906 extern const CFStringRef kSecUseAuthenticationContext
 907     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);
 908
 909 /*!
 910     @enum kSecUseAuthenticationUI Value Constants
 911     @discussion Predefined item attribute constants used to get or set values
 912         in a dictionary. The kSecUseAuthenticationUI constant is the key and its
 913         value is one of the constants defined here.
 914         If the key kSecUseAuthenticationUI not provided then kSecUseAuthenticationUIAllow
 915         is used as default.
 916     @constant kSecUseAuthenticationUIAllow Specifies that authenticate UI can appear.
 917     @constant kSecUseAuthenticationUIFail Specifies that the error
 918         errSecInteractionNotAllowed will be returned if an item needs
 919         to authenticate with UI
 920     @constant kSecUseAuthenticationUIAllowSkip Specifies that all items which need
 921         to authenticate with UI will be silently skipped. This value can be used
 922         only with SecItemCopyMatching.
 923  */
 924 extern const CFStringRef kSecUseAuthenticationUIAllow
 925     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);
 926 extern const CFStringRef kSecUseAuthenticationUIFail
 927     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);
 928 extern const CFStringRef kSecUseAuthenticationUISkip
 929     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);
 930
 931 /*!
 932      @enum kSecAttrTokenID Value Constants
 933      @discussion Predefined item attribute constant used to get or set values
 934          in a dictionary. The kSecAttrTokenID constant is the key and its value
 935          can be kSecAttrTokenIDSecureEnclave.
 936      @constant kSecAttrTokenIDSecureEnclave Specifies well-known identifier of the
 937          token implemented using device's Secure Enclave. The only keychain items
 938          supported by the Secure Enclave token are 256-bit elliptic curve keys
 939          (kSecAttrKeyTypeEC).  Keys must be generated on the secure enclave using
 940          SecKeyGenerateKeyPair call with kSecAttrTokenID set to
 941          kSecAttrTokenIDSecureEnclave in the parameters dictionary, it is not
 942          possible to import pregenerated keys to kSecAttrTokenIDSecureEnclave token.
 943 */
 944 #if !RC_HIDE_J79 && !RC_HIDE_J80
 945 extern const CFStringRef kSecAttrTokenIDSecureEnclave
 946 __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_9_0);
 947 #else
 948 extern const CFStringRef kSecAttrTokenIDSecureEnclave
 949 __OSX_AVAILABLE_STARTING(__MAC_NA, __IPHONE_9_0);
 950 #endif
 951
 952 /*!
 953      @enum kSecAttrAccessGroup Value Constants
 954      @constant kSecAttrAccessGroupToken Represents well-known access group
 955          which contains items provided by external token (typically smart card).
 956          This may be used as a value for kSecAttrAccessGroup attribute. Every
 957          application has access to this access group so it is not needed to
 958          explicitly list it in keychain-access-groups entitlement, but application
 959          must explicitly state this access group in keychain queries in order to
 960          be able to access items from external tokens.
 961 */
 962 extern const CFStringRef kSecAttrAccessGroupToken
 963     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0);
 964
 965 /*!
 966     @function SecItemCopyMatching
 967     @abstract Returns one or more items which match a search query.
 968     @param query A dictionary containing an item class specification and
 969         optional attributes for controlling the search. See the "Keychain
 970         Search Attributes" section for a description of currently defined
 971         search attributes.
 972     @param result On return, a CFTypeRef reference to the found item(s). The
 973         exact type of the result is based on the search attributes supplied
 974         in the query, as discussed below.
 975     @result A result code. See "Security Error Codes" (SecBase.h).
 976     @discussion Attributes defining a search are specified by adding key/value
 977         pairs to the query dictionary.
 978
 979     A typical query consists of:
 980
 981       * a kSecClass key, whose value is a constant from the Class
 982         Constants section that specifies the class of item(s) to be searched
 983       * one or more keys from the "Attribute Key Constants" section, whose value
 984         is the attribute data to be matched
 985       * one or more keys from the "Search Constants" section, whose value is
 986         used to further refine the search
 987       * a key from the "Return Type Key Constants" section, specifying the type of
 988         results desired
 989
 990    Result types are specified as follows:
 991
 992       * To obtain the data of a matching item (CFDataRef), specify
 993         kSecReturnData with a value of kCFBooleanTrue.
 994       * To obtain the attributes of a matching item (CFDictionaryRef), specify
 995         kSecReturnAttributes with a value of kCFBooleanTrue.
 996       * To obtain a reference to a matching item (SecKeychainItemRef,
 997         SecKeyRef, SecCertificateRef, or SecIdentityRef), specify kSecReturnRef
 998         with a value of kCFBooleanTrue.
 999       * To obtain a persistent reference to a matching item (CFDataRef),
1000         specify kSecReturnPersistentRef with a value of kCFBooleanTrue. Note
1001         that unlike normal references, a persistent reference may be stored
1002         on disk or passed between processes.
1003       * If more than one of these result types is specified, the result is
1004         returned as a CFDictionaryRef containing all the requested data.
1005       * If a result type is not specified, no results are returned.
1006
1007     By default, this function returns only the first match found. To obtain
1008     more than one matching item at a time, specify kSecMatchLimit with a value
1009     greater than 1. The result will be a CFArrayRef containing up to that
1010     number of matching items; the items' types are described above.
1011
1012     To filter a provided list of items down to those matching the query,
1013     specify a kSecMatchItemList whose value is a CFArray of SecKeychainItemRef,
1014     SecKeyRef, SecCertificateRef, or SecIdentityRef items. The objects in the
1015     provided array must be of the same type.
1016
1017     To convert from a persistent item reference to a normal item reference,
1018     specify a kSecValuePersistentRef whose value a CFDataRef (the persistent
1019     reference), and a kSecReturnRef whose value is kCFBooleanTrue.
1020 */
1021 OSStatus SecItemCopyMatching(CFDictionaryRef query, CFTypeRef * __nullable CF_RETURNS_RETAINED result)
1022     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
1023
1024 /*!
1025     @function SecItemAdd
1026     @abstract Add one or more items to a keychain.
1027     @param attributes A dictionary containing an item class specification and
1028         optional entries specifying the item's attribute values. See the
1029         "Attribute Key Constants" section for a description of currently defined
1030         attributes.
1031     @param result On return, a CFTypeRef reference to the newly added item(s).
1032         The exact type of the result is based on the values supplied
1033         in attributes, as discussed below. Pass NULL if this result is not
1034         required.
1035     @result A result code. See "Security Error Codes" (SecBase.h).
1036     @discussion Attributes defining an item are specified by adding key/value
1037         pairs to the attributes dictionary.  To add multiple items to a keychain
1038         at once use the kSecUseItemList key with an array of items as its value.
1039         This is currently only supported for non password items.
1040
1041     Result types are specified as follows:
1042
1043       * To obtain the data of the added item (CFDataRef), specify
1044         kSecReturnData with a value of kCFBooleanTrue.
1045       * To obtain all the attributes of the added item (CFDictionaryRef),
1046         specify kSecReturnAttributes with a value of kCFBooleanTrue.
1047       * To obtain a reference to the added item (SecKeychainItemRef, SecKeyRef,
1048         SecCertificateRef, or SecIdentityRef), specify kSecReturnRef with a
1049         value of kCFBooleanTrue.
1050       * To obtain a persistent reference to the added item (CFDataRef), specify
1051         kSecReturnPersistentRef with a value of kCFBooleanTrue. Note that
1052         unlike normal references, a persistent reference may be stored on disk
1053         or passed between processes.
1054       * If more than one of these result types is specified, the result is
1055         returned as a CFDictionaryRef containing all the requested data.
1056       * If a result type is not specified, no results are returned.
1057 */
1058 OSStatus SecItemAdd(CFDictionaryRef attributes, CFTypeRef * __nullable CF_RETURNS_RETAINED result)
1059     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
1060
1061 /*!
1062     @function SecItemUpdate
1063     @abstract Modify zero or more items which match a search query.
1064     @param query A dictionary containing an item class specification and
1065         optional attributes for controlling the search. See the "Attribute
1066         Constants" and "Search Constants" sections for a description of
1067         currently defined search attributes.
1068     @param attributesToUpdate A dictionary containing one or more attributes
1069         whose values should be set to the ones specified. Only real keychain
1070         attributes are permitted in this dictionary (no "meta" attributes are
1071         allowed.) See the "Attribute Key Constants" section for a description of
1072         currently defined value attributes.
1073     @result A result code. See "Security Error Codes" (SecBase.h).
1074     @discussion Attributes defining a search are specified by adding key/value
1075         pairs to the query dictionary.
1076 */
1077 OSStatus SecItemUpdate(CFDictionaryRef query,
1078     CFDictionaryRef attributesToUpdate)
1079     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
1080
1081 /*!
1082     @function SecItemDelete
1083     @abstract Delete zero or more items which match a search query.
1084     @param query A dictionary containing an item class specification and
1085         optional attributes for controlling the search. See the "Attribute
1086         Constants" and "Search Constants" sections for a description of
1087         currently defined search attributes.
1088     @result A result code.  See "Security Error Codes" (SecBase.h).
1089     @discussion Attributes defining a search are specified by adding key/value
1090         pairs to the query dictionary.
1091
1092     By default, this function deletes all items matching the specified query.
1093     You can change this behavior by specifying one of the follow keys:
1094
1095       * To delete an item identified by a transient reference, specify
1096         kSecValueRef with a reference returned by using the kSecReturnRef
1097         key in a previous call to SecItemCopyMatching or SecItemAdd.
1098       * To delete an item identified by a persistent reference, specify
1099         kSecValuePersistentRef with a persistent reference returned by
1100         using the kSecReturnPersistentRef key to SecItemCopyMatching or
1101         SecItemAdd.
1102       * To delete multiple items specify kSecMatchItemList with an array
1103         of references.
1104       * If more than one of these result keys is specified, the behavior is
1105         undefined.
1106 */
1107 OSStatus SecItemDelete(CFDictionaryRef query)
1108     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
1109
1110 CF_IMPLICIT_BRIDGING_DISABLED
1111 CF_ASSUME_NONNULL_END
1112
1113 __END_DECLS
1114
1115 #endif /* !_SECURITY_SECITEM_H_ */