# SecIdentityCopyPreference Returns the preferred identity for the specified name and key use. ``` OSStatus SecIdentityCopyPreference(CFStringRef name, CSSM_KEYUSE keyUsage, CFArrayRef validIssuers, SecIdentityRef*identity); ``` ## Parameters `name` A string containing a URI, RFC822 email address, DNS hostname, or other name that uniquely identifies the service requiring an identity. `keyUsage` A key use value, as defined in `Security.framework/cssmtype.h`. Pass `0` if you don’t want to specify a particular key use. `validIssuers` An array of `CFDataRef` instances whose contents are the subject names of allowable issuers, as returned by a call to `SSLCopyDistinguishedNames` (`Security.framework/SecureTransport.h`). Pass `NULL` if you don’t want to limit the search to specific issuers. `identity` On return, a reference to the preferred identity, or `NULL` if none was found. In Objective-C, call the function to release this object when you are finished with it. ## Return Value A result code. See [Security Framework Result Codes](/documentation/Security/security-framework-result-codes). ## Discussion If a preferred identity has not been set for the specified name, the returned identity reference is `NULL`. You should then typically perform a search for possible identities, using [`SecIdentitySearchCreate`](/documentation/Security/SecIdentitySearchCreate) and [`SecIdentitySearchCopyNext`](/documentation/Security/SecIdentitySearchCopyNext), allowing the user to choose from a list if more than one is found. ### Special Considerations Use [`SecIdentityCopyPreferred(_:_:_:)`](/documentation/Security/SecIdentityCopyPreferred(_:_:_:)) for new development instead. --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)