iOS Developer Library

Developer

Security Framework Reference Keychain Services Reference

Options
Deployment Target:

On This Page
Language:

Keychain Services Reference

Keychain Services is a programming interface that enables you to find, add, modify, and delete keychain items.

If you want to look at some code that uses this API, you can find the source code for the security command-line tool in the SecurityTool project on Apple's Open Source website.

Functions

For this interface, keychain items are found or defined by a CFDictionary of key-value pairs. Each key in the dictionary identifies one attribute of the keychain item, or a search option. For example, you can use the kSecClass key to specify that the keychain item is an Internet password, that it has a specific creation date, that it is for the HTTPS protocol, and that only the first match found should be returned. The keys that can be used for this purpose and the possible values for each key are listed in the Keychain Services Constants section.

See the discussion section of the SecItemCopyMatching function for information about how to construct a keychain-item search dictionary.

  • Returns one or more keychain items that match a search query, or copies attributes of specific keychain items.

    Declaration

    Swift

    func SecItemCopyMatching(_ query: CFDictionary!, _ result: UnsafeMutablePointer<Unmanaged<AnyObject>?>) -> OSStatus

    Objective-C

    OSStatus SecItemCopyMatching ( CFDictionaryRef query, CFTypeRef *result );

    Parameters

    query

    A dictionary containing an item class specification (Keychain Item Class Keys and Values) and optional attributes for controlling the search. See Keychain Services Constants for a description of currently defined search attributes.

    result

    On return, a reference to the found items. The exact type of the result is based on the search attributes supplied in the query, as discussed below.

    Return Value

    A result code. See Keychain Services Result Codes. Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

    Discussion

    You specify attributes defining a search by adding key-value pairs to the query dictionary.

    A typical query consists of:

    Return types (Search Results Constants) are specified as follows:

    • To obtain a reference (of type CFDataRef) to the data of a matching item, specify kSecReturnData with a value of kCFBooleanTrue.

    • To obtain a dictionary (of type CFDictionaryRef) containing the attributes of a matching item, specify kSecReturnAttributes with a value of kCFBooleanTrue.

    • To obtain a reference (of type SecKeychainItemRef, SecKeyRef, SecCertificateRef, or SecIdentityRef) to a matching item, specify kSecReturnRef with a value of kCFBooleanTrue.

    • To obtain a persistent reference (of type CFDataRef) to a matching item, specify kSecReturnPersistentRef with a value of kCFBooleanTrue. Note that unlike normal references, a persistent reference may be stored on disk or passed between processes.

    • If more than one return type is specified (for example, kSecReturnRef and kSecReturnAttributes), the results are returned as a dictionary (that is, an object of type CFDictionaryRef) containing all the requested data.

    By default, this function returns only the first match found. To obtain more than one matching item at a time, specify the search key kSecMatchLimit with a value greater than 1. The result will be an object of type CFArrayRef containing up to that number of matching items.

    By default, this function searches for items in the keychain. To instead provide your own set of items to be filtered by this search query, specify the search key kSecMatchItemList and provide as its value a CFArrayRef object containing items of type SecKeychainItemRef, SecKeyRef, SecCertificateRef, or SecIdentityRef. The objects in the provided array must all be of the same type.

    To limit a keychain search to a particular keychain or keychains, specify the search key kSecMatchSearchList and provide as its value a CFArrayRef object containing items of type SecKeychainRef items.

    To convert from persistent item references to normal item references, specify the search key kSecMatchItemList with a value that consists of an object of type CFArrayRef referencing an array containing one or more elements of type CFDataRef (the persistent references), and a return-type key of kSecReturnRef whose value is kCFBooleanTrue. The objects in the provided array must all be of the same type.

    When you use Xcode to create an application, Xcode adds an application-identifier entitlement to the application bundle. Keychain Services uses this entitlement to grant the application access to its own keychain items. You can also add a keychain-access-groups entitlement to the application and, in the entitlement property list file, specify an array of keychain access groups to which the application belongs. The property list file can have any name you like (for example, keychain-access-groups.plist). The Xcode build variable CODE_SIGN_ENTITLEMENTS should contain the SRCROOT relative path to the entitlement property list file. The property list file itself should be a dictionary with a top-level key called keychain-access-groups whose value is an array of strings. When you call the SecItemAdd function to add an item to the keychain, you can specify the access group to which that item should belong. By default, the SecItemCopyMatching function searches all the access groups to which the application belongs. However, you can add the kSecAttrAccessGroup key to the search dictionary to specify which access group to search for keychain items.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in iOS 2.0 and later.

  • Adds one or more items to a keychain.

    Declaration

    Swift

    func SecItemAdd(_ attributes: CFDictionary!, _ result: UnsafeMutablePointer<Unmanaged<AnyObject>?>) -> OSStatus

    Objective-C

    OSStatus SecItemAdd ( CFDictionaryRef attributes, CFTypeRef *result );

    Parameters

    attributes

    A dictionary containing an item class key-value pair (Keychain Item Class Keys and Values) and optional attribute key-value pairs (Attribute Item Keys and Values) specifying the item's attribute values.

    result

    On return, a reference to the newly added items. The exact type of the result is based on the values supplied in attributes, as discussed below. Pass NULL if this result is not required.

    Return Value

    A result code. See Keychain Services Result Codes. Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

    Discussion

    You specify attributes defining an item by adding key-value pairs to the attributes dictionary. To add multiple items to a keychain at once use the kSecUseItemList key (see section Item List Key) with an array of items as its value. This is only supported for non-password items.

    If you want the new keychain item to be shared among multiple applications, include the kSecAttrAccessGroup key in the attributes dictionary. The value of this key must be the name of a keychain access group to which all of the programs that will share this item belong.

    When you use Xcode to create an application, Xcode adds an application-identifier entitlement to the application bundle. Keychain Services uses this entitlement to grant the application access to its own keychain items. You can also add a keychain-access-groups entitlement to the application and, in the entitlement property list file, specify an array of keychain access groups to which the application belongs. The property list file can have any name you like (for example, keychain-access-groups.plist). The Xcode build variable CODE_SIGN_ENTITLEMENTS should contain the SRCROOT relative path to the entitlement property list file. The property list file itself should be a dictionary with a top-level key called keychain-access-groups whose value is an array of strings. If you add such a property-list file to the application bundle, then the access group corresponding to the application-identifier entitlement is treated as the last element in the access groups array. If you do not include the kSecAttrAccessGroup key in the attributes dictionary when you call the SecItemAdd function to add an item to the keychain, the function uses the first access group in the array by default. If there is no kSecAttrAccessGroup key in the attributes dictionary and there is no keychain-access-groups entitlement in the application bundle, then the access group of a newly created item is the value of the application-identifier entitlement.

    For example, a development group in Apple might have the ID:

    659823F3DC53.com.apple

    and the application identifiers of their two applications might be:

    659823F3DC53.com.apple.oneappleapp and

    659823F3DC53.com.apple.twoappleapp

    If both applications add a keychain-access-groups entitlement with one value in the array of access groups:

    659823F3DC53.com.apple.netaccount

    then both applications would add new keychain items to the 659823F3DC53.com.apple.netaccount access group by default and both applications would have access to keychain items in that group. In addition, each application would still have access to its own private keychain items: OneAppleApp would have access to items in keychain access group 659823F3DC53.com.apple.oneappleapp and TwoAppleApp would have access to items in 659823F3DC53.com.apple.twoappleapp.

    Return types (Search Results Constants) are specified as follows:

    • To obtain the data of the added item as an object of type CFDataRef, specify the return type key kSecReturnData with a value of kCFBooleanTrue.

    • To obtain all the attributes of the added item as objects of type CFDictionaryRef, specify kSecReturnAttributes with a value of kCFBooleanTrue.

    • To obtain a reference to the added item of type SecKeychainItemRef, SecKeyRef, SecCertificateRef, or SecIdentityRef), specify kSecReturnRef with a value of kCFBooleanTrue. This is the default behavior if a return type is not explicitly specified.

    • To obtain a persistent reference to the added item (an object of type CFDataRef), specify kSecReturnPersistentRef with a value of kCFBooleanTrue. Note that unlike normal references, a persistent reference may be stored on disk or passed between processes.

    • If more than one of these return types is specified, the result is returned as an object of type CFDictionaryRef containing all the requested data.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in iOS 2.0 and later.

  • Modifies items that match a search query.

    Declaration

    Swift

    func SecItemUpdate(_ query: CFDictionary!, _ attributesToUpdate: CFDictionary!) -> OSStatus

    Objective-C

    OSStatus SecItemUpdate ( CFDictionaryRef query, CFDictionaryRef attributesToUpdate );

    Parameters

    query

    A dictionary containing an item class specification and optional attributes for controlling the search. Specify the items whose values you wish to change. See Search Keys for a description of currently defined search attributes.

    attributesToUpdate

    A dictionary containing the attributes whose values should be changed, along with the new values. Only real keychain attributes are permitted in this dictionary (no "meta" attributes are allowed.) See Attribute Item Keys and Values for a description of currently defined value attributes.

    Return Value

    A result code. See Keychain Services Result Codes. Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

    Discussion

    See the discussion section of the SecItemCopyMatching function for information about how to construct a search dictionary.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in iOS 2.0 and later.

  • Deletes items that match a search query.

    Declaration

    Swift

    func SecItemDelete(_ query: CFDictionary!) -> OSStatus

    Objective-C

    OSStatus SecItemDelete ( CFDictionaryRef query );

    Parameters

    query

    A dictionary containing an item class specification and optional attributes for controlling the search. See Search Keys for a description of currently defined search attributes.

    Return Value

    A result code. See Keychain Services Result Codes. Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

    Discussion

    See the discussion section of the SecItemCopyMatching function for information about how to construct a search dictionary.

    By default, this function deletes all items matching the specified query. You can change this behavior by specifying a key, as follows:

    • To delete an item identified by a transient reference, specify the kSecMatchItemList search key with a reference returned by using the kSecReturnRef return type key in a previous call to the SecItemCopyMatching or SecItemAdd functions.

    • To delete an item identified by a persistent reference, specify the kSecMatchItemList search key with a persistent reference returned by using the kSecReturnPersistentRef return type key to the SecItemCopyMatching or SecItemAdd functions.

    • If more than one of these return keys is specified, the behavior is undefined.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in iOS 2.0 and later.

Constants

OS X Keychain Services API Constants

  • Predefined key constants used when passing dictionary-based arguments to import/export functions.

    Declaration

    Swift

    var kSecImportExportPassphrase: Unmanaged<CFString>!

    Objective-C

    extern CFStringRef kSecImportExportPassphrase;

    Constants

    • kSecImportExportPassphrase

      kSecImportExportPassphrase

      A passphrase (represented by a CFStringRef object) to be used when exporting to or importing from PKCS#12 format.

      Available in iOS 2.0 and later.

Keychain Item Class Keys and Values

Constants used in a search dictionary to specify the class of items in the keychain. See SecItemCopyMatching for a description of a search dictionary.

  • Key constant used to set the item class value in a search dictionary.

    Declaration

    Swift

    var kSecClass: CFStringRef

    Objective-C

    CFTypeRef kSecClass;

    Constants

    • kSecClass

      kSecClass

      Dictionary key whose value is the item's class code.

      Possible values for this key are listed in Item Class Value Constants.

      Available in iOS 2.0 and later.

  • Values used with the kSecClass key in a search dictionary.

    Declaration

    Swift

    var kSecClassGenericPassword: CFStringRef var kSecClassInternetPassword: CFStringRef var kSecClassCertificate: CFStringRef var kSecClassKey: CFStringRef var kSecClassIdentity: CFStringRef

    Objective-C

    CFTypeRef kSecClassGenericPassword; CFTypeRef kSecClassInternetPassword; CFTypeRef kSecClassCertificate; CFTypeRef kSecClassKey; CFTypeRef kSecClassIdentity;

    Constants

    • kSecClassGenericPassword

      kSecClassGenericPassword

      Generic password item.

      The following attribute types (Attribute Item Keys and Values) can be used with an item of this type:

      • kSecAttrAccessible

      • kSecAttrAccessGroup

      • kSecAttrCreationDate

      • kSecAttrModificationDate

      • kSecAttrDescription

      • kSecAttrComment

      • kSecAttrCreator

      • kSecAttrType

      • kSecAttrLabel

      • kSecAttrIsInvisible

      • kSecAttrIsNegative

      • kSecAttrAccount

      • kSecAttrService

      • kSecAttrGeneric

      Available in iOS 2.0 and later.

    • kSecClassInternetPassword

      kSecClassInternetPassword

      Internet password item.

      The following attribute types (Attribute Item Keys and Values) can be used with an item of this type:

      • kSecAttrAccessible

      • kSecAttrAccessGroup

      • kSecAttrCreationDate

      • kSecAttrModificationDate

      • kSecAttrDescription

      • kSecAttrComment

      • kSecAttrCreator

      • kSecAttrType

      • kSecAttrLabel

      • kSecAttrIsInvisible

      • kSecAttrIsNegative

      • kSecAttrAccount

      • kSecAttrSecurityDomain

      • kSecAttrServer

      • kSecAttrProtocol

      • kSecAttrAuthenticationType

      • kSecAttrPort

      • kSecAttrPath

      Available in iOS 2.0 and later.

    • kSecClassCertificate

      kSecClassCertificate

      Certificate item.

      The following attribute types (Attribute Item Keys and Values) can be used with an item of this type:

      • kSecAttrAccessible

      • kSecAttrAccessGroup

      • kSecAttrCertificateType

      • kSecAttrCertificateEncoding

      • kSecAttrLabel

      • kSecAttrSubject

      • kSecAttrIssuer

      • kSecAttrSerialNumber

      • kSecAttrSubjectKeyID

      • kSecAttrPublicKeyHash

      Available in iOS 2.0 and later.

    • kSecClassKey

      kSecClassKey

      Cryptographic key item.

      The following attribute types (Attribute Item Keys and Values) can be used with an item of this type:

      • kSecAttrAccessible

      • kSecAttrAccessGroup

      • kSecAttrKeyClass

      • kSecAttrLabel

      • kSecAttrApplicationLabel

      • kSecAttrIsPermanent

      • kSecAttrApplicationTag

      • kSecAttrKeyType

      • kSecAttrKeySizeInBits

      • kSecAttrEffectiveKeySize

      • kSecAttrCanEncrypt

      • kSecAttrCanDecrypt

      • kSecAttrCanDerive

      • kSecAttrCanSign

      • kSecAttrCanVerify

      • kSecAttrCanWrap

      • kSecAttrCanUnwrap

      Available in iOS 2.0 and later.

    • kSecClassIdentity

      kSecClassIdentity

      Identity item.

      An identity is a certificate together with its associated private key. Because an identity is the combination of a private key and a certificate, this class shares attributes of both kSecClassKey and kSecClassCertificate.

      Available in iOS 2.0 and later.

Attribute Item Keys and Values

You use keys in a search dictionary to specify the keychain items for which to search. You can specify a combination of item attributes and search attributes (see Search Keys) when looking for matching items with the SecItemCopyMatching function. This section lists all the keys that specify keychain item attributes. The description of each item indicates what the possible values are for that key. In a few cases, the programming interface provides a set of constants that you can use as values for a specific key. Those value constants are also in this section, following the descriptions of the keys.

  • Each type of keychain item can have a number of attributes describing that item. For the possible types of keychain item and the attributes that can be specified for each, see Keychain Item Class Keys and Values.

    Declaration

    Swift

    var kSecAttrAccessible: CFStringRef var kSecAttrCreationDate: CFStringRef var kSecAttrModificationDate: CFStringRef var kSecAttrDescription: CFStringRef var kSecAttrComment: CFStringRef var kSecAttrCreator: CFStringRef var kSecAttrType: CFStringRef var kSecAttrLabel: CFStringRef var kSecAttrIsInvisible: CFStringRef var kSecAttrIsNegative: CFStringRef var kSecAttrAccount: CFStringRef var kSecAttrService: CFStringRef var kSecAttrGeneric: CFStringRef var kSecAttrSecurityDomain: CFStringRef var kSecAttrServer: CFStringRef var kSecAttrProtocol: CFStringRef var kSecAttrAuthenticationType: CFStringRef var kSecAttrPort: CFStringRef var kSecAttrPath: CFStringRef var kSecAttrSubject: CFStringRef var kSecAttrIssuer: CFStringRef var kSecAttrSerialNumber: CFStringRef var kSecAttrSubjectKeyID: CFStringRef var kSecAttrPublicKeyHash: CFStringRef var kSecAttrCertificateType: CFStringRef var kSecAttrCertificateEncoding: CFStringRef var kSecAttrKeyClass: CFStringRef var kSecAttrApplicationLabel: CFStringRef var kSecAttrIsPermanent: CFStringRef var kSecAttrApplicationTag: CFStringRef var kSecAttrKeyType: CFStringRef var kSecAttrKeySizeInBits: CFStringRef var kSecAttrEffectiveKeySize: CFStringRef var kSecAttrCanEncrypt: CFStringRef var kSecAttrCanDecrypt: CFStringRef var kSecAttrCanDerive: CFStringRef var kSecAttrCanSign: CFStringRef var kSecAttrCanVerify: CFStringRef var kSecAttrCanWrap: CFStringRef var kSecAttrCanUnwrap: CFStringRef var kSecAttrAccessGroup: CFStringRef

    Objective-C

    CFTypeRef kSecAttrAccessible; CFTypeRef kSecAttrCreationDate; CFTypeRef kSecAttrModificationDate; CFTypeRef kSecAttrDescription; CFTypeRef kSecAttrComment; CFTypeRef kSecAttrCreator; CFTypeRef kSecAttrType; CFTypeRef kSecAttrLabel; CFTypeRef kSecAttrIsInvisible; CFTypeRef kSecAttrIsNegative; CFTypeRef kSecAttrAccount; CFTypeRef kSecAttrService; CFTypeRef kSecAttrGeneric; CFTypeRef kSecAttrSecurityDomain; CFTypeRef kSecAttrServer; CFTypeRef kSecAttrProtocol; CFTypeRef kSecAttrAuthenticationType; CFTypeRef kSecAttrPort; CFTypeRef kSecAttrPath; CFTypeRef kSecAttrSubject; CFTypeRef kSecAttrIssuer; CFTypeRef kSecAttrSerialNumber; CFTypeRef kSecAttrSubjectKeyID; CFTypeRef kSecAttrPublicKeyHash; CFTypeRef kSecAttrCertificateType; CFTypeRef kSecAttrCertificateEncoding; CFTypeRef kSecAttrKeyClass; CFTypeRef kSecAttrApplicationLabel; CFTypeRef kSecAttrIsPermanent; CFTypeRef kSecAttrApplicationTag; CFTypeRef kSecAttrKeyType; CFTypeRef kSecAttrKeySizeInBits; CFTypeRef kSecAttrEffectiveKeySize; CFTypeRef kSecAttrCanEncrypt; CFTypeRef kSecAttrCanDecrypt; CFTypeRef kSecAttrCanDerive; CFTypeRef kSecAttrCanSign; CFTypeRef kSecAttrCanVerify; CFTypeRef kSecAttrCanWrap; CFTypeRef kSecAttrCanUnwrap; CFTypeRef kSecAttrAccessGroup;

    Constants

    • kSecAttrAccessible

      kSecAttrAccessible

      A CFTypeRef (opaque) value that indicates when your app needs access to the data in a keychain item. You should choose the most restrictive option that meets your app’s needs so that iOS can protect that item to the greatest extent possible. For a list of possible values, see Keychain Item Accessibility Constants.

      Available in iOS 4.0 and later.

    • kSecAttrCreationDate

      kSecAttrCreationDate

      Creation date key.

      The corresponding value is of type CFDateRef and represents the date the item was created. Read only.

      Available in iOS 2.0 and later.

    • kSecAttrModificationDate

      kSecAttrModificationDate

      Modification date key.

      The corresponding value is of type CFDateRef and represents the last time the item was updated. Read only.

      Available in iOS 2.0 and later.

    • kSecAttrDescription

      kSecAttrDescription

      Description attribute key.

      The corresponding value is of type CFStringRef and specifies a user-visible string describing this kind of item (for example, "Disk image password").

      Available in iOS 2.0 and later.

    • kSecAttrComment

      kSecAttrComment

      Comment attribute key.

      The corresponding value is of type CFStringRef and contains the user-editable comment for this item.

      Available in iOS 2.0 and later.

    • kSecAttrCreator

      kSecAttrCreator

      Creator attribute key.

      The corresponding value is of type CFNumberRef and represents the item's creator. This number is the unsigned integer representation of a four-character code (for example, 'aCrt').

      Available in iOS 2.0 and later.

    • kSecAttrType

      kSecAttrType

      Type attribute key.

      The corresponding value is of type CFNumberRef and represents the item's type. This number is the unsigned integer representation of a four-character code (for example, 'aTyp').

      Available in iOS 2.0 and later.

    • kSecAttrLabel

      kSecAttrLabel

      Label attribute key.

      The corresponding value is of type CFStringRef and contains the user-visible label for this item.

      Available in iOS 2.0 and later.

    • kSecAttrIsInvisible

      kSecAttrIsInvisible

      Invisible attribute key.

      The corresponding value is of type CFBooleanRef and is kCFBooleanTrue if the item is invisible (that is, should not be displayed).

      Available in iOS 2.0 and later.

    • kSecAttrIsNegative

      kSecAttrIsNegative

      Negative attribute key.

      The corresponding value is of type CFBooleanRef and indicates whether there is a valid password associated with this keychain item. This is useful if your application doesn't want a password for some particular service to be stored in the keychain, but prefers that it always be entered by the user.

      Available in iOS 2.0 and later.

    • kSecAttrAccount

      kSecAttrAccount

      Account attribute key.

      The corresponding value is of type CFStringRef and contains an account name. Items of class kSecClassGenericPassword and kSecClassInternetPassword have this attribute.

      Available in iOS 2.0 and later.

    • kSecAttrService

      kSecAttrService

      Service attribute key.

      The corresponding value is a string of type CFStringRef that represents the service associated with this item. Items of class kSecClassGenericPassword have this attribute.

      Available in iOS 2.0 and later.

    • kSecAttrGeneric

      kSecAttrGeneric

      Generic attribute key.

      The corresponding value is of type CFDataRef and contains a user-defined attribute. Items of class kSecClassGenericPassword have this attribute.

      Available in iOS 2.0 and later.

    • kSecAttrSecurityDomain

      kSecAttrSecurityDomain

      Security domain attribute key.

      The corresponding value is of type CFStringRef and represents the Internet security domain. Items of class kSecClassInternetPassword have this attribute.

      Available in iOS 2.0 and later.

    • kSecAttrServer

      kSecAttrServer

      Server attribute key.

      The corresponding value is of type CFStringRef and contains the server's domain name or IP address. Items of class kSecClassInternetPassword have this attribute.

      Available in iOS 2.0 and later.

    • kSecAttrProtocol

      kSecAttrProtocol

      Protocol attribute key.

      The corresponding value is of type CFNumberRef and denotes the protocol for this item (see Protocol Values). Items of class kSecClassInternetPassword have this attribute.

      Available in iOS 2.0 and later.

    • kSecAttrAuthenticationType

      kSecAttrAuthenticationType

      Authentication type attribute key.

      The corresponding value is of type CFNumberRef and denotes the authentication scheme for this item (see Authentication Type Values).

      Available in iOS 2.0 and later.

    • kSecAttrPort

      kSecAttrPort

      Port attribute key.

      The corresponding value is of type CFNumberRef and represents an Internet port number. Items of class kSecClassInternetPassword have this attribute.

      Available in iOS 2.0 and later.

    • kSecAttrPath

      kSecAttrPath

      Path attribute key.

      The corresponding value is of type CFStringRef and represents a path, typically the path component of the URL. Items of class kSecClassInternetPassword have this attribute.

      Available in iOS 2.0 and later.

    • kSecAttrSubject

      kSecAttrSubject

      Subject attribute key.

      The corresponding value is of type CFDataRef and contains the X.500 subject name of a certificate. Items of class kSecClassCertificate have this attribute. Read only.

      Available in iOS 2.0 and later.

    • kSecAttrIssuer

      kSecAttrIssuer

      Issuer attribute key.

      The corresponding value is of type CFDataRef and contains the X.500 issuer name of a certificate. Items of class kSecClassCertificate have this attribute. Read only.

      Available in iOS 2.0 and later.

    • kSecAttrSerialNumber

      kSecAttrSerialNumber

      Serial number attribute key.  

      The corresponding value is of type CFDataRef and contains the serial number data of a certificate. Items of class kSecClassCertificate have this attribute. Read only.

      Available in iOS 2.0 and later.

    • kSecAttrSubjectKeyID

      kSecAttrSubjectKeyID

      Subject key ID attribute key.

      The corresponding value is of type CFDataRef and contains the subject key ID of a certificate. Items of class kSecClassCertificate have this attribute. Read only.

      Available in iOS 2.0 and later.

    • kSecAttrPublicKeyHash

      kSecAttrPublicKeyHash

      Public key hash attribute key.

      The corresponding value is of type CFDataRef and contains the hash of a certificate's public key. Items of class kSecClassCertificate have this attribute. Read only.

      Available in iOS 2.0 and later.

    • kSecAttrCertificateType

      kSecAttrCertificateType

      Certificate type attribute key.

      The corresponding value is of type CFNumberRef and denotes the certificate type (see the CSSM_CERT_TYPE enumeration in cssmtype.h). Items of class kSecClassCertificate have this attribute. Read only.

      Available in iOS 2.0 and later.

    • kSecAttrCertificateEncoding

      kSecAttrCertificateEncoding

      Certificate encoding attribute key.

      The corresponding value is of type CFNumberRef and denotes the certificate encoding (see the CSSM_CERT_ENCODING enumeration in cssmtype.h). Items of class kSecClassCertificate have this attribute. Read only.

      Available in iOS 2.0 and later.

    • kSecAttrKeyClass

      kSecAttrKeyClass

      Key class attribute key.

      The corresponding value is of type CFTypeRef and specifies a type of cryptographic key. Possible values are listed in Key Class Values. Read only.

      Available in iOS 2.0 and later.

    • kSecAttrApplicationLabel

      kSecAttrApplicationLabel

      Application label attribute key.

      The corresponding value is of type CFStringRef and contains a label for this item. This attribute is different from the kSecAttrLabel attribute, which is intended to be human-readable. This attribute is used to look up a key programmatically; in particular, for keys of class kSecAttrKeyClassPublic and kSecAttrKeyClassPrivate, the value of this attribute is the hash of the public key.

      Available in iOS 2.0 and later.

    • kSecAttrIsPermanent

      kSecAttrIsPermanent

      Permanence attribute key.

      The corresponding value is of type CFBooleanRef and indicates whether this cryptographic key is to be stored permanently.

      Available in iOS 2.0 and later.

    • kSecAttrApplicationTag

      kSecAttrApplicationTag

      Private tag attribute key.

      The corresponding value is of type CFDataRef and contains private tag data.

      Available in iOS 2.0 and later.

    • kSecAttrKeyType

      kSecAttrKeyType

      Algorithm attribute key.

      The corresponding value is of type CFNumberRef and indicates the algorithm associated with this cryptographic key (see the CSSM_ALGORITHMS enumeration in cssmtype.h and Key Type Values).

      Available in iOS 2.0 and later.

    • kSecAttrKeySizeInBits

      kSecAttrKeySizeInBits

      Number of bits attribute key.

      The corresponding value is of type CFNumberRef and indicates the total number of bits in this cryptographic key. Compare with kSecAttrEffectiveKeySize.

      Available in iOS 2.0 and later.

    • kSecAttrEffectiveKeySize

      kSecAttrEffectiveKeySize

      Effective number of bits attribute key.

      The corresponding value is of type CFNumberRef and indicates the effective number of bits in this cryptographic key. For example, a DES key has a kSecAttrKeySizeInBits of 64, but a kSecAttrEffectiveKeySize of 56 bits.

      Available in iOS 2.0 and later.

    • kSecAttrCanEncrypt

      kSecAttrCanEncrypt

      Encryption attribute key.

      The corresponding value is of type CFBooleanRef and indicates whether this cryptographic key can be used to encrypt data.

      Available in iOS 2.0 and later.

    • kSecAttrCanDecrypt

      kSecAttrCanDecrypt

      Decryption attribute key.

      The corresponding value is of type CFBooleanRef and indicates whether this cryptographic key can be used to decrypt data.

      Available in iOS 2.0 and later.

    • kSecAttrCanDerive

      kSecAttrCanDerive

      Derivation attribute key.

      The corresponding value is of type CFBooleanRef and indicates whether this cryptographic key can be used to derive another key.

      Available in iOS 2.0 and later.

    • kSecAttrCanSign

      kSecAttrCanSign

      Signature attribute key.

      The corresponding value is of type CFBooleanRef and indicates whether this cryptographic key can be used to create a digital signature.

      Available in iOS 2.0 and later.

    • kSecAttrCanVerify

      kSecAttrCanVerify

      Signature verification attribute key.

      The corresponding value is of type CFBooleanRef and indicates whether this cryptographic key can be used to verify a digital signature.

      Available in iOS 2.0 and later.

    • kSecAttrCanWrap

      kSecAttrCanWrap

      Wrap attribute key.

      The corresponding value is of type CFBooleanRef and indicates whether this cryptographic key can be used to wrap another key.

      Available in iOS 2.0 and later.

    • kSecAttrCanUnwrap

      kSecAttrCanUnwrap

      Unwrap attribute key.

      The corresponding value is of type CFBooleanRef and indicates whether this cryptographic key can be used to unwrap another key.

      Available in iOS 2.0 and later.

    • kSecAttrAccessGroup

      kSecAttrAccessGroup

      Access group key.

      The corresponding value is of type CFStringRef and indicates which access group an item is in. Access groups can be used to share keychain items among two or more applications. For applications to share a keychain item, the applications must have a common access group listed in their keychain-access-groups entitlement, and the application adding the shared item to the keychain must specify this shared access-group name as the value for this key in the dictionary passed to the SecItemAdd function.

      An application can be a member of any number of access groups. By default, the SecItemUpdate, SecItemDelete, and SecItemCopyMatching functions search all the access groups an application is a member of. Include this key in the search dictionary for these functions to specify which access group is searched.

      A keychain item can be in only a single access group.

      Available in iOS 3.0 and later.

    Discussion

    These predefined item attribute keys are used to get or set values in a dictionary. Not all attributes apply to each item class.

  • Values that can be used with the kSecAttrProtocol attribute key.

    Declaration

    Swift

    var kSecAttrProtocolFTP: CFStringRef var kSecAttrProtocolFTPAccount: CFStringRef var kSecAttrProtocolHTTP: CFStringRef var kSecAttrProtocolIRC: CFStringRef var kSecAttrProtocolNNTP: CFStringRef var kSecAttrProtocolPOP3: CFStringRef var kSecAttrProtocolSMTP: CFStringRef var kSecAttrProtocolSOCKS: CFStringRef var kSecAttrProtocolIMAP: CFStringRef var kSecAttrProtocolLDAP: CFStringRef var kSecAttrProtocolAppleTalk: CFStringRef var kSecAttrProtocolAFP: CFStringRef var kSecAttrProtocolTelnet: CFStringRef var kSecAttrProtocolSSH: CFStringRef var kSecAttrProtocolFTPS: CFStringRef var kSecAttrProtocolHTTPS: CFStringRef var kSecAttrProtocolHTTPProxy: CFStringRef var kSecAttrProtocolHTTPSProxy: CFStringRef var kSecAttrProtocolFTPProxy: CFStringRef var kSecAttrProtocolSMB: CFStringRef var kSecAttrProtocolRTSP: CFStringRef var kSecAttrProtocolRTSPProxy: CFStringRef var kSecAttrProtocolDAAP: CFStringRef var kSecAttrProtocolEPPC: CFStringRef var kSecAttrProtocolIPP: CFStringRef var kSecAttrProtocolNNTPS: CFStringRef var kSecAttrProtocolLDAPS: CFStringRef var kSecAttrProtocolTelnetS: CFStringRef var kSecAttrProtocolIMAPS: CFStringRef var kSecAttrProtocolIRCS: CFStringRef var kSecAttrProtocolPOP3S: CFStringRef

    Objective-C

    CFTypeRef kSecAttrProtocolFTP; CFTypeRef kSecAttrProtocolFTPAccount; CFTypeRef kSecAttrProtocolHTTP; CFTypeRef kSecAttrProtocolIRC; CFTypeRef kSecAttrProtocolNNTP; CFTypeRef kSecAttrProtocolPOP3; CFTypeRef kSecAttrProtocolSMTP; CFTypeRef kSecAttrProtocolSOCKS; CFTypeRef kSecAttrProtocolIMAP; CFTypeRef kSecAttrProtocolLDAP; CFTypeRef kSecAttrProtocolAppleTalk; CFTypeRef kSecAttrProtocolAFP; CFTypeRef kSecAttrProtocolTelnet; CFTypeRef kSecAttrProtocolSSH; CFTypeRef kSecAttrProtocolFTPS; CFTypeRef kSecAttrProtocolHTTPS; CFTypeRef kSecAttrProtocolHTTPProxy; CFTypeRef kSecAttrProtocolHTTPSProxy; CFTypeRef kSecAttrProtocolFTPProxy; CFTypeRef kSecAttrProtocolSMB; CFTypeRef kSecAttrProtocolRTSP; CFTypeRef kSecAttrProtocolRTSPProxy; CFTypeRef kSecAttrProtocolDAAP; CFTypeRef kSecAttrProtocolEPPC; CFTypeRef kSecAttrProtocolIPP; CFTypeRef kSecAttrProtocolNNTPS; CFTypeRef kSecAttrProtocolLDAPS; CFTypeRef kSecAttrProtocolTelnetS; CFTypeRef kSecAttrProtocolIMAPS; CFTypeRef kSecAttrProtocolIRCS; CFTypeRef kSecAttrProtocolPOP3S;

    Constants

    • kSecAttrProtocolFTP

      kSecAttrProtocolFTP

      FTP protocol.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolFTPAccount

      kSecAttrProtocolFTPAccount

      A client side FTP account.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolHTTP

      kSecAttrProtocolHTTP

      HTTP protocol.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolIRC

      kSecAttrProtocolIRC

      IRC protocol.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolNNTP

      kSecAttrProtocolNNTP

      NNTP protocol.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolPOP3

      kSecAttrProtocolPOP3

      POP3 protocol.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolSMTP

      kSecAttrProtocolSMTP

      SMTP protocol.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolSOCKS

      kSecAttrProtocolSOCKS

      SOCKS protocol.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolIMAP

      kSecAttrProtocolIMAP

      IMAP protocol.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolLDAP

      kSecAttrProtocolLDAP

      LDAP protocol.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolAppleTalk

      kSecAttrProtocolAppleTalk

      AFP over AppleTalk.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolAFP

      kSecAttrProtocolAFP

      AFP over TCP.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolTelnet

      kSecAttrProtocolTelnet

      Telnet protocol.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolSSH

      kSecAttrProtocolSSH

      SSH protocol.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolFTPS

      kSecAttrProtocolFTPS

      FTP over TLS/SSL.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolHTTPS

      kSecAttrProtocolHTTPS

      HTTP over TLS/SSL.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolHTTPProxy

      kSecAttrProtocolHTTPProxy

      HTTP proxy.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolHTTPSProxy

      kSecAttrProtocolHTTPSProxy

      HTTPS proxy.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolFTPProxy

      kSecAttrProtocolFTPProxy

      FTP proxy.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolSMB

      kSecAttrProtocolSMB

      SMB protocol.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolRTSP

      kSecAttrProtocolRTSP

      RTSP protocol.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolRTSPProxy

      kSecAttrProtocolRTSPProxy

      RTSP proxy.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolDAAP

      kSecAttrProtocolDAAP

      DAAP protocol.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolEPPC

      kSecAttrProtocolEPPC

      Remote Apple Events.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolIPP

      kSecAttrProtocolIPP

      IPP protocol.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolNNTPS

      kSecAttrProtocolNNTPS

      NNTP over TLS/SSL.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolLDAPS

      kSecAttrProtocolLDAPS

      LDAP over TLS/SSL.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolTelnetS

      kSecAttrProtocolTelnetS

      Telnet over TLS/SSL.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolIMAPS

      kSecAttrProtocolIMAPS

      IMAP over TLS/SSL.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolIRCS

      kSecAttrProtocolIRCS

      IRC over TLS/SSL.

      Available in iOS 2.0 and later.

    • kSecAttrProtocolPOP3S

      kSecAttrProtocolPOP3S

      POP3 over TLS/SSL.

      Available in iOS 2.0 and later.

  • Values that can be used with the kSecAttrAuthenticationType attribute key.

    Declaration

    Swift

    var kSecAttrAuthenticationTypeNTLM: CFStringRef var kSecAttrAuthenticationTypeMSN: CFStringRef var kSecAttrAuthenticationTypeDPA: CFStringRef var kSecAttrAuthenticationTypeRPA: CFStringRef var kSecAttrAuthenticationTypeHTTPBasic: CFStringRef var kSecAttrAuthenticationTypeHTTPDigest: CFStringRef var kSecAttrAuthenticationTypeHTMLForm: CFStringRef var kSecAttrAuthenticationTypeDefault: CFStringRef

    Objective-C

    CFTypeRef kSecAttrAuthenticationTypeNTLM; CFTypeRef kSecAttrAuthenticationTypeMSN; CFTypeRef kSecAttrAuthenticationTypeDPA; CFTypeRef kSecAttrAuthenticationTypeRPA; CFTypeRef kSecAttrAuthenticationTypeHTTPBasic; CFTypeRef kSecAttrAuthenticationTypeHTTPDigest; CFTypeRef kSecAttrAuthenticationTypeHTMLForm; CFTypeRef kSecAttrAuthenticationTypeDefault;

    Constants

    • kSecAttrAuthenticationTypeNTLM

      kSecAttrAuthenticationTypeNTLM

      Windows NT LAN Manager authentication.

      Available in iOS 2.0 and later.

    • kSecAttrAuthenticationTypeMSN

      kSecAttrAuthenticationTypeMSN

      Microsoft Network default authentication.

      Available in iOS 2.0 and later.

    • kSecAttrAuthenticationTypeDPA

      kSecAttrAuthenticationTypeDPA

      Distributed Password authentication.

      Available in iOS 2.0 and later.

    • kSecAttrAuthenticationTypeRPA

      kSecAttrAuthenticationTypeRPA

      Remote Password authentication.

      Available in iOS 2.0 and later.

    • kSecAttrAuthenticationTypeHTTPBasic

      kSecAttrAuthenticationTypeHTTPBasic

      HTTP Basic authentication.

      Available in iOS 2.0 and later.

    • kSecAttrAuthenticationTypeHTTPDigest

      kSecAttrAuthenticationTypeHTTPDigest

      HTTP Digest Access authentication.

      Available in iOS 2.0 and later.

    • kSecAttrAuthenticationTypeHTMLForm

      kSecAttrAuthenticationTypeHTMLForm

      HTML form based authentication.

      Available in iOS 2.0 and later.

    • kSecAttrAuthenticationTypeDefault

      kSecAttrAuthenticationTypeDefault

      The default authentication type.

      Available in iOS 2.0 and later.

  • Values that can be used with the kSecAttrKeyClass attribute key.

    Declaration

    Swift

    var kSecAttrKeyClassPublic: CFStringRef var kSecAttrKeyClassPrivate: CFStringRef var kSecAttrKeyClassSymmetric: CFStringRef

    Objective-C

    CFTypeRef kSecAttrKeyClassPublic; CFTypeRef kSecAttrKeyClassPrivate; CFTypeRef kSecAttrKeyClassSymmetric;

    Constants

    • kSecAttrKeyClassPublic

      kSecAttrKeyClassPublic

      A public key of a public-private pair.

      Available in iOS 2.0 and later.

    • kSecAttrKeyClassPrivate

      kSecAttrKeyClassPrivate

      A private key of a public-private pair.

      Available in iOS 2.0 and later.

    • kSecAttrKeyClassSymmetric

      kSecAttrKeyClassSymmetric

      A private key used for symmetric-key encryption and decryption.

      Available in iOS 2.0 and later.

  • Values that can be used with the kSecAttrKeyType attribute key.

    Declaration

    Swift

    var kSecAttrKeyTypeRSA: CFStringRef

    Objective-C

    extern const CFTypeRef kSecAttrKeyTypeRSA;

    Constants

    • kSecAttrKeyTypeRSA

      kSecAttrKeyTypeRSA

      RSA algorithm.

      Available in iOS 2.0 and later.

  • These constants are legal values for kSecAttrAccessible used for determining when a keychain item should be readable.

    Declaration

    Swift

    var kSecAttrAccessibleAfterFirstUnlock: CFStringRef var kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly: CFStringRef var kSecAttrAccessibleAlways: CFStringRef var kSecAttrAccessibleAlwaysThisDeviceOnly: CFStringRef var kSecAttrAccessibleWhenUnlocked: CFStringRef var kSecAttrAccessibleWhenUnlockedThisDeviceOnly: CFStringRef

    Objective-C

    CFTypeRef kSecAttrAccessibleWhenUnlocked; CFTypeRef kSecAttrAccessibleAfterFirstUnlock; CFTypeRef kSecAttrAccessibleAlways; CFTypeRef kSecAttrAccessibleWhenUnlockedThisDeviceOnly; CFTypeRef kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly; CFTypeRef kSecAttrAccessibleAlwaysThisDeviceOnly;

    Constants

    • kSecAttrAccessibleAfterFirstUnlock

      kSecAttrAccessibleAfterFirstUnlock

      The data in the keychain item cannot be accessed after a restart until the device has been unlocked once by the user.

      After the first unlock, the data remains accessible until the next restart. This is recommended for items that need to be accessed by background applications. Items with this attribute migrate to a new device when using encrypted backups.

      Available in iOS 4.0 and later.

    • kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly

      kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly

      The data in the keychain item cannot be accessed after a restart until the device has been unlocked once by the user.

      After the first unlock, the data remains accessible until the next restart. This is recommended for items that need to be accessed by background applications. Items with this attribute do not migrate to a new device. Thus, after restoring from a backup of a different device, these items will not be present.

      Available in iOS 4.0 and later.

    • kSecAttrAccessibleAlways

      kSecAttrAccessibleAlways

      The data in the keychain item can always be accessed regardless of whether the device is locked.

      This is not recommended for application use. Items with this attribute migrate to a new device when using encrypted backups.

      Available in iOS 4.0 and later.

    • kSecAttrAccessibleAlwaysThisDeviceOnly

      kSecAttrAccessibleAlwaysThisDeviceOnly

      The data in the keychain item can always be accessed regardless of whether the device is locked.

      This is not recommended for application use. Items with this attribute do not migrate to a new device. Thus, after restoring from a backup of a different device, these items will not be present.

      Available in iOS 4.0 and later.

    • kSecAttrAccessibleWhenUnlocked

      kSecAttrAccessibleWhenUnlocked

      The data in the keychain item can be accessed only while the device is unlocked by the user.

      This is recommended for items that need to be accessible only while the application is in the foreground. Items with this attribute migrate to a new device when using encrypted backups.

      This is the default value for keychain items added without explicitly setting an accessibility constant.

      Available in iOS 4.0 and later.

    • kSecAttrAccessibleWhenUnlockedThisDeviceOnly

      kSecAttrAccessibleWhenUnlockedThisDeviceOnly

      The data in the keychain item can be accessed only while the device is unlocked by the user.

      This is recommended for items that need to be accessible only while the application is in the foreground. Items with this attribute do not migrate to a new device. Thus, after restoring from a backup of a different device, these items will not be present.

      Available in iOS 4.0 and later.

Search Keys

  • Keys used to set search attributes in a keychain search dictionary. You can specify a combination of search attributes and item attributes (see Attribute Item Keys and Values) when looking for matching items with the SecItemCopyMatching function.

    Declaration

    Swift

    var kSecMatchPolicy: CFStringRef var kSecMatchItemList: CFStringRef var kSecMatchSearchList: CFStringRef var kSecMatchIssuers: CFStringRef var kSecMatchEmailAddressIfPresent: CFStringRef var kSecMatchSubjectContains: CFStringRef var kSecMatchCaseInsensitive: CFStringRef var kSecMatchTrustedOnly: CFStringRef var kSecMatchValidOnDate: CFStringRef var kSecMatchLimit: CFStringRef var kSecMatchLimitOne: CFStringRef var kSecMatchLimitAll: CFStringRef

    Objective-C

    CFTypeRef kSecMatchPolicy; CFTypeRef kSecMatchItemList; CFTypeRef kSecMatchSearchList; CFTypeRef kSecMatchIssuers; CFTypeRef kSecMatchEmailAddressIfPresent; CFTypeRef kSecMatchSubjectContains; CFTypeRef kSecMatchCaseInsensitive; CFTypeRef kSecMatchTrustedOnly; CFTypeRef kSecMatchValidOnDate; CFTypeRef kSecMatchLimit; CFTypeRef kSecMatchLimitOne; CFTypeRef kSecMatchLimitAll;

    Constants

    • kSecMatchPolicy

      kSecMatchPolicy

      Match policy attribute key.

      The corresponding value is of type SecPolicyRef. If provided, returned certificates or identities must verify with this policy.

      Available in iOS 2.0 and later.

    • kSecMatchItemList

      kSecMatchItemList

      Item list attribute key.

      To provide your own set of items to be filtered by a search query rather than searching the keychain, specify this search key in a call to the SecItemCopyMatching function with a value that consists of an object of type CFArrayRef where the array contains either SecKeychainItemRef, SecKeyRef, SecCertificateRef, SecIdentityRef, or CFDataRef items. The objects in the provided array must all be of the same type.

      To convert from persistent item references to normal item references, specify this search key in a call to the SecItemCopyMatching function with a value of type CFArrayRef where the array contains one or more CFDataRef elements (the persistent references), and a return-type key of kSecReturnRef whose value is kCFBooleanTrue.

      To delete an item identified by a transient reference, specify the kSecMatchItemList search key in a call to the SecItemDelete function with a reference returned by using the kSecReturnRef return type key in a previous call to the SecItemCopyMatching or SecItemAdd functions.

      To delete an item identified by a persistent reference, specify the kSecMatchItemList search key in a call to the SecItemDelete function with a persistent reference returned by using the kSecReturnPersistentRef return type key to the SecItemCopyMatching or SecItemAdd functions.

      Available in iOS 2.0 and later.

    • kSecMatchSearchList

      kSecMatchSearchList

      Specifies a dictionary key whose value is a CFArray of SecKeychainRef items. If provided, the search will be limited to the keychains contained in this list.

      Available in iOS 2.0 and later.

    • kSecMatchIssuers

      kSecMatchIssuers

      Issuers attribute key.

      The corresponding value is of type CFArrayRef, where the array consists of X.500 names of type CFDataRef. If provided, returned certificates or identities are limited to those whose certificate chain contains one of the issuers provided in this list.

      Available in iOS 2.0 and later.

    • kSecMatchEmailAddressIfPresent

      kSecMatchEmailAddressIfPresent

      Email address attribute key.

      The corresponding value is of type CFStringRef and contains an RFC822 email address. If provided, returned certificates or identities are limited to those that either contain the address or do not contain any email address.

      Available in iOS 2.0 and later.

    • kSecMatchSubjectContains

      kSecMatchSubjectContains

      Subject attribute key.

      The corresponding value is of type CFStringRef. If provided, returned certificates or identities are limited to those whose subject contains this string.

      Available in iOS 2.0 and later.

    • kSecMatchCaseInsensitive

      kSecMatchCaseInsensitive

      Case sensitivity attribute key.

      The corresponding value is of type CFBooleanRef. If this value is kCFBooleanFalse, or if this attribute is not provided, then case-sensitive string matching is performed.

      Available in iOS 2.0 and later.

    • kSecMatchTrustedOnly

      kSecMatchTrustedOnly

      Trusted anchor attribute key.

      The corresponding value is of type CFBooleanRef. If this attribute is provided with A value of kCFBooleanTrue, only certificates that can be verified back to a trusted anchor are returned. If this value is kCFBooleanFalse or the attribute is not provided, then both trusted and untrusted certificates may be returned.

      Available in iOS 2.0 and later.

    • kSecMatchValidOnDate

      kSecMatchValidOnDate

      Valid-on-date attribute key.

      The corresponding value is of type CFDateRef. If provided, returned keys, certificates or identities are limited to those that are valid for the given date. Pass a value of kCFNull to indicate the current date.

      Available in iOS 2.0 and later.

    • kSecMatchLimit

      kSecMatchLimit

      Match limit attribute key.

      The corresponding value is of type CFNumberRef. If provided, this value specifies the maximum number of results to return or otherwise act upon. For a single item, specify kSecMatchLimitOne. To specify all matching items, specify kSecMatchLimitAll. The default behavior is function-dependent.

      Available in iOS 2.0 and later.

    • kSecMatchLimitOne

      kSecMatchLimitOne

      Results are limited to the first item found; used as a value for the kSecMatchLimit attribute key.

      Available in iOS 2.0 and later.

    • kSecMatchLimitAll

      kSecMatchLimitAll

      An unlimited number of results may be returned; used as a value for the kSecMatchLimit attribute key.

      Available in iOS 2.0 and later.

  • Key used to specify a list of items to search or add.

    Declaration

    Swift

    var kSecUseItemList: CFStringRef

    Objective-C

    CFTypeRef kSecUseItemList;

    Constants

    • kSecUseItemList

      kSecUseItemList

      Item list key.

      The corresponding value is of type CFArrayRef, where the array contains either SecKeychainItemRef, SecKeyRef, SecCertificateRef, SecIdentityRef, or (for persistent item references) CFDataRef items. If provided, this array is treated as the set of all possible items to search (or to add if the function being called is SecItemAdd). The items in the array must all be of the same type.

      Available in iOS 2.0 and later.

    Discussion

    When this attribute is provided, no keychains are searched.

Search Results Constants

  • Keys used to specify the type of results that should be returned by the SecItemCopyMatching or SecItemAdd function.

    Declaration

    Swift

    var kSecReturnData: CFStringRef var kSecReturnAttributes: CFStringRef var kSecReturnRef: CFStringRef var kSecReturnPersistentRef: CFStringRef

    Objective-C

    CFTypeRef kSecReturnData; CFTypeRef kSecReturnAttributes; CFTypeRef kSecReturnRef; CFTypeRef kSecReturnPersistentRef;

    Constants

    • kSecReturnData

      kSecReturnData

      Return data attribute key.

      The corresponding value is of type CFBooleanRef. A value of kCFBooleanTrue indicates that the data of an item should be returned in the form of a CFDataRef. For keys and password items, data is secret (encrypted) and may require the user to enter a password for access.

      Available in iOS 2.0 and later.

    • kSecReturnAttributes

      kSecReturnAttributes

      Return attributes attribute key.

      The corresponding value is of type CFBooleanRef. A value of kCFBooleanTrue indicates that a dictionary of the (unencrypted) attributes of an item should be returned in the form of a CFDictionaryRef.

      Available in iOS 2.0 and later.

    • kSecReturnRef

      kSecReturnRef

      Return reference attribute key.

      The corresponding value is of type CFBooleanRef. A value of kCFBooleanTrue indicates that a reference should be returned. Depending on the item class requested, the returned references may be of type SecKeychainItemRef, SecKeyRef, SecCertificateRef, SecIdentityRef, or CFDataRef.

      Available in iOS 2.0 and later.

    • kSecReturnPersistentRef

      kSecReturnPersistentRef

      Return persistent reference attribute key. A persistent reference to a credential can be stored on disk for later use or passed to other processes.

      The corresponding value is of type CFBooleanRef. A value of kCFBooleanTrue indicates that a persistent reference to an item (CFDataRef) should be returned.

      Available in iOS 2.0 and later.

    Discussion

    You can specify zero or more of these return types. If you specify more than one of these return types, Keychain Services returns the result as a CFDictionaryRef reference to a dictionary whose keys are the return types and whose values are the requested data.

  • Keys used in the results dictionary for SecItemCopyMatching or SecItemAdd, indicating the type of values returned. You can specify zero or more of these types depending on the function you are calling.

    Declaration

    Swift

    var kSecValueData: CFStringRef var kSecValueRef: CFStringRef var kSecValuePersistentRef: CFStringRef

    Objective-C

    CFTypeRef kSecValueData; CFTypeRef kSecValueRef; CFTypeRef kSecValuePersistentRef;

    Constants

    • kSecValueData

      kSecValueData

      Data attribute key. A persistent reference to a credential can be stored on disk for later use or passed to other processes.

      The corresponding value is of type CFDataRef.  For keys and password items, the data is secret (encrypted) and may require the user to enter a password for access.

      Available in iOS 2.0 and later.

    • kSecValueRef

      kSecValueRef

      Reference attribute key.

      The corresponding value, depending on the item class requested, is of type SecKeychainItemRef, SecKeyRef, SecCertificateRef, or SecIdentityRef.

      Available in iOS 2.0 and later.

    • kSecValuePersistentRef

      kSecValuePersistentRef

      Persistent reference attribute key.

      The corresponding value is of type CFDataRef. The bytes in this CFDataRef can be stored by the caller and used on a subsequent invocation of the application (or even a different application) to retrieve the item referenced by it.

      Available in iOS 2.0 and later.

Result Codes

The most common result codes returned by Keychain Services are listed in the table below. The assigned error space for Keychain Services is discontinuous: –25240 through –25279 and –25290 through –25329. Keychain Item Services may also return noErr (0) or paramErr (–50), or CSSM result codes (see Common Security: CDSA and CSSM, version 2 (with corrigenda) from The Open Group (http://www.opengroup.org/security/cdsa.htm)).

  • No error.

    Value

    0

    Description

    No error.

    Available in iOS 2.0 and later.

  • Function or operation not implemented.

    Value

    -4

    Description

    Function or operation not implemented.

    Available in iOS 2.0 and later.

  • One or more parameters passed to the function were not valid.

    Value

    -50

    Description

    One or more parameters passed to the function were not valid.

    Available in iOS 2.0 and later.

  • Failed to allocate memory.

    Value

    -108

    Description

    Failed to allocate memory.

    Available in iOS 2.0 and later.

  • No trust results are available.

    Value

    –25291

    Description

    No trust results are available.

    Available in iOS 2.0 and later.

  • Authorization/Authentication failed.

    Value

    –25293

    Description

    Authorization/Authentication failed.

    Available in iOS 4.2 and later.

  • The item already exists.

    Value

    –25299

    Description

    The item already exists.

    Available in iOS 2.0 and later.

  • The item cannot be found.

    Value

    –25300

    Description

    The item cannot be found.

    Available in iOS 2.0 and later.

  • Interaction with the Security Server is not allowed.

    Value

    –25308

    Description

    Interaction with the Security Server is not allowed.

    Available in iOS 2.0 and later.

  • Unable to decode the provided data.

    Value

    -26275

    Description

    Unable to decode the provided data.

    Available in iOS 2.0 and later.