libsecurity_keychain/lib/SecItem.h

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