keychain/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 specified)
  89         kSecAttrAccessible (iOS; also OS X if kSecAttrSynchronizable specified)
  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 specified)
 108         kSecAttrAccessible (iOS; also OS X if kSecAttrSynchronizable specified)
 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 specified)
 145         kSecAttrAccessible (iOS; also OS X if kSecAttrSynchronizable specified)
 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. iOS only.
 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_AVAILABLE(macos(10.9), ios(4.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_AVAILABLE(macos(10.9), ios(4.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.
 774     @constant kSecAttrKeyTypeEC This is the legacy name for kSecAttrKeyTypeECSECPrimeRandom, new applications should not use it.
 775     @constant kSecAttrKeyTypeDSA (OSX only)
 776     @constant kSecAttrKeyTypeAES (OSX only)
 777     @constant kSecAttrKeyType3DES (OSX only)
 778     @constant kSecAttrKeyTypeRC4 (OSX only)
 779     @constant kSecAttrKeyTypeRC2 (OSX only)
 780     @constant kSecAttrKeyTypeCAST (OSX only)
 781     @constant kSecAttrKeyTypeECDSA (deprecated; use kSecAttrKeyTypeECSECPrimeRandom instead.) (OSX only)
 782 */
 783 extern const CFStringRef kSecAttrKeyTypeRSA
 784     API_AVAILABLE(macos(10.7), ios(2.0));
 785 extern const CFStringRef kSecAttrKeyTypeDSA
 786     API_AVAILABLE(macos(10.7), ios(NA), bridgeos(NA));
 787 extern const CFStringRef kSecAttrKeyTypeAES
 788     API_AVAILABLE(macos(10.7), ios(NA), bridgeos(NA));
 789 extern const CFStringRef kSecAttrKeyTypeDES
 790     API_AVAILABLE(macos(10.7), ios(NA), bridgeos(NA));
 791 extern const CFStringRef kSecAttrKeyType3DES
 792     API_AVAILABLE(macos(10.7), ios(NA), bridgeos(NA));
 793 extern const CFStringRef kSecAttrKeyTypeRC4
 794     API_AVAILABLE(macos(10.7), ios(NA), bridgeos(NA));
 795 extern const CFStringRef kSecAttrKeyTypeRC2
 796     API_AVAILABLE(macos(10.7), ios(NA), bridgeos(NA));
 797 extern const CFStringRef kSecAttrKeyTypeCAST
 798     API_AVAILABLE(macos(10.7), ios(NA), bridgeos(NA));
 799 extern const CFStringRef kSecAttrKeyTypeECDSA
 800     API_AVAILABLE(macos(10.7), ios(NA), bridgeos(NA));
 801 extern const CFStringRef kSecAttrKeyTypeEC
 802     API_AVAILABLE(macos(10.9), ios(4.0));
 803 extern const CFStringRef kSecAttrKeyTypeECSECPrimeRandom
 804     API_AVAILABLE(macos(10.12), ios(10.0));
 805
 806 /*
 807      @enum kSecAttrPRF Value Constants
 808      @discussion Predefined item attribute constants used to specify the PRF
 809      to use with SecKeyDeriveFromPassword. OS X only.
 810      @constant kSecAttrPRFHmacAlgSHA1
 811      @constant kSecAttrPRFHmacAlgSHA224
 812      @constant kSecAttrPRFHmacAlgSHA256
 813      @constant kSecAttrPRFHmacAlgSHA384
 814      @constant kSecAttrPRFHmacAlgSHA512
 815 */
 816 extern const CFStringRef kSecAttrPRFHmacAlgSHA1
 817     API_AVAILABLE(macos(10.7), ios(NA), bridgeos(NA));
 818 extern const CFStringRef kSecAttrPRFHmacAlgSHA224
 819     API_AVAILABLE(macos(10.7), ios(NA), bridgeos(NA));
 820 extern const CFStringRef kSecAttrPRFHmacAlgSHA256
 821     API_AVAILABLE(macos(10.7), ios(NA), bridgeos(NA));
 822 extern const CFStringRef kSecAttrPRFHmacAlgSHA384
 823     API_AVAILABLE(macos(10.7), ios(NA), bridgeos(NA));
 824 extern const CFStringRef kSecAttrPRFHmacAlgSHA512
 825       API_AVAILABLE(macos(10.7), ios(NA), bridgeos(NA));
 826
 827
 828 /*!
 829     @enum Search Constants
 830     @discussion Predefined search constants used to set values in a query
 831         dictionary. You can specify a combination of search attributes and
 832         item attributes when looking for matching items with the
 833         SecItemCopyMatching function.
 834     @constant kSecMatchPolicy Specifies a dictionary key whose value is a
 835         SecPolicyRef. If provided, returned certificates or identities must
 836         verify with this policy.
 837     @constant kSecMatchItemList OS X only. Specifies a dictionary key whose value is a
 838          CFArray of SecKeychainItemRef items. If provided, returned items will be
 839          limited to the subset which are contained in this list.
 840          @constant kSecMatchSearchList Specifies a dictionary key whose value is a
 841          CFArray of SecKeychainRef items. If provided, the search will be limited
 842          to the keychains contained in this list.
 843     @constant kSecMatchIssuers Specifies a dictionary key whose value is a
 844         CFArray of X.500 names (of type CFDataRef). If provided, returned
 845         certificates or identities will be limited to those whose
 846         certificate chain contains one of the issuers provided in this list.
 847     @constant kSecMatchEmailAddressIfPresent Specifies a dictionary key whose
 848         value is a CFStringRef containing an RFC822 email address. If
 849         provided, returned certificates or identities will be limited to those
 850         that contain the address, or do not contain any email address.
 851     @constant kSecMatchSubjectContains Specifies a dictionary key whose value
 852         is a CFStringRef. If provided, returned certificates or identities
 853         will be limited to those containing this string in the subject.
 854     @constant kSecMatchSubjectStartsWith OS X only. Specifies a dictionary key whose value
 855         is a CFStringRef. If provided, returned certificates or identities
 856         will be limited to those with subject names that start with this string.
 857     @constant kSecMatchSubjectEndsWith OS X only. Specifies a dictionary key whose value
 858          is a CFStringRef. If provided, returned certificates or identities
 859          will be limited to those with subject names that end with this string.
 860     @constant kSecMatchSubjectWholeString OS X only. Specifies a dictionary key whose
 861          value is a CFStringRef. If provided, returned certificates or identities
 862          will be limited to those matching this string exactly in the subject.
 863     @constant kSecMatchCaseInsensitive Specifies a dictionary key whose value
 864         is a CFBooleanRef. If this value is kCFBooleanFalse, or is not
 865         provided, then case-sensitive string matching is performed.
 866     @constant kSecMatchDiacriticInsensitive OS X only. Specifies a dictionary key whose
 867         value is a CFBooleanRef. If this value is kCFBooleanFalse, or is not
 868         provided, then diacritic-sensitive string matching is performed.
 869     @constant kSecMatchWidthInsensitive OS X only. Specifies a dictionary key whose
 870         value is a CFBooleanRef. If this value is kCFBooleanFalse, or is not
 871         provided, then string matching is width-sensitive (e.g. 'a' != 0xFF41).
 872     @constant kSecMatchTrustedOnly Specifies a dictionary key whose value is
 873         a CFBooleanRef. If provided with a value of kCFBooleanTrue, only
 874         certificates which can be verified back to a trusted anchor will be
 875         returned. If this value is kCFBooleanFalse, or is not provided, then
 876         both trusted and untrusted certificates may be returned.
 877     @constant kSecMatchValidOnDate Specifies a dictionary key whose value is
 878         of type CFDateRef. If provided, returned keys, certificates or
 879         identities will be limited to those which are valid for the given date.
 880         Pass a value of kCFNull to indicate the current date.
 881     @constant kSecMatchLimit Specifies a dictionary key whose value is a
 882         CFNumberRef. If provided, this value specifies the maximum number of
 883         results to return. If not provided, results are limited to the first
 884         item found. Predefined values are provided for a single item
 885         (kSecMatchLimitOne) and all matching items (kSecMatchLimitAll).
 886     @constant kSecMatchLimitOne Specifies that results are limited to the first
 887         item found; used as a value for the kSecMatchLimit dictionary key.
 888     @constant kSecMatchLimitAll Specifies that an unlimited number of results
 889         may be returned; used as a value for the kSecMatchLimit dictionary
 890         key.
 891 */
 892 extern const CFStringRef kSecMatchPolicy
 893     API_AVAILABLE(macos(10.6), ios(2.0));
 894 extern const CFStringRef kSecMatchItemList
 895     API_AVAILABLE(macos(10.6), ios(2.0));
 896 extern const CFStringRef kSecMatchSearchList
 897     API_AVAILABLE(macos(10.6), ios(2.0));
 898 extern const CFStringRef kSecMatchIssuers
 899     API_AVAILABLE(macos(10.6), ios(2.0));
 900 extern const CFStringRef kSecMatchEmailAddressIfPresent
 901     API_AVAILABLE(macos(10.6), ios(2.0));
 902 extern const CFStringRef kSecMatchSubjectContains
 903     API_AVAILABLE(macos(10.6), ios(2.0));
 904 extern const CFStringRef kSecMatchSubjectStartsWith
 905     API_AVAILABLE(macos(10.7), ios(NA), bridgeos(NA));
 906 extern const CFStringRef kSecMatchSubjectEndsWith
 907     API_AVAILABLE(macos(10.7), ios(NA), bridgeos(NA));
 908 extern const CFStringRef kSecMatchSubjectWholeString
 909     API_AVAILABLE(macos(10.7), ios(NA), bridgeos(NA));
 910 extern const CFStringRef kSecMatchCaseInsensitive
 911     API_AVAILABLE(macos(10.6), ios(2.0));
 912 extern const CFStringRef kSecMatchDiacriticInsensitive
 913     API_AVAILABLE(macos(10.7), ios(NA), bridgeos(NA));
 914 extern const CFStringRef kSecMatchWidthInsensitive
 915     API_AVAILABLE(macos(10.7), ios(NA), bridgeos(NA));
 916 extern const CFStringRef kSecMatchTrustedOnly
 917     API_AVAILABLE(macos(10.6), ios(2.0));
 918 extern const CFStringRef kSecMatchValidOnDate
 919     API_AVAILABLE(macos(10.6), ios(2.0));
 920 extern const CFStringRef kSecMatchLimit
 921     API_AVAILABLE(macos(10.6), ios(2.0));
 922 extern const CFStringRef kSecMatchLimitOne
 923     API_AVAILABLE(macos(10.6), ios(2.0));
 924 extern const CFStringRef kSecMatchLimitAll
 925     API_AVAILABLE(macos(10.6), ios(2.0));
 926
 927
 928 /*!
 929     @enum Return Type Key Constants
 930     @discussion Predefined return type keys used to set values in a dictionary.
 931         You use these keys to specify the type of results which should be
 932         returned by the SecItemCopyMatching or SecItemAdd function. You can
 933         specify zero or more of these return types. If more than one of these
 934         result types is specified, the result is returned as a CFDictionaryRef
 935         whose keys are the result types and values are the requested data.
 936     @constant kSecReturnData Specifies a dictionary key whose value is of type
 937         CFBooleanRef. A value of kCFBooleanTrue indicates that the data of
 938         an item (CFDataRef) should be returned. For keys and password
 939         items, data is secret (encrypted) and may require the user to enter
 940         a password for access.
 941     @constant kSecReturnAttributes Specifies a dictionary key whose value is
 942         of type CFBooleanRef. A value of kCFBooleanTrue indicates that the
 943         (non-encrypted) attributes of an item (CFDictionaryRef) should be
 944         returned.
 945     @constant kSecReturnRef Specifies a dictionary key whose value is a
 946         CFBooleanRef. A value of kCFBooleanTrue indicates that a reference
 947         should be returned. Depending on the item class requested, the
 948         returned reference(s) may be of type SecKeychainItemRef, SecKeyRef,
 949         SecCertificateRef, or SecIdentityRef.
 950     @constant kSecReturnPersistentRef Specifies a dictionary key whose value
 951         is of type CFBooleanRef. A value of kCFBooleanTrue indicates that a
 952         persistent reference to an item (CFDataRef) should be returned.
 953 */
 954 extern const CFStringRef kSecReturnData
 955     API_AVAILABLE(macos(10.6), ios(2.0));
 956 extern const CFStringRef kSecReturnAttributes
 957     API_AVAILABLE(macos(10.6), ios(2.0));
 958 extern const CFStringRef kSecReturnRef
 959     API_AVAILABLE(macos(10.6), ios(2.0));
 960 extern const CFStringRef kSecReturnPersistentRef
 961     API_AVAILABLE(macos(10.6), ios(2.0));
 962
 963
 964 /*!
 965     @enum Value Type Key Constants
 966     @discussion Predefined value type keys used to pass values in a dictionary.
 967         You can specify zero or more of these types depending on the function
 968         you are calling.  For SecItemCopyMatching or SecItemAdd these are
 969         used as keys in the results dictionary.
 970     @constant kSecValueData Specifies a dictionary key whose value is of type
 971         CFDataRef.  For keys and password items, data is secret (encrypted)
 972         and may require the user to enter a password for access.
 973     @constant kSecValueRef Specifies a dictionary key whose value, depending
 974         on the item class requested, is of type SecKeychainItemRef, SecKeyRef,
 975         SecCertificateRef, or SecIdentityRef.
 976     @constant kSecValuePersistentRef Specifies a dictionary key whose value
 977         is of type CFDataRef.  The bytes in this CFDataRef can be stored by
 978         the caller and used on a subsequent invocation of the application (or
 979         even a different application) to retrieve the item referenced by it.
 980 */
 981 extern const CFStringRef kSecValueData
 982     API_AVAILABLE(macos(10.6), ios(2.0));
 983 extern const CFStringRef kSecValueRef
 984     API_AVAILABLE(macos(10.6), ios(2.0));
 985 extern const CFStringRef kSecValuePersistentRef
 986     API_AVAILABLE(macos(10.6), ios(2.0));
 987
 988
 989 /*!
 990     @enum Other Constants
 991     @discussion Predefined constants used to set values in a dictionary.
 992     @constant kSecUseItemList Specifies a dictionary key whose value is a
 993         CFArray of items. If provided, this array is treated as the set of
 994         all possible items to search, or add if the API being called is
 995         SecItemAdd. The items in this array may be of type SecKeyRef,
 996         SecCertificateRef, SecIdentityRef, or CFDataRef (for a persistent
 997         item reference.) The items in the array must all be of the same
 998         type. When this attribute is provided, no keychains are searched.
 999     @constant kSecUseKeychain OS X only. Specifies a dictionary key whose value is a
1000         keychain reference. You use this key to specify a value of type
1001         SecKeychainRef to which SecItemAdd will add the provided item(s).
1002     @constant kSecUseOperationPrompt Specifies a dictionary key whose value
1003         is a CFStringRef that represents a user-visible string describing
1004         the operation for which the application is attempting to authenticate.
1005         The application is responsible for the text localization.
1006     @constant kSecUseNoAuthenticationUI OS X only. Specifies a dictionary key whose value
1007         is a CFBooleanRef. If provided with a value of kCFBooleanTrue, the error
1008         errSecInteractionNotAllowed will be returned if the item is attempting
1009         to authenticate with UI.
1010     @constant kSecUseAuthenticationUI Specifies a dictionary key whose value
1011         is one of kSecUseAuthenticationUIAllow, kSecUseAuthenticationUIFail, kSecUseAuthenticationUISkip.
1012     @constant kSecUseAuthenticationContext Specifies a dictionary key whose value
1013         is LAContext to be used for keychain item authentication.
1014         * If the item requires authentication and this key is omitted, a new context
1015           will be created just for the purpose of the single call.
1016         * If the specified context has been previously authenticated, the operation
1017           will succeed without asking user for authentication.
1018         * If the specified context has not been previously authenticated, the new
1019           authentication will be started on this context, allowing caller to
1020           eventually reuse the sucessfully authenticated context in subsequent
1021           keychain operations.
1022 */
1023 extern const CFStringRef kSecUseItemList
1024     API_AVAILABLE(macos(10.6)) API_UNAVAILABLE(ios, tvos, watchos);
1025 extern const CFStringRef kSecUseKeychain
1026     API_AVAILABLE(macos(10.7), ios(NA), bridgeos(NA));
1027 extern const CFStringRef kSecUseOperationPrompt
1028     API_AVAILABLE(macos(10.10), ios(8.0));
1029 extern const CFStringRef kSecUseNoAuthenticationUI
1030     API_DEPRECATED("Use kSecUseAuthenticationUI instead.", macos(10.10, 10.11), ios(8.0, 9.0));
1031 extern const CFStringRef kSecUseAuthenticationUI
1032     API_AVAILABLE(macos(10.11), ios(9.0));
1033 extern const CFStringRef kSecUseAuthenticationContext
1034     API_AVAILABLE(macos(10.11), ios(9.0));
1035
1036 /*!
1037     @enum kSecUseAuthenticationUI Value Constants
1038     @discussion Predefined item attribute constants used to get or set values
1039         in a dictionary. The kSecUseAuthenticationUI constant is the key and its
1040         value is one of the constants defined here.
1041         If the key kSecUseAuthenticationUI not provided then kSecUseAuthenticationUIAllow
1042         is used as default.
1043     @constant kSecUseAuthenticationUIAllow Specifies that authenticate UI can appear.
1044     @constant kSecUseAuthenticationUIFail Specifies that the error
1045         errSecInteractionNotAllowed will be returned if an item needs
1046         to authenticate with UI
1047     @constant kSecUseAuthenticationUIAllowSkip Specifies that all items which need
1048         to authenticate with UI will be silently skipped. This value can be used
1049         only with SecItemCopyMatching.
1050 */
1051 extern const CFStringRef kSecUseAuthenticationUIAllow
1052     API_AVAILABLE(macos(10.11), ios(9.0));
1053 extern const CFStringRef kSecUseAuthenticationUIFail
1054     API_AVAILABLE(macos(10.11), ios(9.0));
1055 extern const CFStringRef kSecUseAuthenticationUISkip
1056     API_AVAILABLE(macos(10.11), ios(9.0));
1057
1058 /*!
1059      @enum kSecAttrTokenID Value Constants
1060      @discussion Predefined item attribute constant used to get or set values
1061          in a dictionary. The kSecAttrTokenID constant is the key and its value
1062          can be kSecAttrTokenIDSecureEnclave.
1063      @constant kSecAttrTokenIDSecureEnclave Specifies well-known identifier of the
1064          token implemented using device's Secure Enclave. The only keychain items
1065          supported by the Secure Enclave token are 256-bit elliptic curve keys
1066          (kSecAttrKeyTypeEC).  Keys must be generated on the secure enclave using
1067          SecKeyGenerateKeyPair call with kSecAttrTokenID set to
1068          kSecAttrTokenIDSecureEnclave in the parameters dictionary, it is not
1069          possible to import pregenerated keys to kSecAttrTokenIDSecureEnclave token.
1070 */
1071 extern const CFStringRef kSecAttrTokenIDSecureEnclave
1072     API_AVAILABLE(macos(10.12), ios(9.0));
1073
1074 /*!
1075      @enum kSecAttrAccessGroup Value Constants
1076      @constant kSecAttrAccessGroupToken Represents well-known access group
1077          which contains items provided by external token (typically smart card).
1078          This may be used as a value for kSecAttrAccessGroup attribute. Every
1079          application has access to this access group so it is not needed to
1080          explicitly list it in keychain-access-groups entitlement, but application
1081          must explicitly state this access group in keychain queries in order to
1082          be able to access items from external tokens.
1083 */
1084 extern const CFStringRef kSecAttrAccessGroupToken
1085     API_AVAILABLE(macos(10.12), ios(10.0));
1086
1087 /*!
1088     @function SecItemCopyMatching
1089     @abstract Returns one or more items which match a search query.
1090     @param query A dictionary containing an item class specification and
1091         optional attributes for controlling the search. See the "Keychain
1092         Search Attributes" section for a description of currently defined
1093         search attributes.
1094     @param result On return, a CFTypeRef reference to the found item(s). The
1095         exact type of the result is based on the search attributes supplied
1096         in the query, as discussed below.
1097     @result A result code. See "Security Error Codes" (SecBase.h).
1098     @discussion Attributes defining a search are specified by adding key/value
1099         pairs to the query dictionary.
1100
1101     A typical query consists of:
1102
1103       * a kSecClass key, whose value is a constant from the Class
1104         Constants section that specifies the class of item(s) to be searched
1105       * one or more keys from the "Attribute Key Constants" section, whose value
1106         is the attribute data to be matched
1107       * one or more keys from the "Search Constants" section, whose value is
1108         used to further refine the search
1109       * a key from the "Return Type Key Constants" section, specifying the type of
1110         results desired
1111
1112    Result types are specified as follows:
1113
1114       * To obtain the data of a matching item (CFDataRef), specify
1115         kSecReturnData with a value of kCFBooleanTrue.
1116       * To obtain the attributes of a matching item (CFDictionaryRef), specify
1117         kSecReturnAttributes with a value of kCFBooleanTrue.
1118       * To obtain a reference to a matching item (SecKeychainItemRef,
1119         SecKeyRef, SecCertificateRef, or SecIdentityRef), specify kSecReturnRef
1120         with a value of kCFBooleanTrue.
1121       * To obtain a persistent reference to a matching item (CFDataRef),
1122         specify kSecReturnPersistentRef with a value of kCFBooleanTrue. Note
1123         that unlike normal references, a persistent reference may be stored
1124         on disk or passed between processes.
1125       * If more than one of these result types is specified, the result is
1126         returned as a CFDictionaryRef containing all the requested data.
1127       * If a result type is not specified, no results are returned.
1128
1129     By default, this function returns only the first match found. To obtain
1130     more than one matching item at a time, specify kSecMatchLimit with a value
1131     greater than 1. The result will be a CFArrayRef containing up to that
1132     number of matching items; the items' types are described above.
1133
1134     To filter a provided list of items down to those matching the query,
1135     specify a kSecMatchItemList whose value is a CFArray of SecKeychainItemRef,
1136     SecKeyRef, SecCertificateRef, or SecIdentityRef items. The objects in the
1137     provided array must be of the same type.
1138
1139     On iOS, to convert from a persistent item reference to a normal item reference,
1140     specify a kSecValuePersistentRef whose value a CFDataRef (the persistent
1141     reference), and a kSecReturnRef whose value is kCFBooleanTrue.
1142
1143     On OSX, to convert from persistent item references to normal item references,
1144     specify a kSecMatchItemList whose value is a CFArray containing one or
1145     more CFDataRef elements (the persistent reference), and a kSecReturnRef
1146     whose value is kCFBooleanTrue. The objects in the provided array must be
1147     of the same type.
1148 */
1149 OSStatus SecItemCopyMatching(CFDictionaryRef query, CFTypeRef * __nullable CF_RETURNS_RETAINED result)
1150     API_AVAILABLE(macos(10.6), ios(2.0));
1151
1152 /*!
1153     @function SecItemAdd
1154     @abstract Add one or more items to a keychain.
1155     @param attributes A dictionary containing an item class specification and
1156         optional entries specifying the item's attribute values. See the
1157         "Attribute Key Constants" section for a description of currently defined
1158         attributes.
1159     @param result On return, a CFTypeRef reference to the newly added item(s).
1160         The exact type of the result is based on the values supplied
1161         in attributes, as discussed below. Pass NULL if this result is not
1162         required.
1163     @result A result code. See "Security Error Codes" (SecBase.h).
1164     @discussion Attributes defining an item are specified by adding key/value
1165         pairs to the attributes dictionary.  To add multiple items to a keychain
1166         at once use the kSecUseItemList key with an array of items as its value.
1167         This is currently only supported for non password items.
1168
1169         On OSX, To add an item to a particular keychain, supply kSecUseKeychain
1170         with a SecKeychainRef as its value.
1171
1172     Result types are specified as follows:
1173
1174       * To obtain the data of the added item (CFDataRef), specify
1175         kSecReturnData with a value of kCFBooleanTrue.
1176       * To obtain all the attributes of the added item (CFDictionaryRef),
1177         specify kSecReturnAttributes with a value of kCFBooleanTrue.
1178       * To obtain a reference to the added item (SecKeychainItemRef, SecKeyRef,
1179         SecCertiicateRef, or SecIdentityRef), specify kSecReturnRef with a
1180         value of kCFBooleanTrue.
1181       * To obtain a persistent reference to the added item (CFDataRef), specify
1182         kSecReturnPersistentRef with a value of kCFBooleanTrue. Note that
1183         unlike normal references, a persistent reference may be stored on disk
1184         or passed between processes.
1185       * If more than one of these result types is specified, the result is
1186         returned as a CFDictionaryRef containing all the requested data.
1187       * On iOS, if a result type is not specified, no results are returned.
1188         On OSX, the added item is returned.
1189 */
1190 OSStatus SecItemAdd(CFDictionaryRef attributes, CFTypeRef * __nullable CF_RETURNS_RETAINED result)
1191     API_AVAILABLE(macos(10.6), ios(2.0));
1192
1193 /*!
1194     @function SecItemUpdate
1195     @abstract Modify zero or more items which match a search query.
1196     @param query A dictionary containing an item class specification and
1197         optional attributes for controlling the search. See the "Attribute
1198         Constants" and "Search Constants" sections for a description of
1199         currently defined search attributes.
1200     @param attributesToUpdate A dictionary containing one or more attributes
1201         whose values should be set to the ones specified. Only real keychain
1202         attributes are permitted in this dictionary (no "meta" attributes are
1203         allowed.) See the "Attribute Key Constants" section for a description of
1204         currently defined value attributes.
1205     @result A result code. See "Security Error Codes" (SecBase.h).
1206     @discussion Attributes defining a search are specified by adding key/value
1207         pairs to the query dictionary.
1208 */
1209 OSStatus SecItemUpdate(CFDictionaryRef query, CFDictionaryRef attributesToUpdate)
1210     API_AVAILABLE(macos(10.6), ios(2.0));
1211
1212 /*!
1213     @function SecItemDelete
1214     @abstract Delete zero or more items which match a search query.
1215     @param query A dictionary containing an item class specification and
1216         optional attributes for controlling the search. See the "Attribute
1217         Constants" and "Search Constants" sections for a description of
1218         currently defined search attributes.
1219     @result A result code.  See "Security Error Codes" (SecBase.h).
1220     @discussion Attributes defining a search are specified by adding key/value
1221         pairs to the query dictionary.
1222
1223     By default, this function deletes all items matching the specified query.
1224     You can change this behavior by specifying one of the follow keys:
1225
1226       * To delete an item identified by a transient reference, on iOS, specify
1227         kSecValueRef with a item reference. On OS X, give a kSecMatchItemList
1228         containing an item reference.
1229       * To delete an item identified by a persistent reference, on iOS, specify
1230         kSecValuePersistentRef with a persistent reference returned by
1231         using the kSecReturnPersistentRef key to SecItemCopyMatching or
1232         SecItemAdd. on OSX, use kSecMatchItemList with a persistent reference
1233         returned by using the kSecReturnPersistentRef key with
1234         SecItemCopyMatching or SecItemAdd.
1235       * To delete multiple items specify kSecMatchItemList with an array
1236         of references.
1237       * If more than one of these result keys is specified, the behavior is
1238         undefined.
1239 */
1240 OSStatus SecItemDelete(CFDictionaryRef query)
1241     API_AVAILABLE(macos(10.6), ios(2.0));
1242
1243 CF_IMPLICIT_BRIDGING_DISABLED
1244 CF_ASSUME_NONNULL_END
1245
1246 __END_DECLS
1247
1248 #endif /* !_SECURITY_SECITEM_H_ */