Search Attribute Keys and Values

Filter a keychain item search.

Overview

When looking for items using any of the SecItemCopyMatching, SecItemUpdate, or SecItemDelete functions, you specify a query dictionary containing both the item attributes to look for (see Item Attribute Keys and Values) and additional search attributes that condition the search. For example, you can use the matching key kSecMatchLimit with value kSecMatchLimitOne to restrict the output to include only the first result even when more than one item matches.

Topics

Item Search Matching Keys

Keys used to condition a keychain item search.

kSecMatchPolicy

A key whose value indicates a policy with which a matching certificate or identity must verify.

kSecMatchItemList

A key whose value indicates a list of items to search.

kSecMatchSearchList

A key whose value indicates a list of items to search.

kSecMatchIssuers

A key whose value is a string to match against a certificate or identity's issuers.

kSecMatchEmailAddressIfPresent

A key whose value is a string to match against a certificate or identity's email address.

kSecMatchSubjectContains

A key whose value is a string to look for in a certificate or identity's subject.

kSecMatchSubjectStartsWith

A key whose value is a string to match against the beginning of a certificate or identity's subject.

kSecMatchSubjectEndsWith

A key whose value is a string to match against the end of a certificate or identity's subject.

kSecMatchSubjectWholeString

A key whose value is a string to exactly match a certificate or identity's subject.

kSecMatchCaseInsensitive

A key whose value is a Boolean indicating whether case-insensitive matching is performed.

kSecMatchDiacriticInsensitive

A key whose value is a Boolean indicating whether diacritic-insensitive matching is performed.

kSecMatchWidthInsensitive

A key whose value is a Boolean indicating whether width-insensitive matching is performed.

kSecMatchTrustedOnly

A key whose value is a Boolean indicating whether untrusted certificates should be returned.

kSecMatchValidOnDate

A key whose value indicates the validity date.

kSecMatchLimit

A key whose value indicates the match limit.

Match Limit Values

Use these values with the kSecMatchLimit key.

kSecMatchLimitOne

A value that corresponds to matching exactly one item.

kSecMatchLimitAll

A value that corresponds to matching an unlimited number of items.

Additional Item Search Keys

Keys used to specify additional keychain item search options.

kSecUseItemList

A key whose value is an array of items to search.

kSecUseKeychain

A key whose value is a keychain to operate on.

kSecUseOperationPrompt

A key whose value is an operation prompt.

kSecUseNoAuthenticationUI

A key whose value is a Boolean indicating whether to disallow UI authentication.

Deprecated
kSecUseAuthenticationUI

A key whose value indicates whether the user may be prompted for authentication.

kSecUseAuthenticationContext

A key whose value indicates a local authentication context to use.

kSecUseDataProtectionKeychain

A key whose value indicates whether to treat macOS keychain items like iOS keychain items.

UI Authentication Values

Values you use with the kSecUseAuthenticationUI key.

kSecUseAuthenticationUIAllow

A value that indicates user authentication is allowed.

kSecUseAuthenticationUIFail

A value that indicates user authentication is disallowed.

kSecUseAuthenticationUISkip

A value that indicates items requiring user authentication should be skipped.

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.

Item Return Result Keys

Specify how you want returned keychain item data formatted.