Function

SecItemCopyMatching(_:_:)

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

Declaration

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

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 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 Result Codes. Call SecCopyErrorMessageString(_:_:) (macOS 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:

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 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 kSecMatchItemList and provide as its value a CFArray object containing items of type SecKeychainItem, SecKey, SecCertificate, or SecIdentity. 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 CFArray object containing items of type SecKeychain 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 CFArray referencing an array containing one or more elements of type CFData (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 specifying an array of keychain access groups to which the application belongs. 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.