Item Return Result Keys

Specify how you want returned keychain item data formatted.

Overview

When you use one of the SecItemAdd or SecItemCopyMatching functions to add or search for keychain items, these functions return the item's data and attributes through the result parameter to which you provide a pointer. Use the item result keys described below in the corresponding query dictionary to indicate how those results should be formatted:

  • If you request a data reference with kSecReturnRef, the search returns a reference of type SecKeychainItemRef, SecKeyRef, SecCertificateRef, SecIdentityRef, or CFData, depending on the class of the item.

  • If you request a persistent data reference using kSecReturnPersistentRef, the search returns an item reference of type CFData that you can store on disk or pass between processes. You later convert persistent references to regular references with another call to the SecItemCopyMatching function, using an array of persistent references (of the same item class) as the value for the kSecMatchItemList key.

  • If you ask for the data itself with kSecReturnData, the search returns a CFData instance that holds the actual data. This is typically what you want for password items. To undo the encryption it added prior to storing the item, keychain services decrypts the data before returning it to you.

  • If you request the item’s attributes using kSecReturnAttributes or more than one return type, the search returns a dictionary. Item attributes are represented directly as key-value pairs in this dictionary, while the item’s data appears in one or more of the previously mentioned forms, and is associated with the appropriate item value type key from Item Return Result Keys.

  • When you specify a match limit greater than one, the search produces an array. Each element of the array is itself a search result formatted according to the previous rules.

Topics

Item Result Keys

Use these keys to specify the type of results to return from a keychain item search or add operation.

kSecReturnData

A key whose value is a Boolean indicating whether or not to return item data.

kSecReturnAttributes

A key whose value is a Boolean indicating whether or not to return item attributes.

kSecReturnRef

A key whose value is a Boolean indicating whether or not to return a reference to an item.

kSecReturnPersistentRef

A key whose value is a Boolean indicating whether or not to return a persistent reference to an item.

Item Value Type Keys

These keys appear in the result dictionary when you specify more than one search result key.

kSecValueData

A key whose value is the item's data.

kSecValueRef

A key whose value is a reference to the item.

kSecValuePersistentRef

A key whose value is a persistent reference to the item.

See Also

Keychain Item Search

Searching for Keychain Items

Find keychain items based on search criteria that you specify.

SecItemCopyMatching

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