Certificate, Key, and Trust Services

The functions and constants of the Security Framework used to manage certificates, keys, and trust policies.

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 Sec​Certificate​Get​Type​ID()

Returns the unique identifier of the opaque type to which a Sec​Certificate object belongs.

func Sec​Identity​Get​Type​ID()

Returns the unique identifier of the opaque type to which a Sec​Identity object belongs.

func Sec​Key​Get​Type​ID()

Returns the unique identifier of the opaque type to which a Sec​Key object belongs.

func Sec​Policy​Get​Type​ID()

Returns the unique identifier of the opaque type to which a Sec​Policy object belongs.

func Sec​Trust​Get​Type​ID()

Returns the unique identifier of the opaque type to which a Sec​Trust object belongs.

Managing Certificates

func Sec​Certificate​Create​With​Data(CFAllocator?, CFData)

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

func Sec​Certificate​Copy​Data(Sec​Certificate)

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

func Sec​Certificate​Copy​Normalized​Issuer​Content(Sec​Certificate, Unsafe​Mutable​Pointer<Unmanaged<CFError>?>?)

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

Deprecated
func Sec​Certificate​Copy​Normalized​Subject​Content(Sec​Certificate, Unsafe​Mutable​Pointer<Unmanaged<CFError>?>?)

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

Deprecated
func Sec​Certificate​Copy​Preferred(CFString, CFArray?)

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

func Sec​Certificate​Copy​Public​Key(Sec​Certificate)

Retrieves the public key from a certificate.

func Sec​Certificate​Copy​Serial​Number(Sec​Certificate)

Returns a copy of a certificate’s serial number.

func Sec​Certificate​Copy​Subject​Summary(Sec​Certificate)

Returns a human-readable summary of a certificate.

func Sec​Certificate​Set​Preferred(Sec​Certificate?, CFString, CFArray?)

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

Managing Identities

func Sec​Identity​Copy​Preferred(CFString, CFArray?, CFArray?)

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

func Sec​Identity​Set​Preferred(Sec​Identity?, CFString, CFArray?)

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

func Sec​Identity​Set​System​Identity(CFString, Sec​Identity?)

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

func Sec​PKCS12Import(CFData, CFDictionary, Unsafe​Mutable​Pointer<CFArray?>)

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

Cryptography and Digital Signatures

func Sec​Key​Get​Block​Size(Sec​Key)

Gets the block length associated with a cryptographic key.

func Sec​Key​Copy​External​Representation(Sec​Key, Unsafe​Mutable​Pointer<Unmanaged<CFError>?>?)

Returns an external representation of the given key suitable for the key's type.

Managing Policies

func Sec​Policy​Copy​Properties(Sec​Policy)

Returns a dictionary containing a policy’s properties.

func Sec​Policy​Create​Basic​X509()

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

func Sec​Policy​Create​SSL(Bool, CFString?)

Returns a policy object for evaluating SSL certificate chains.

Managing Trust

func Sec​Trust​Copy​Anchor​Certificates(Unsafe​Mutable​Pointer<CFArray?>)

Retrieves the anchor (root) certificates stored by macOS.

func Sec​Trust​Copy​Custom​Anchor​Certificates(Sec​Trust, Unsafe​Mutable​Pointer<CFArray?>)

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

func Sec​Trust​Copy​Exceptions(Sec​Trust)

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

func Sec​Trust​Copy​Properties(Sec​Trust)

Returns an array containing the properties of a trust object.

func Sec​Trust​Copy​Policies(Sec​Trust, Unsafe​Mutable​Pointer<CFArray?>)

Retrieves the policies used by a given trust management object.

func Sec​Trust​Copy​Public​Key(Sec​Trust)

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

func Sec​Trust​Evaluate​Async(Sec​Trust, Dispatch​Queue?, Sec​Trust​Callback)

Evaluates a trust object asynchronously on the specified dispatch queue.

func Sec​Trust​Get​Certificate​Count(Sec​Trust)

Returns the number of certificates in an evaluated certificate chain.

func Sec​Trust​Get​Certificate​At​Index(Sec​Trust, CFIndex)

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

func Sec​Trust​Get​Verify​Time(Sec​Trust)

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

func Sec​Trust​Set​Anchor​Certificates(Sec​Trust, CFArray)

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

func Sec​Trust​Set​Anchor​Certificates​Only(Sec​Trust, Bool)

Reenables trusting built-in anchor certificates.

func Sec​Trust​Set​Exceptions(Sec​Trust, CFData?)

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

func Sec​Trust​Set​Keychains(Sec​Trust, CFType​Ref?)

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

func Sec​Trust​Set​Options(Sec​Trust, Sec​Trust​Option​Flags)

Sets option flags for customizing evaluation of a trust object.

func Sec​Trust​Set​Policies(Sec​Trust, CFType​Ref)

Set the policies to use in an evaluation.

func Sec​Trust​Set​Verify​Date(Sec​Trust, CFDate)

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

Reporting Errors

func Sec​Copy​Error​Message​String(OSStatus, Unsafe​Mutable​Raw​Pointer?)

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

Data Types

Sec​Certificate

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

Sec​Identity

Abstract Core Foundation-type object representing an identity.

Sec​Identity​Search

Contains information about an identity search.

Sec​Key

Abstract Core Foundation-type object representing an asymmetric key.

Sec​Policy

Contains information about a policy.

Sec​Policy​Search

Contains information about a policy search.

Sec​Public​Key​Hash

Represents a 20-byte public key hash.

Sec​Trust

Contains information about trust management.

Constants

Certificate Item Attribute Constants

Indicates certificate item attributes.

Sec​Padding

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

Sec​Trust​Result​Type

Specifies the trust result type.

PKCS #12 Import Item Keys

Dictionary keys used in the dictionaries returned by the Sec​PKCS12Import(_:​_:​_:​) function.

System Identity Domains

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

Sec​Credential​Type

The credential type to be returned by Sec​Key​Get​Credentials.

Sec​Trust​Settings​Domain

The trust settings domains used by the trust settings API.

Sec​Trust​Settings​Key​Usage

Allowed uses for the encryption key in a certificate.

Trust Settings Usage Constraints Dictionary Keys

The keys in one usage constraints dictionary.

Property Type Keys

Type values that can appear in the k​Sec​Property​Key​Type key in dictionary entries returned by Sec​Certificate​Copy​Values(_:​_:​_:​).

Certificate Usage Constants

Constants that represent allowed certificate use.

Sec​Key​Sizes

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 err​Sec​Unimplemented:​ OSStatus

Function or operation not implemented.

var err​Sec​Param:​ OSStatus

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

var err​Sec​Allocate:​ OSStatus

Failed to allocate memory.

var err​Sec​Not​Available:​ OSStatus

No trust results are available.

var err​Sec​Auth​Failed:​ OSStatus

Authorization/Authentication failed.

var err​Sec​Duplicate​Keychain:​ OSStatus

A keychain with the same name already exists.

var err​Sec​Data​Too​Large:​ OSStatus

The data is too large for the particular data type.

var err​Sec​No​Such​Class:​ OSStatus

The keychain item class does not exist.

var err​Sec​Interaction​Not​Allowed:​ OSStatus

Interaction with the Security Server is not allowed.

var err​Sec​No​Storage​Module:​ OSStatus

There is no storage module available.

var err​Sec​No​Certificate​Module:​ OSStatus

There is no certificate module available.

var err​Sec​No​Policy​Module:​ OSStatus

There is no policy module available.

var err​Sec​Create​Chain​Failed:​ OSStatus

The attempt to create a certificate chain failed.

var err​Sec​Invalid​Prefs​Domain:​ OSStatus

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

var err​Sec​ACLNot​Simple:​ OSStatus

The access control list is not in standard simple form.

var err​Sec​Policy​Not​Found:​ OSStatus

The policy specified cannot be found.

var err​Sec​No​Access​For​Item:​ OSStatus

The specified item has no access control.

var err​Sec​Invalid​Owner​Edit:​ OSStatus

An invalid attempt to change the owner of an item.

var err​Sec​Decode:​ OSStatus

Unable to decode the provided data.