libsecurity_keychain/lib/SecItem.h

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