Certificate, Key, and Trust Services

Overview

Certificate, Key, and Trust Services provides a C API for managing certificates, public and private keys, and trust policies. You can use these services in your application to:

  • Determine identity by matching a certificate with a private key

  • Create and request certificate objects

  • Import certificates, keys, and identities

  • Create public-private key pairs

  • Represent trust policies

Concurrency Considerations

On iOS, all the functions in this API are thread-safe and reentrant.

In OS X v10.6, some functions can block while waiting for input from the user (for example, when the user is asked to unlock a keychain or give permission to change trust settings). In general, it is safe to use the functions in this API from threads other than your main thread, but you should avoid calling the function from multiple operations, work queues, or threads concurrently. Instead, function calls should be serialized (or confined to a single thread) to prevent any potential problems. Exceptions are noted in the discussions of the relevant functions.

Symbols

Getting Type Identifiers

func SecCertificateGetTypeID()

Returns the unique identifier of the opaque type to which a SecCertificate object belongs.

func SecIdentityGetTypeID()

Returns the unique identifier of the opaque type to which a SecIdentity object belongs.

func SecKeyGetTypeID()

Returns the unique identifier of the opaque type to which a SecKey object belongs.

func SecPolicyGetTypeID()

Returns the unique identifier of the opaque type to which a SecPolicy object belongs.

func SecTrustGetTypeID()

Returns the unique identifier of the opaque type to which a SecTrust object belongs.

Managing Certificates

func SecCertificateCreateWithData(CFAllocator?, CFData)

Creates a certificate object from a DER representation of a certificate.

func SecCertificateCopyData(SecCertificate)

Returns a DER representation of a certificate given a certificate object.

func SecCertificateCopyCommonName(SecCertificate, UnsafeMutablePointer<CFString?>)

Retrieves the common name of the subject of a certificate.

func SecCertificateCopyEmailAddresses(SecCertificate, UnsafeMutablePointer<CFArray?>)

Retrieves the email addresses for the subject of a certificate.

func SecCertificateCopyNormalizedIssuerContent(SecCertificate, UnsafeMutablePointer<Unmanaged<CFError>?>?)

Returns a normalized copy of the distinguished name (DN) of the issuer of a certificate.

func SecCertificateCopyNormalizedSubjectContent(SecCertificate, UnsafeMutablePointer<Unmanaged<CFError>?>?)

Returns a normalized copy of the distinguished name (DN) of the subject of a certificate.

func SecCertificateCopyPreferred(CFString, CFArray?)

Returns the preferred certificate for the specified name and key usage.

func SecCertificateCopySubjectSummary(SecCertificate)

Returns a human-readable summary of a certificate.

func SecCertificateSetPreference(SecCertificate, CFString, uint32, CFDate?)

Sets the preferred certificate for a specified name, key use, and date.

func SecCertificateSetPreferred(SecCertificate?, CFString, CFArray?)

Sets the certificate that should be preferred for the specified name and key use.

Managing Identities

func SecIdentityCopyPreferred(CFString, CFArray?, CFArray?)

Retrieves the preferred identity for the specified name and key use.

func SecIdentityCopyPrivateKey(SecIdentity, UnsafeMutablePointer<SecKey?>)

Retrieves the private key associated with an identity.

func SecIdentityCreateWithCertificate(CFTypeRef?, SecCertificate, UnsafeMutablePointer<SecIdentity?>)

Creates a new identity for a certificate and its associated private key.

func SecIdentitySetPreferred(SecIdentity?, CFString, CFArray?)

Sets the identity that should be preferred for the specified name and key use.

func SecIdentitySetSystemIdentity(CFString, SecIdentity?)

Assigns the system-wide identity to be associated with a specified domain.

func SecPKCS12Import(CFData, CFDictionary, UnsafeMutablePointer<CFArray?>)

Returns the identities and certificates in a PKCS #12-formatted blob.

Cryptography and Digital Signatures

func SecKeyDeriveFromPassword(CFString, CFDictionary, UnsafeMutablePointer<Unmanaged<CFError>?>?)

Returns a key object in which the key data is derived from a password.

func SecKeyGetBlockSize(SecKey)

Gets the block length associated with a cryptographic key.

Managing Policies

func SecPolicyCopyProperties(SecPolicy)

Returns a dictionary containing a policy’s properties.

func SecPolicyCreateBasicX509()

Returns a policy object for the default X.509 policy.

func SecPolicyCreateSSL(Bool, CFString?)

Returns a policy object for evaluating SSL certificate chains.

Managing Trust

func SecTrustCopyAnchorCertificates(UnsafeMutablePointer<CFArray?>)

Retrieves the anchor (root) certificates stored by macOS.

func SecTrustCopyCustomAnchorCertificates(SecTrust, UnsafeMutablePointer<CFArray?>)

Retrieves the custom anchor certificates, if any, used by a given trust.

func SecTrustCopyExceptions(SecTrust)

Returns an opaque cookie containing exceptions to trust policies that will allow future evaluations of the current certificate to succeed.

func SecTrustCopyProperties(SecTrust)

Returns an array containing the properties of a trust object.

func SecTrustCopyPolicies(SecTrust, UnsafeMutablePointer<CFArray?>)

Retrieves the policies used by a given trust management object.

func SecTrustCopyPublicKey(SecTrust)

Returns the public key for a leaf certificate after it has been evaluated.

func SecTrustCreateWithCertificates(CFTypeRef, CFTypeRef?, UnsafeMutablePointer<SecTrust?>)

Creates a trust management object based on certificates and policies.

func SecTrustEvaluate(SecTrust, UnsafeMutablePointer<SecTrustResultType>?)

Evaluates trust for the specified certificate and policies.

func SecTrustEvaluateAsync(SecTrust, DispatchQueue?, SecTrustCallback)

Evaluates a trust object asynchronously on the specified dispatch queue.

func SecTrustGetCertificateCount(SecTrust)

Returns the number of certificates in an evaluated certificate chain.

func SecTrustGetCertificateAtIndex(SecTrust, CFIndex)

Returns a specific certificate from the certificate chain used to evaluate trust.

func SecTrustGetTrustResult(SecTrust, UnsafeMutablePointer<SecTrustResultType>)

Returns the result code from the most recent trust evaluation.

func SecTrustGetVerifyTime(SecTrust)

Gets the absolute time against which the certificates in a trust management object are verified.

func SecTrustSetAnchorCertificates(SecTrust, CFArray)

Sets the anchor certificates used when evaluating a trust management object.

func SecTrustSetAnchorCertificatesOnly(SecTrust, Bool)

Reenables trusting built-in anchor certificates.

func SecTrustSetExceptions(SecTrust, CFData?)

Sets a list of exceptions that should be ignored when evaluating the certificate.

func SecTrustSetKeychains(SecTrust, CFTypeRef?)

Sets the keychains searched for intermediate certificates when evaluating a trust management object.

func SecTrustSetOptions(SecTrust, SecTrustOptionFlags)

Sets option flags for customizing evaluation of a trust object.

func SecTrustSetPolicies(SecTrust, CFTypeRef)

Set the policies to use in an evaluation.

func SecTrustSetVerifyDate(SecTrust, CFDate)

Sets the date and time against which the certificates in a trust management object are verified.

Managing Trust Settings

func SecTrustSettingsCopyCertificates(SecTrustSettingsDomain, UnsafeMutablePointer<CFArray?>?)

Obtains an array of all certificates that have trust settings in a specific trust settings domain.

func SecTrustSettingsCopyModificationDate(SecCertificate, SecTrustSettingsDomain, UnsafeMutablePointer<CFDate?>)

Obtains the date and time at which a certificate’s trust settings were last modified.

func SecTrustSettingsCreateExternalRepresentation(SecTrustSettingsDomain, UnsafeMutablePointer<CFData?>)

Obtains an external, portable representation of the specified domain's trust settings.

Reporting Errors

func SecCopyErrorMessageString(OSStatus, UnsafeMutableRawPointer?)

Returns a string explaining the meaning of a security result code.

Data Types

SecCertificate

Abstract Core Foundation-type object representing an X.509 certificate.

SecIdentity

Abstract Core Foundation-type object representing an identity.

SecIdentitySearch

Contains information about an identity search.

SecKey

Abstract Core Foundation-type object representing an asymmetric key.

SecPolicy

Contains information about a policy.

SecPolicySearch

Contains information about a policy search.

SecPublicKeyHash

Represents a 20-byte public key hash.

SecTrust

Contains information about trust management.

SecKeyGeneratePairBlock

Block called with the results of a call to SecKeyGeneratePairAsync(_:_:_:).

SecTrustCallback

Block called with the results of a call to SecTrustEvaluateAsync(_:_:_:).

Constants

Certificate Item Attribute Constants

Indicates certificate item attributes.

SecPadding

Specifies the type of padding to be used when creating or verifying a digital signature.

SecTrustResultType

Specifies the trust result type.

PKCS #12 Import Item Keys

Dictionary keys used in the dictionaries returned by the SecPKCS12Import(_:_:_:) function.

System Identity Domains

Domains for which you can set or obtain a system-wide identity.

SecCredentialType

The credential type to be returned by SecKeyGetCredentials.

SecTrustSettingsDomain

The trust settings domains used by the trust settings API.

SecTrustSettingsKeyUsage

Allowed uses for the encryption key in a certificate.

Trust Settings Usage Constraints Dictionary Keys

The keys in one usage constraints dictionary.

SecTrustSettingsResult

Effective trust settings for usage constraints dictionaries used by the SecTrustSettingsCopyTrustSettings(_:_:_:) and SecTrustSettingsSetTrustSettings(_:_:_:) functions.

Property Type Keys

Type values that can appear in the kSecPropertyKeyType key in dictionary entries returned by SecCertificateCopyValues(_:_:_:).

Certificate Usage Constants

Constants that represent allowed certificate use.

SecTrustOptionFlags

Trust option flags used for SecTrustSetOptions(_:_:).

SecKeySizes

Supported sizes for keys of various common types.

Standard Policies for Specific Certificate Types

Special OIDs that cause a certificate to be evaluated based on security policies specific to a given type of certificate.

Result Codes

The most common result codes returned by Certificate, Key, and Trust Services are listed in the table below. The assigned error space is discontinuous: –25240..–25279 and –25290..–25329.

var errSecUnimplemented: OSStatus

Function or operation not implemented.

var errSecParam: OSStatus

One or more parameters passed to the function were not valid.

var errSecAllocate: OSStatus

Failed to allocate memory.

var errSecNotAvailable: OSStatus

No trust results are available.

var errSecAuthFailed: OSStatus

Authorization/Authentication failed.

var errSecNoSuchKeychain: OSStatus

The keychain does not exist.

var errSecInvalidKeychain: OSStatus

The keychain is not valid.

var errSecDuplicateKeychain: OSStatus

A keychain with the same name already exists.

var errSecDuplicateItem: OSStatus

The item already exists.

var errSecItemNotFound: OSStatus

The item cannot be found.

var errSecBufferTooSmall: OSStatus

The buffer is too small.

var errSecDataTooLarge: OSStatus

The data is too large for the particular data type.

var errSecNoSuchAttr: OSStatus

The attribute does not exist.

var errSecInvalidItemRef: OSStatus

The item reference is invalid.

var errSecInvalidSearchRef: OSStatus

The search reference is invalid.

var errSecNoSuchClass: OSStatus

The keychain item class does not exist.

var errSecNoDefaultKeychain: OSStatus

A default keychain does not exist.

var errSecInteractionNotAllowed: OSStatus

Interaction with the Security Server is not allowed.

var errSecReadOnlyAttr: OSStatus

The attribute is read only.

var errSecWrongSecVersion: OSStatus

The version is incorrect.

var errSecKeySizeNotAllowed: OSStatus

The key size is not allowed.

var errSecNoStorageModule: OSStatus

There is no storage module available.

var errSecNoCertificateModule: OSStatus

There is no certificate module available.

var errSecNoPolicyModule: OSStatus

There is no policy module available.

var errSecInteractionRequired: OSStatus

User interaction is required.

var errSecDataNotAvailable: OSStatus

The data is not available.

var errSecDataNotModifiable: OSStatus

The data is not modifiable.

var errSecCreateChainFailed: OSStatus

The attempt to create a certificate chain failed.

var errSecInvalidPrefsDomain: OSStatus

The preference domain specified is invalid. This error is available in macOS 10.3 and later.

var errSecACLNotSimple: OSStatus

The access control list is not in standard simple form.

var errSecPolicyNotFound: OSStatus

The policy specified cannot be found.

var errSecInvalidTrustSetting: OSStatus

The trust setting is invalid.

var errSecNoAccessForItem: OSStatus

The specified item has no access control.

var errSecInvalidOwnerEdit: OSStatus

An invalid attempt to change the owner of an item.

var errSecTrustNotAvailable: OSStatus

No trust results are available.

var errSecDecode: OSStatus

Unable to decode the provided data.