sec/Security/SecItem.h

   1 /*
   2  * Copyright (c) 2006-2010 Apple Inc. All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 /*!
  25     @header SecItem
  26     SecItem defines CoreFoundation-based constants and functions for
  27     access to Security items (certificates, keys, identities, and
  28     passwords.)
  29 */
  30
  31 #ifndef _SECURITY_SECITEM_H_
  32 #define _SECURITY_SECITEM_H_
  33
  34 #include <Security/SecBase.h>
  35 #include <CoreFoundation/CFArray.h>
  36 #include <CoreFoundation/CFDictionary.h>
  37
  38 #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 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.
  59     @constant kSecClassGenericPassword Specifies generic password items.
  60     @constant kSecClassInternetPassword Specifies Internet password items.
  61     @constant kSecClassCertificate Specifies certificate items.
  62     @constant kSecClassKey Specifies key items.
  63     @constant kSecClassIdentity Specifies identity items.
  64 */
  65 extern CFTypeRef kSecClassGenericPassword
  66     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
  67 extern CFTypeRef kSecClassInternetPassword
  68     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
  69 extern CFTypeRef kSecClassCertificate
  70     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
  71 extern CFTypeRef kSecClassKey
  72     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
  73 extern CFTypeRef kSecClassIdentity
  74     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
  75
  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         kSecAttrAccessible
  85         kSecAttrAccessGroup
  86         kSecAttrCreationDate
  87         kSecAttrModificationDate
  88         kSecAttrDescription
  89         kSecAttrComment
  90         kSecAttrCreator
  91         kSecAttrType
  92         kSecAttrLabel
  93         kSecAttrIsInvisible
  94         kSecAttrIsNegative
  95         kSecAttrAccount
  96         kSecAttrService
  97         kSecAttrGeneric
  98
  99     kSecClassInternetPassword item attributes:
 100         kSecAttrAccessible
 101         kSecAttrAccessGroup
 102         kSecAttrCreationDate
 103         kSecAttrModificationDate
 104         kSecAttrDescription
 105         kSecAttrComment
 106         kSecAttrCreator
 107         kSecAttrType
 108         kSecAttrLabel
 109         kSecAttrIsInvisible
 110         kSecAttrIsNegative
 111         kSecAttrAccount
 112         kSecAttrSecurityDomain
 113         kSecAttrServer
 114         kSecAttrProtocol
 115         kSecAttrAuthenticationType
 116         kSecAttrPort
 117         kSecAttrPath
 118
 119     kSecClassCertificate item attributes:
 120         kSecAttrAccessible
 121         kSecAttrAccessGroup
 122         kSecAttrCertificateType
 123         kSecAttrCertificateEncoding
 124         kSecAttrLabel
 125         kSecAttrSubject
 126         kSecAttrIssuer
 127         kSecAttrSerialNumber
 128         kSecAttrSubjectKeyID
 129         kSecAttrPublicKeyHash
 130
 131     kSecClassKey item attributes:
 132         kSecAttrAccessible
 133         kSecAttrAccessGroup
 134         kSecAttrKeyClass
 135         kSecAttrLabel
 136         kSecAttrApplicationLabel
 137         kSecAttrIsPermanent
 138         kSecAttrApplicationTag
 139         kSecAttrKeyType
 140         kSecAttrKeySizeInBits
 141         kSecAttrEffectiveKeySize
 142         kSecAttrCanEncrypt
 143         kSecAttrCanDecrypt
 144         kSecAttrCanDerive
 145         kSecAttrCanSign
 146         kSecAttrCanVerify
 147         kSecAttrCanWrap
 148         kSecAttrCanUnwrap
 149
 150     kSecClassIdentity item attributes:
 151         Since an identity is the combination of a private key and a
 152         certificate, this class shares attributes of both kSecClassKey and
 153         kSecClassCertificate.
 154
 155     @constant kSecAttrAccessible Specifies a dictionary key whose value
 156         indicates when your application needs access to an items data.  You
 157         should choose the most restrictive option that meets your applications
 158         needs to allow the system to protect that item in the best way
 159         possible.
 160     @constant kSecAttrAccessGroup Specifies a dictionary key whose value is
 161         a CFStringRef indicating which access group an item is in.  The access
 162         groups that a particular application has access to are determined by
 163         two entitlements for that application.  The application-identifier
 164         entitlement contains the applications single access group, unless
 165         there is a keychain-access-groups entitlement present.  The latter
 166         has as its value a list of access groups.   The first (or only)
 167         access group an application is in is the default one new items are
 168         created in.  By default SecItemCopyMatching searches all the access
 169         groups an item is a member of.  Specifying this attribute to
 170         SecItemAdd, changes the access group an item will be added to, or
 171         limits which access groups are searched for SecItemUpdate,
 172         SecItemDelete or SecItemCopyMatching calls.  To share keychain items
 173         between multiple applications they need to have a common group listed
 174         in their keychain-access-groups entitlement, and they must both specify
 175         this shared access group name as the value for this key in the
 176         dictionary passed to SecItemAdd().
 177     @constant kSecAttrCreationDate (read-only) Specifies a dictionary key whose
 178         value is the item's creation date. You use this key to get a value
 179         of type CFDateRef that represents the date the item was created.
 180     @constant kSecAttrModificationDate (read-only) Specifies a dictionary key
 181         whose value is the item's modification date. You use this key to get
 182         a value of type CFDateRef that represents the last time the item was
 183         updated.
 184     @constant kSecAttrDescription Specifies a dictionary key whose value is
 185         the item's description attribute. You use this key to set or get a
 186         value of type CFStringRef that represents a user-visible string
 187         describing this particular kind of item (e.g., "disk image password").
 188     @constant kSecAttrComment Specifies a dictionary key whose value is the
 189         item's comment attribute. You use this key to set or get a value of
 190         type CFStringRef containing the user-editable comment for this item.
 191     @constant kSecAttrCreator Specifies a dictionary key whose value is the
 192         item's creator attribute. You use this key to set or get a value of
 193         type CFNumberRef that represents the item's creator. This number is
 194         the unsigned integer representation of a four-character code (e.g.,
 195         'aCrt').
 196     @constant kSecAttrType Specifies a dictionary key whose value is the item's
 197         type attribute. You use this key to set or get a value of type
 198         CFNumberRef that represents the item's type. This number is the
 199         unsigned integer representation of a four-character code (e.g.,
 200         'aTyp').
 201     @constant kSecAttrLabel Specifies a dictionary key whose value is the
 202         item's label attribute. You use this key to set or get a value of
 203         type CFStringRef containing the user-visible label for this item.
 204     @constant kSecAttrIsInvisible Specifies a dictionary key whose value is the
 205         item's invisible attribute. You use this key to set or get a value
 206         of type CFBooleanRef that indicates whether the item is invisible
 207         (i.e., should not be displayed.)
 208     @constant kSecAttrIsNegative Specifies a dictionary key whose value is the
 209         item's negative attribute. You use this key to set or get a value of
 210         type CFBooleanRef that indicates whether there is a valid password
 211         associated with this keychain item. This is useful if your application
 212         doesn't want a password for some particular service to be stored in
 213         the keychain, but prefers that it always be entered by the user.
 214     @constant kSecAttrAccount Specifies a dictionary key whose value is the
 215         item's account attribute. You use this key to set or get a CFStringRef
 216         that contains an account name. (Items of class
 217         kSecClassGenericPassword, kSecClassInternetPassword have this
 218         attribute.)
 219     @constant kSecAttrService Specifies a dictionary key whose value is the
 220         item's service attribute. You use this key to set or get a CFStringRef
 221         that represents the service associated with this item. (Items of class
 222         kSecClassGenericPassword have this attribute.)
 223     @constant kSecAttrGeneric Specifies a dictionary key whose value is the
 224         item's generic attribute. You use this key to set or get a value of
 225         CFDataRef that contains a user-defined attribute. (Items of class
 226         kSecClassGenericPassword have this attribute.)
 227     @constant kSecAttrSecurityDomain Specifies a dictionary key whose value
 228         is the item's security domain attribute. You use this key to set or
 229         get a CFStringRef value that represents the Internet security domain.
 230         (Items of class kSecClassInternetPassword have this attribute.)
 231     @constant kSecAttrServer Specifies a dictionary key whose value is the
 232         item's server attribute. You use this key to set or get a value of
 233         type CFStringRef that contains the server's domain name or IP address.
 234         (Items of class kSecClassInternetPassword have this attribute.)
 235     @constant kSecAttrProtocol Specifies a dictionary key whose value is the
 236         item's protocol attribute. You use this key to set or get a value of
 237         type CFNumberRef that denotes the protocol for this item (see the
 238         SecProtocolType enum in SecKeychainItem.h). (Items of class
 239         kSecClassInternetPassword have this attribute.)
 240     @constant kSecAttrAuthenticationType Specifies a dictionary key whose value
 241         is the item's authentication type attribute. You use this key to set
 242         or get a value of type CFNumberRef that denotes the authentication
 243         scheme for this item (see the kSecAttrAuthenticationType value
 244                 constants below).
 245     @constant kSecAttrPort Specifies a dictionary key whose value is the item's
 246         port attribute. You use this key to set or get a CFNumberRef value
 247         that represents an Internet port number. (Items of class
 248         kSecClassInternetPassword have this attribute.)
 249     @constant kSecAttrPath Specifies a dictionary key whose value is the item's
 250         path attribute, typically this is the path component of the URL.  You use
 251         this key to set or get a CFStringRef value that represents a path. (Items
 252         of class kSecClassInternetPassword have this attribute.)
 253     @constant kSecAttrSubject (read-only) Specifies a dictionary key whose
 254         value is the item's subject. You use this key to get a value of type
 255         CFDataRef that contains the X.500 subject name of a certificate.
 256         (Items of class kSecClassCertificate have this attribute.)
 257     @constant kSecAttrIssuer (read-only) Specifies a dictionary key whose value
 258         is the item's issuer. You use this key to get a value of type
 259         CFDataRef that contains the X.500 issuer name of a certificate. (Items
 260         of class kSecClassCertificate have this attribute.)
 261     @constant kSecAttrSerialNumber (read-only) Specifies a dictionary key whose
 262         value is the item's serial number.  You use this key to get a value
 263         of type CFDataRef that contains the serial number data of a
 264         certificate. (Items of class kSecClassCertificate have this
 265         attribute.)
 266     @constant kSecAttrSubjectKeyID (read-only) Specifies a dictionary key whose
 267         value is the item's subject key ID. You use this key to get a value
 268         of type CFDataRef that contains the subject key ID of a certificate.
 269         (Items of class kSecClassCertificate have this attribute.)
 270     @constant kSecAttrPublicKeyHash (read-only) Specifies a dictionary key
 271         whose value is the item's public key hash. You use this key to get a
 272         value of type CFDataRef that contains the hash of a certificate's
 273         public key. (Items of class kSecClassCertificate have this attribute.)
 274     @constant kSecAttrCertificateType (read-only) Specifies a dictionary key
 275         whose value is the item's certificate type. You use this key to get
 276         a value of type CFNumberRef that denotes the certificate type
 277         (Currently only the value of this attribute must be equal to the
 278         version of the X509 certificate.  So 1 for v1 2 for v2 and 3 for v3
 279         certificates). Only items of class kSecClassCertificate have this
 280         attribute.
 281     @constant kSecAttrCertificateEncoding (read-only) Specifies a dictionary
 282         key whose value is the item's certificate encoding. You use this key
 283         to get a value of type CFNumberRef that denotes the certificate
 284         encoding (Currently only the value 3 meaning
 285         kSecAttrCertificateEncodingDER is supported). Only items of class
 286         kSecClassCertificate have this attribute.
 287     @constant kSecAttrKeyClass (read only) Specifies a dictionary key whose
 288         value is one of kSecAttrKeyClassPublic, kSecAttrKeyClassPrivate or
 289         kSecAttrKeyClassSymmetric.
 290     @constant kSecAttrApplicationLabel Specifies a dictionary key whose value
 291         is the key's application label attribute. This is different from the
 292         kSecAttrLabel (which is intended to be human-readable). This attribute
 293         is used to look up a key programmatically; in particular, for keys of
 294         class kSecAttrKeyClassPublic and kSecAttrKeyClassPrivate, the value of
 295         this attribute is the hash of the public key.
 296     @constant kSecAttrIsPermanent Specifies a dictionary key whose value is a
 297         CFBooleanRef indicating whether the key in question will be stored
 298         permanently.
 299     @constant kSecAttrApplicationTag Specifies a dictionary key whose value is a
 300         CFDataRef containing private tag data.
 301     @constant kSecAttrKeyType Specifies a dictionary key whose value is a
 302         CFNumberRef indicating the algorithm associated with this key
 303         (Currently only the value 42 is supported, alternatively you can use
 304         kSecAttrKeyTypeRSA).
 305     @constant kSecAttrKeySizeInBits Specifies a dictionary key whose value
 306         is a CFNumberRef indicating the number of bits in this key.
 307     @constant kSecAttrEffectiveKeySize Specifies a dictionary key whose value
 308         is a CFNumberRef indicating the effective number of bits in this key.
 309         For example, a DES key has a kSecAttrKeySizeInBits of 64, but a
 310         kSecAttrEffectiveKeySize of 56 bits.
 311     @constant kSecAttrCanEncrypt Specifies a dictionary key whole value is a
 312         CFBooleanRef indicating whether the key in question can be used to
 313         encrypt data.
 314     @constant kSecAttrCanDecrypt Specifies a dictionary key whose value is a
 315         CFBooleanRef indicating whether the key in question can be used to
 316         decrypt data.
 317     @constant kSecAttrCanDerive Specifies a dictionary key whole value is a
 318         CFBooleanRef indicating whether the key in question can be used to
 319         derive another key.
 320     @constant kSecAttrCanSign Specifies a dictionary key whole value is a
 321         CFBooleanRef indicating whether the key in question can be used to
 322         create a digital signature.
 323     @constant kSecAttrCanVerify Specifies a dictionary key whole value is a
 324         CFBooleanRef indicating whether the key in question can be used to
 325         verify a digital signature.
 326     @constant kSecAttrCanWrap Specifies a dictionary key whole value is a
 327         CFBooleanRef indicating whether the key in question can be used to
 328         wrap another key.
 329     @constant kSecAttrCanUnwrap Specifies a dictionary key whole value is a
 330         CFBooleanRef indicating whether the key in question can be used to
 331         unwrap another key.
 332 */
 333 extern CFTypeRef kSecAttrAccessible
 334     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_4_0);
 335 extern CFTypeRef kSecAttrAccessGroup
 336     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_3_0);
 337 extern CFTypeRef kSecAttrCreationDate
 338     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 339 extern CFTypeRef kSecAttrModificationDate
 340     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 341 extern CFTypeRef kSecAttrDescription
 342     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 343 extern CFTypeRef kSecAttrComment
 344     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 345 extern CFTypeRef kSecAttrCreator
 346     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 347 extern CFTypeRef kSecAttrType
 348     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 349 extern CFTypeRef kSecAttrLabel
 350     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 351 extern CFTypeRef kSecAttrIsInvisible
 352     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 353 extern CFTypeRef kSecAttrIsNegative
 354     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 355 extern CFTypeRef kSecAttrAccount
 356     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 357 extern CFTypeRef kSecAttrService
 358     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 359 extern CFTypeRef kSecAttrGeneric
 360     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 361 extern CFTypeRef kSecAttrSecurityDomain
 362     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 363 extern CFTypeRef kSecAttrServer
 364     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 365 extern CFTypeRef kSecAttrProtocol
 366     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 367 extern CFTypeRef kSecAttrAuthenticationType
 368     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 369 extern CFTypeRef kSecAttrPort
 370     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 371 extern CFTypeRef kSecAttrPath
 372     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 373 extern CFTypeRef kSecAttrSubject
 374     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 375 extern CFTypeRef kSecAttrIssuer
 376     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 377 extern CFTypeRef kSecAttrSerialNumber
 378     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 379 extern CFTypeRef kSecAttrSubjectKeyID
 380     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 381 extern CFTypeRef kSecAttrPublicKeyHash
 382     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 383 extern CFTypeRef kSecAttrCertificateType
 384     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 385 extern CFTypeRef kSecAttrCertificateEncoding
 386     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 387 extern CFTypeRef kSecAttrKeyClass
 388     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 389 extern CFTypeRef kSecAttrApplicationLabel
 390     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 391 extern CFTypeRef kSecAttrIsPermanent
 392     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 393 extern CFTypeRef kSecAttrApplicationTag
 394     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 395 extern CFTypeRef kSecAttrKeyType
 396     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 397 extern CFTypeRef kSecAttrKeySizeInBits
 398     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 399 extern CFTypeRef kSecAttrEffectiveKeySize
 400     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 401 extern CFTypeRef kSecAttrCanEncrypt
 402     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 403 extern CFTypeRef kSecAttrCanDecrypt
 404     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 405 extern CFTypeRef kSecAttrCanDerive
 406     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 407 extern CFTypeRef kSecAttrCanSign
 408     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 409 extern CFTypeRef kSecAttrCanVerify
 410     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 411 extern CFTypeRef kSecAttrCanWrap
 412     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 413 extern CFTypeRef kSecAttrCanUnwrap
 414     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 415
 416 /*!
 417     @enum kSecAttrAccessible Value Constants
 418     @discussion Predefined item attribute constants used to get or set values
 419         in a dictionary. The kSecAttrAccessible constant is the key and its
 420         value is one of the constants defined here.
 421         When ask SecItemCopyMatching to return the items data the error
 422         errSecInteractionNotAllowed will be returned if the items data is not
 423         available until a device unlock occurs.
 424     @constant kSecAttrAccessibleWhenUnlocked item's data can only be accessed
 425         while the device is unlocked. This is recommended for items that only
 426         need be accesible while the application is in the foreground.  Items
 427         with this attribute will migrate to a new device when using encrypted
 428         backups.
 429     @constant kSecAttrAccessibleAfterFirstUnlock item's data can only be
 430         accessed once the device has been unlocked after a restart.  This is
 431         recommended for items that need to be accesible by background
 432         applications. Items with this attribute will migrate to a new device
 433         when using encrypted backups.
 434     @constant kSecAttrAccessibleAlways item's data can always be accessed
 435         regardless of the lock state of the device.  This is not recommended
 436         for anything except system use. Items with this attribute will migrate
 437         to a new device when using encrypted backups.
 438     @constant kSecAttrAccessibleWhenUnlockedThisDeviceOnly item's data can only
 439         be accessed while the device is unlocked. This is recommended for items
 440         that only need be accesible while the application is in the foreground.
 441         Items with this attribute will never migrate to a new device, so after
 442         a backup is restored to a new device these items will be missing.
 443     @constant kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly item's data can
 444         only be accessed once the device has been unlocked after a restart.
 445         This is recommended for items that need to be accessible by background
 446         applications. Items with this attribute will never migrate to a new
 447         device, so after a backup is restored to a new device these items will
 448         be missing.
 449     @constant kSecAttrAccessibleAlwaysThisDeviceOnly item's data can
 450         always be accessed regardless of the lock state of the device.  This
 451         is not recommended for anything except system use. Items with this
 452         attribute will never migrate to a new device, so after a backup is
 453         restored to a new device these items will be missing.
 454 */
 455 extern CFTypeRef kSecAttrAccessibleWhenUnlocked
 456     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_4_0);
 457 extern CFTypeRef kSecAttrAccessibleAfterFirstUnlock
 458     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_4_0);
 459 extern CFTypeRef kSecAttrAccessibleAlways
 460     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_4_0);
 461 extern CFTypeRef kSecAttrAccessibleWhenUnlockedThisDeviceOnly
 462     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_4_0);
 463 extern CFTypeRef kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
 464     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_4_0);
 465 extern CFTypeRef kSecAttrAccessibleAlwaysThisDeviceOnly
 466     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_4_0);
 467
 468 /*!
 469     @enum kSecAttrProtocol Value Constants
 470     @discussion Predefined item attribute constants used to get or set values
 471                 in a dictionary. The kSecAttrProtocol constant is the key and its
 472                 value is one of the constants defined here.
 473     @constant kSecAttrProtocolFTP.
 474     @constant kSecAttrProtocolFTPAccount.
 475     @constant kSecAttrProtocolHTTP.
 476     @constant kSecAttrProtocolIRC.
 477     @constant kSecAttrProtocolNNTP.
 478     @constant kSecAttrProtocolPOP3.
 479     @constant kSecAttrProtocolSMTP.
 480     @constant kSecAttrProtocolSOCKS.
 481     @constant kSecAttrProtocolIMAP.
 482     @constant kSecAttrProtocolLDAP.
 483     @constant kSecAttrProtocolAppleTalk.
 484     @constant kSecAttrProtocolAFP.
 485     @constant kSecAttrProtocolTelnet.
 486     @constant kSecAttrProtocolSSH.
 487     @constant kSecAttrProtocolFTPS.
 488     @constant kSecAttrProtocolHTTPS.
 489     @constant kSecAttrProtocolHTTPProxy.
 490     @constant kSecAttrProtocolHTTPSProxy.
 491     @constant kSecAttrProtocolFTPProxy.
 492     @constant kSecAttrProtocolSMB.
 493     @constant kSecAttrProtocolRTSP.
 494     @constant kSecAttrProtocolRTSPProxy.
 495     @constant kSecAttrProtocolDAAP.
 496     @constant kSecAttrProtocolEPPC.
 497     @constant kSecAttrProtocolIPP.
 498     @constant kSecAttrProtocolNNTPS.
 499     @constant kSecAttrProtocolLDAPS.
 500     @constant kSecAttrProtocolTelnetS.
 501     @constant kSecAttrProtocolIMAPS.
 502     @constant kSecAttrProtocolIRCS.
 503     @constant kSecAttrProtocolPOP3S.
 504 */
 505 extern CFTypeRef kSecAttrProtocolFTP
 506     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 507 extern CFTypeRef kSecAttrProtocolFTPAccount
 508     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 509 extern CFTypeRef kSecAttrProtocolHTTP
 510     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 511 extern CFTypeRef kSecAttrProtocolIRC
 512     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 513 extern CFTypeRef kSecAttrProtocolNNTP
 514     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 515 extern CFTypeRef kSecAttrProtocolPOP3
 516     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 517 extern CFTypeRef kSecAttrProtocolSMTP
 518     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 519 extern CFTypeRef kSecAttrProtocolSOCKS
 520     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 521 extern CFTypeRef kSecAttrProtocolIMAP
 522     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 523 extern CFTypeRef kSecAttrProtocolLDAP
 524     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 525 extern CFTypeRef kSecAttrProtocolAppleTalk
 526     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 527 extern CFTypeRef kSecAttrProtocolAFP
 528     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 529 extern CFTypeRef kSecAttrProtocolTelnet
 530     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 531 extern CFTypeRef kSecAttrProtocolSSH
 532     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 533 extern CFTypeRef kSecAttrProtocolFTPS
 534     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 535 extern CFTypeRef kSecAttrProtocolHTTPS
 536     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 537 extern CFTypeRef kSecAttrProtocolHTTPProxy
 538     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 539 extern CFTypeRef kSecAttrProtocolHTTPSProxy
 540     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 541 extern CFTypeRef kSecAttrProtocolFTPProxy
 542     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 543 extern CFTypeRef kSecAttrProtocolSMB
 544     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 545 extern CFTypeRef kSecAttrProtocolRTSP
 546     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 547 extern CFTypeRef kSecAttrProtocolRTSPProxy
 548     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 549 extern CFTypeRef kSecAttrProtocolDAAP
 550     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 551 extern CFTypeRef kSecAttrProtocolEPPC
 552     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 553 extern CFTypeRef kSecAttrProtocolIPP
 554     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 555 extern CFTypeRef kSecAttrProtocolNNTPS
 556     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 557 extern CFTypeRef kSecAttrProtocolLDAPS
 558     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 559 extern CFTypeRef kSecAttrProtocolTelnetS
 560     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 561 extern CFTypeRef kSecAttrProtocolIMAPS
 562     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 563 extern CFTypeRef kSecAttrProtocolIRCS
 564     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 565 extern CFTypeRef kSecAttrProtocolPOP3S
 566     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 567
 568 /*!
 569     @enum kSecAttrAuthenticationType Value Constants
 570     @discussion Predefined item attribute constants used to get or set values
 571                 in a dictionary. The kSecAttrAuthenticationType constant is the key
 572                 and its value is one of the constants defined here.
 573     @constant kSecAttrAuthenticationTypeNTLM.
 574     @constant kSecAttrAuthenticationTypeMSN.
 575     @constant kSecAttrAuthenticationTypeDPA.
 576     @constant kSecAttrAuthenticationTypeRPA.
 577     @constant kSecAttrAuthenticationTypeHTTPBasic.
 578     @constant kSecAttrAuthenticationTypeHTTPDigest.
 579     @constant kSecAttrAuthenticationTypeHTMLForm.
 580     @constant kSecAttrAuthenticationTypeDefault.
 581 */
 582 extern CFTypeRef kSecAttrAuthenticationTypeNTLM
 583     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 584 extern CFTypeRef kSecAttrAuthenticationTypeMSN
 585     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 586 extern CFTypeRef kSecAttrAuthenticationTypeDPA
 587     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 588 extern CFTypeRef kSecAttrAuthenticationTypeRPA
 589     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 590 extern CFTypeRef kSecAttrAuthenticationTypeHTTPBasic
 591     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 592 extern CFTypeRef kSecAttrAuthenticationTypeHTTPDigest
 593     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 594 extern CFTypeRef kSecAttrAuthenticationTypeHTMLForm
 595     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 596 extern CFTypeRef kSecAttrAuthenticationTypeDefault
 597     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 598
 599 /*!
 600     @enum kSecAttrKeyClass Value Constants
 601     @discussion Predefined item attribute constants used to get or set values
 602                 in a dictionary. The kSecAttrKeyClass constant is the key
 603                 and its value is one of the constants defined here.
 604     @constant kSecAttrKeyClassPublic.
 605     @constant kSecAttrKeyClassPrivate.
 606     @constant kSecAttrKeyClassSymmetric.
 607 */
 608 extern CFTypeRef kSecAttrKeyClassPublic
 609     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
 610 extern CFTypeRef kSecAttrKeyClassPrivate
 611     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
 612 extern CFTypeRef kSecAttrKeyClassSymmetric
 613     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
 614
 615 /*!
 616     @enum kSecAttrKeyType Value Constants
 617     @discussion Predefined item attribute constants used to get or set values
 618                 in a dictionary. The kSecAttrKeyType constant is the key
 619                 and its value is one of the constants defined here.
 620     @constant kSecAttrKeyTypeRSA.
 621     @constant kSecAttrKeyTypeEC.
 622 */
 623 extern CFTypeRef kSecAttrKeyTypeRSA
 624     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
 625 extern CFTypeRef kSecAttrKeyTypeEC
 626     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_4_0);
 627
 628 /*!
 629     @enum Search Constants
 630     @discussion Predefined search constants used to set values in a query
 631         dictionary. You can specify a combination of search attributes and
 632         item attributes when looking for matching items with the
 633         SecItemCopyMatching function.
 634     @constant kSecMatchPolicy Specifies a dictionary key whose value is a
 635         SecPolicyRef. If provided, returned certificates or identities must
 636         verify with this policy.
 637     @constant kSecMatchIssuers Specifies a dictionary key whose value is a
 638         CFArray of X.500 names (of type CFDataRef). If provided, returned
 639         certificates or identities will be limited to those whose
 640         certificate chain contains one of the issuers provided in this list.
 641     @constant kSecMatchEmailAddressIfPresent Specifies a dictionary key whose
 642         value is a CFStringRef containing an RFC822 email address. If
 643         provided, returned certificates or identities will be limited to those
 644         that contain the address, or do not contain any email address.
 645     @constant kSecMatchSubjectContains Specifies a dictionary key whose value
 646         is a CFStringRef. If provided, returned certificates or identities
 647         will be limited to those containing this string in the subject.
 648     @constant kSecMatchCaseInsensitive Specifies a dictionary key whose value
 649         is a CFBooleanRef. If this value is kCFBooleanFalse, or is not
 650         provided, then case-sensitive string matching is performed.
 651     @constant kSecMatchTrustedOnly Specifies a dictionary key whose value is
 652         a CFBooleanRef. If provided with a value of kCFBooleanTrue, only
 653         certificates which can be verified back to a trusted anchor will be
 654         returned. If this value is kCFBooleanFalse, or is not provided, then
 655         both trusted and untrusted certificates may be returned.
 656     @constant kSecMatchValidOnDate Specifies a dictionary key whose value is
 657         of type CFDateRef. If provided, returned keys, certificates or
 658         identities will be limited to those which are valid for the given date.
 659         Pass a value of kCFNull to indicate the current date.
 660     @constant kSecMatchLimit Specifies a dictionary key whose value is a
 661         CFNumberRef. If provided, this value specifies the maximum number of
 662         results to return. If not provided, results are limited to the first
 663         item found. Predefined values are provided for a single item
 664         (kSecMatchLimitOne) and all matching items (kSecMatchLimitAll).
 665     @constant kSecMatchLimitOne Specifies that results are limited to the first
 666         item found; used as a value for the kSecMatchLimit dictionary key.
 667     @constant kSecMatchLimitAll Specifies that an unlimited number of results
 668         may be returned; used as a value for the kSecMatchLimit dictionary
 669         key.
 670 */
 671 extern CFTypeRef kSecMatchPolicy
 672     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 673 extern CFTypeRef kSecMatchItemList
 674     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 675 extern CFTypeRef kSecMatchSearchList
 676     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 677 extern CFTypeRef kSecMatchIssuers
 678     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 679 extern CFTypeRef kSecMatchEmailAddressIfPresent
 680     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 681 extern CFTypeRef kSecMatchSubjectContains
 682     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 683 extern CFTypeRef kSecMatchCaseInsensitive
 684     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 685 extern CFTypeRef kSecMatchTrustedOnly
 686     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 687 extern CFTypeRef kSecMatchValidOnDate
 688     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 689 extern CFTypeRef kSecMatchLimit
 690     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 691 extern CFTypeRef kSecMatchLimitOne
 692     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 693 extern CFTypeRef kSecMatchLimitAll
 694     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 695
 696
 697 /*!
 698     @enum Return Type Key Constants
 699     @discussion Predefined return type keys used to set values in a dictionary.
 700         You use these keys to specify the type of results which should be
 701         returned by the SecItemCopyMatching or SecItemAdd function. You can
 702         specify zero or more of these return types. If more than one of these
 703         result types is specified, the result is returned as a CFDictionaryRef
 704         whose keys are the result types and values are the requested data.
 705     @constant kSecReturnData Specifies a dictionary key whose value is of type
 706         CFBooleanRef. A value of kCFBooleanTrue indicates that the data of
 707         an item (CFDataRef) should be returned. For keys and password
 708         items, data is secret (encrypted) and may require the user to enter
 709         a password for access.
 710     @constant kSecReturnAttributes Specifies a dictionary key whose value is
 711         of type CFBooleanRef. A value of kCFBooleanTrue indicates that the
 712         (non-encrypted) attributes of an item (CFDictionaryRef) should be
 713         returned.
 714     @constant kSecReturnRef Specifies a dictionary key whose value is a
 715         CFBooleanRef. A value of kCFBooleanTrue indicates that a reference
 716         should be returned. Depending on the item class requested, the
 717         returned reference(s) may be of type SecKeychainItemRef, SecKeyRef,
 718         SecCertificateRef, or SecIdentityRef.
 719     @constant kSecReturnPersistentRef Specifies a dictionary key whose value
 720         is of type CFBooleanRef. A value of kCFBooleanTrue indicates that a
 721         persistent reference to an item (CFDataRef) should be returned.
 722 */
 723 extern CFTypeRef kSecReturnData
 724     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 725 extern CFTypeRef kSecReturnAttributes
 726     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 727 extern CFTypeRef kSecReturnRef
 728     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 729 extern CFTypeRef kSecReturnPersistentRef
 730     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 731
 732
 733 /*!
 734     @enum Value Type Key Constants
 735     @discussion Predefined value type keys used to pass values in a dictionary.
 736         You can specify zero or more of these types depending on the function
 737         you are calling.  For SecItemCopyMatching or SecItemAdd these are
 738         used as keys in the results dictionary.
 739     @constant kSecValueData Specifies a dictionary key whose value is of type
 740         CFDataRef.  For keys and password items, data is secret (encrypted)
 741         and may require the user to enter a password for access.
 742     @constant kSecValueRef Specifies a dictionary key whose value, depending
 743         on the item class requested, is of type SecKeychainItemRef, SecKeyRef,
 744         SecCertificateRef, or SecIdentityRef.
 745     @constant kSecValuePersistentRef Specifies a dictionary key whose value
 746         is of type CFDataRef.  The bytes in this CFDataRef can be stored by
 747         the caller and used on a subsequent invocation of the application (or
 748         even a different application) to retrieve the item referenced by it.
 749 */
 750 extern CFTypeRef kSecValueData
 751     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 752 extern CFTypeRef kSecValueRef
 753     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 754 extern CFTypeRef kSecValuePersistentRef
 755     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 756
 757
 758 /*!
 759     @enum Other Constants
 760     @discussion Predefined constants used to set values in a dictionary.
 761     @constant kSecUseItemList Specifies a dictionary key whose value is a
 762         CFArray of items. If provided, this array is treated as the set of
 763         all possible items to search, or add if the API being called is
 764         SecItemAdd. The items in this array may be of type SecKeyRef,
 765         SecCertificateRef, SecIdentityRef, or CFDataRef (for a persistent
 766         item reference.) The items in the array must all be of the same
 767         type. When this attribute is provided, no keychains are searched.
 768 */
 769 extern CFTypeRef kSecUseItemList
 770     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 771
 772 /*!
 773     @function SecItemCopyMatching
 774     @abstract Returns one or more items which match a search query.
 775     @param query A dictionary containing an item class specification and
 776         optional attributes for controlling the search. See the "Keychain
 777         Search Attributes" section for a description of currently defined
 778         search attributes.
 779     @param result On return, a CFTypeRef reference to the found item(s). The
 780         exact type of the result is based on the search attributes supplied
 781         in the query, as discussed below.
 782     @result A result code. See "Security Error Codes" (SecBase.h).
 783     @discussion Attributes defining a search are specified by adding key/value
 784         pairs to the query dictionary.
 785
 786     A typical query consists of:
 787
 788       * a kSecClass key, whose value is a constant from the Class
 789         Constants section that specifies the class of item(s) to be searched
 790       * one or more keys from the "Attribute Key Constants" section, whose value
 791         is the attribute data to be matched
 792       * one or more keys from the "Search Constants" section, whose value is
 793         used to further refine the search
 794       * a key from the "Return Type Key Constants" section, specifying the type of
 795         results desired
 796
 797    Result types are specified as follows:
 798
 799       * To obtain the data of a matching item (CFDataRef), specify
 800         kSecReturnData with a value of kCFBooleanTrue.
 801       * To obtain the attributes of a matching item (CFDictionaryRef), specify
 802         kSecReturnAttributes with a value of kCFBooleanTrue.
 803       * To obtain a reference to a matching item (SecKeychainItemRef,
 804         SecKeyRef, SecCertificateRef, or SecIdentityRef), specify kSecReturnRef
 805         with a value of kCFBooleanTrue.
 806       * To obtain a persistent reference to a matching item (CFDataRef),
 807         specify kSecReturnPersistentRef with a value of kCFBooleanTrue. Note
 808         that unlike normal references, a persistent reference may be stored
 809         on disk or passed between processes.
 810       * If more than one of these result types is specified, the result is
 811         returned as a CFDictionaryRef containing all the requested data.
 812       * If a result type is not specified, no results are returned.
 813
 814     By default, this function returns only the first match found. To obtain
 815     more than one matching item at a time, specify kSecMatchLimit with a value
 816     greater than 1. The result will be a CFArrayRef containing up to that
 817     number of matching items; the items' types are described above.
 818
 819     To filter a provided list of items down to those matching the query,
 820     specify a kSecMatchItemList whose value is a CFArray of SecKeychainItemRef,
 821     SecKeyRef, SecCertificateRef, or SecIdentityRef items. The objects in the
 822     provided array must be of the same type.
 823
 824     To convert from a persistent item reference to a normal item reference,
 825     specify a kSecValuePersistentRef whose value a CFDataRef (the persistent
 826     reference), and a kSecReturnRef whose value is kCFBooleanTrue.
 827 */
 828 OSStatus SecItemCopyMatching(CFDictionaryRef query, CFTypeRef *result)
 829     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 830
 831 /*!
 832     @function SecItemAdd
 833     @abstract Add one or more items to a keychain.
 834     @param attributes A dictionary containing an item class specification and
 835         optional entries specifying the item's attribute values. See the
 836         "Attribute Key Constants" section for a description of currently defined
 837         attributes.
 838     @param result On return, a CFTypeRef reference to the newly added item(s).
 839         The exact type of the result is based on the values supplied
 840         in attributes, as discussed below. Pass NULL if this result is not
 841         required.
 842     @result A result code. See "Security Error Codes" (SecBase.h).
 843     @discussion Attributes defining an item are specified by adding key/value
 844         pairs to the attributes dictionary.  To add multiple items to a keychain
 845         at once use the kSecUseItemList key with an array of items as its value.
 846         This is currently only supported for non password items.
 847
 848     Result types are specified as follows:
 849
 850       * To obtain the data of the added item (CFDataRef), specify
 851         kSecReturnData with a value of kCFBooleanTrue.
 852       * To obtain all the attributes of the added item (CFDictionaryRef),
 853         specify kSecReturnAttributes with a value of kCFBooleanTrue.
 854       * To obtain a reference to the added item (SecKeychainItemRef, SecKeyRef,
 855         SecCertificateRef, or SecIdentityRef), specify kSecReturnRef with a
 856         value of kCFBooleanTrue.
 857       * To obtain a persistent reference to the added item (CFDataRef), specify
 858         kSecReturnPersistentRef with a value of kCFBooleanTrue. Note that
 859         unlike normal references, a persistent reference may be stored on disk
 860         or passed between processes.
 861       * If more than one of these result types is specified, the result is
 862         returned as a CFDictionaryRef containing all the requested data.
 863       * If a result type is not specified, no results are returned.
 864 */
 865 OSStatus SecItemAdd(CFDictionaryRef attributes, CFTypeRef *result)
 866     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 867
 868 /*!
 869     @function SecItemUpdate
 870     @abstract Modify zero or more items which match a search query.
 871     @param query A dictionary containing an item class specification and
 872         optional attributes for controlling the search. See the "Attribute
 873         Constants" and "Search Constants" sections for a description of
 874         currently defined search attributes.
 875     @param attributesToUpdate A dictionary containing one or more attributes
 876         whose values should be set to the ones specified. Only real keychain
 877         attributes are permitted in this dictionary (no "meta" attributes are
 878         allowed.) See the "Attribute Key Constants" section for a description of
 879         currently defined value attributes.
 880     @result A result code. See "Security Error Codes" (SecBase.h).
 881     @discussion Attributes defining a search are specified by adding key/value
 882         pairs to the query dictionary.
 883 */
 884 OSStatus SecItemUpdate(CFDictionaryRef query,
 885     CFDictionaryRef attributesToUpdate)
 886     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 887
 888 /*!
 889     @function SecItemDelete
 890     @abstract Delete zero or more items which match a search query.
 891     @param query A dictionary containing an item class specification and
 892         optional attributes for controlling the search. See the "Attribute
 893         Constants" and "Search Constants" sections for a description of
 894         currently defined search attributes.
 895     @result A result code.  See "Security Error Codes" (SecBase.h).
 896     @discussion Attributes defining a search are specified by adding key/value
 897         pairs to the query dictionary.
 898
 899     By default, this function deletes all items matching the specified query.
 900     You can change this behavior by specifying one of the follow keys:
 901
 902       * To delete an item identified by a transient reference, specify
 903         kSecValueRef with a reference returned by using the kSecReturnRef
 904         key in a previous call to SecItemCopyMatching or SecItemAdd.
 905       * To delete an item identified by a persistent reference, specify
 906         kSecValuePersistentRef with a persistent reference returned by
 907         using the kSecReturnPersistentRef key to SecItemCopyMatching or
 908         SecItemAdd.
 909       * To delete multiple items specify kSecMatchItemList with an array
 910         of references.
 911       * If more than one of these result keys is specified, the behavior is
 912         undefined.
 913 */
 914 OSStatus SecItemDelete(CFDictionaryRef query)
 915     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 916
 917 #if defined(__cplusplus)
 918 }
 919 #endif
 920
 921 #endif /* !_SECURITY_SECITEM_H_ */