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