Returns one or more keychain items that match a search query, or copies attributes of specific keychain items.
- iOS 2.0+
- macOS 10.6+
- tvOS 2.0+
- watchOS 2.0+
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.
You specify attributes defining a search by adding key-value pairs to the query dictionary.
A typical query consists of:
One or more attribute key-value pairs (Attribute Item Keys and Values), which specify the attribute data to be matched.
One or more search key-value pairs (Search Keys), which specify values that further refine the search.
A return-type key-value pair (Search Results Constants), specifying the type of results you desire.
Return types (Search Results Constants) are specified as follows:
To obtain a reference (of type
CFData) to the data of a matching item, specify
kwith a value of
Sec Return Data
k. For key items, the resulting data has the same format as the return value of the function
Key Copy External Representation(_: _:)
To obtain a persistent reference (of type
CFData) to a matching item, specify
kwith a value of
Sec Return Persistent Ref
k. 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,
Sec Return Ref
k), the results are returned as a dictionary (that is, an object of type
Sec Return Attributes
CFDictionary) 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
k with a value greater than
1. The result will be an object of type
CFArray 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
k and provide as its value a
CFArray object containing items of type
Sec. The objects in the provided array must all be of the same type.
To convert from persistent item references to normal item references, specify the search key
k with a value that consists of an object of type
CFArray referencing an array containing one or more elements of type
CFData (the persistent references), and a return-type key of
k whose value is
k. 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 specifying an array of keychain access groups to which the application belongs. When you call the
Sec function to add an item to the keychain, you can specify the access group to which that item should belong. By default, the
Sec function searches all the access groups to which the application belongs. However, you can add the
k key to the search dictionary to specify which access group to search for keychain items.