Certificate, Key, and Trust Services Reference

Framework
Security/Security.h
Declared in
SecBase.h
SecCertificate.h
SecIdentity.h
SecIdentitySearch.h
SecImportExport.h
SecKey.h
SecKeychainItem.h
SecPolicy.h
SecPolicySearch.h
SecTrust.h
SecTrustSettings.h
cssmapple.h

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:

Concurrency Considerations

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

On 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.

Functions by Task

Getting Type Identifiers

Managing Certificates

Managing Identities

Cryptography and Digital Signatures

Managing Policies

Managing Trust

Managing Trust Settings

Reporting Errors

Functions

SecCertificateAddToKeychain

Adds a certificate to a keychain.

OSStatus SecCertificateAddToKeychain (
   SecCertificateRef certificate,
   SecKeychainRef keychain
);
Parameters
certificate

The certificate object for the certificate to add to the keychain.

keychain

The keychain object for the keychain to which you want to add the certificate. Pass NULL to add the certificate to the default keychain.

Discussion

This function requires a certificate object, which can, for example, be created with the SecCertificateCreateFromData function or obtained over a network (see Secure Transport Reference). If the certificate has already been added to the specified keychain, the function returns errSecDuplicateItem and does not add another copy to the keychain. The function looks at the certificate data, not at the certificate object, to determine whether the certificate is a duplicate. It considers two certificates to be duplicates if they have the same primary key attributes.

Special Considerations

If the keychain is locked, the system asks the user for a password or other token to unlock it. This function can therefore block while waiting for user input.

Availability
  • Available in OS X v10.3 and later.
Declared In
SecCertificate.h

SecCertificateCopyCommonName

Retrieves the common name of the subject of a certificate.

OSStatus SecCertificateCopyCommonName (
   SecCertificateRef certificate,
   CFStringRef *commonName
);
Parameters
certificate

The certificate object from which to retrieve the common name.

commonName

On return, points to the common name. Call the CFRelease function to release this object when you are finished with it.

Availability
  • Available in OS X v10.5 and later.
Declared In
SecCertificate.h

SecCertificateCopyData

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

CFDataRef SecCertificateCopyData (
   SecCertificateRef certificate
);
Parameters
certificate

The certificate object for which you wish to return the DER (Distinguished Encoding Rules) representation of the X.509 certificate.

Return Value

The DER representation of the certificate. Call the CFRelease function to release this object when you are finished with it. Returns NULL if the data passed in the certificate parameter is not a valid certificate object.

Availability
  • Available in OS X v10.6 and later.
Declared In
SecCertificate.h

SecCertificateCopyEmailAddresses

Retrieves the email addresses for the subject of a certificate.

OSStatus SecCertificateCopyEmailAddresses (
   SecCertificateRef certificate,
   CFArrayRef *emailAddresses
);
Parameters
certificate

The certificate object from which to retrieve the email addresses.

emailAddresses

On return, an array of zero or more CFStringRef elements, each containing one email address found in the certificate subject. Call the CFRelease function to release this object when you are finished with it.

Discussion

Not every certificate subject includes an email address. If the function does not find any email addresses, it returns a CFArrayRef object with zero elements in the array.

Availability
  • Available in OS X v10.5 and later.
Declared In
SecCertificate.h

SecCertificateCopyLongDescription

Returns a copy of the long description of a certificate.

CFStringRef SecCertificateCopyLongDescription (
   CFAllocatorRef alloc,
   SecCertificateRef certificate,
   CFErrorRef *error
);
Parameters
alloc

The allocator that should be used. Pass NULL or kCFAllocatorDefault to use the default allocator.

certificate

The certificate from which the long description should be copied.

error

A pointer to a CFErrorRef variable where an error object is stored upon failure. If not NULL, the caller is responsible for checking this variable and releasing the resulting object if it exists.

Return Value

Returns a CFStringRef object containing the long description, or NULL if an error occurred.

Discussion

The format of this string is not guaranteed to be consistent across different operating systems or versions. Do not attempt to parse it programmatically.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecCertificate.h

SecCertificateCopyNormalizedIssuerContent

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

CFDataRef SecCertificateCopyNormalizedIssuerContent (
   SecCertificateRef certificate,
   CFErrorRef *error
);
Parameters
certificate

The certificate from which the issuer’s distinguished name should be copied.

error

A pointer to a CFErrorRef variable where an error object is stored upon failure. If not NULL, the caller is responsible for checking this variable and releasing the resulting object if it exists.

Return Value

Returns a CFDataRef object containing a DER-encoded X.509 distinguished name suitable for use with SecItemCopyMatching. Returns NULL if an error occurred.

Discussion

To obtain a copy of the issuer’s distinguished name in a format suitable for display purposes, call SecCertificateCopyValues instead.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecCertificate.h

SecCertificateCopyNormalizedSubjectContent

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

CFDataRef SecCertificateCopyNormalizedSubjectContent (
   SecCertificateRef certificate,
   CFErrorRef *error
);
Parameters
certificate

The certificate from which the subject’s distinguished name should be copied.

error

A pointer to a CFErrorRef variable where an error object is stored upon failure. If not NULL, the caller is responsible for checking this variable and releasing the resulting object if it exists.

Return Value

Returns a CFDataRef object containing a DER-encoded X.509 distinguished name suitable for use with SecItemCopyMatching. Returns NULL if an error occurred.

Discussion

To obtain a copy of the subject’s distinguished name in a format suitable for display purposes, call SecCertificateCopyValues instead.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecCertificate.h

SecCertificateCopyPreferred

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

SecCertificateRef SecCertificateCopyPreferred (
   CFStringRef name,
   CFArrayRef keyUsage
);
Parameters
name

A string containing an email address (RFC 822) or other name for which a preferred certificate is requested.

keyUsage

An array containing a list of usage attributes (kSecAttrCanEncrypt, for example), or NULL if you do not want to request a certificate based on a particular usage. See Attribute Item Keys for a complete list of possible usage attributes.

Return Value

Returns the preferred certificate for the specified name and key usage, or NULL if a matching certificate does not exist. This certificate must be released by the caller.

Discussion

This function is typically used to obtain the preferred encryption certificate for an email recipient. If a preferred certificate has not been set for the supplied name, this function returns NULL. Your code should then perform a search for possible certificates by calling SecItemCopyMatching.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecCertificate.h

SecCertificateCopyPublicKey

Retrieves the public key from a certificate.

OSStatus SecCertificateCopyPublicKey (
   SecCertificateRef certificate,
   SecKeyRef *key
);
Parameters
certificate

The certificate object from which to retrieve the public key.

key

On return, points to the public key for the specified certificate. Call the CFRelease function to release this object when you are finished with it.

Availability
  • Available in OS X v10.3 and later.
Declared In
SecCertificate.h

SecCertificateCopySerialNumber

Returns a copy of a certificate’s serial number.

CFDataRef SecCertificateCopySerialNumber (
   SecCertificateRef certificate,
   CFErrorRef *error
);
Parameters
certificate

The certificate from which the serial number should be copied.

error

A pointer to a CFErrorRef variable where an error object is stored upon failure. If not NULL, the caller is responsible for checking this variable and releasing the resulting object if it exists.

Return Value

Returns a CFDataRef object containing a DER-encoded integer for the certificate’s serial number (without the tag and length fields). Returns NULL if an error occurred. The caller is responsible for releasing this object.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecCertificate.h

SecCertificateCopyShortDescription

Returns a copy of the short description of a certificate.

CFStringRef SecCertificateCopyShortDescription (
   CFAllocatorRef alloc,
   SecCertificateRef certificate,
   CFErrorRef *error
);
Parameters
alloc

The allocator that should be used. Pass NULL or kCFAllocatorDefault to use the default allocator.

certificate

The certificate from which the short description should be copied.

error

A pointer to a CFErrorRef variable where an error object is stored upon failure. If not NULL, the caller is responsible for checking this variable and releasing the resulting object if it exists.

Return Value

Returns a CFStringRef object containing the short description, or NULL if an error occurred.

Discussion

The format of this string is not guaranteed to be consistent across different operating systems or versions. Do not attempt to parse it programmatically.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecCertificate.h

SecCertificateCopySubjectSummary

Returns a human-readable summary of a certificate.

CFStringRef SecCertificateCopySubjectSummary (
   SecCertificateRef certificate
);
Parameters
certificate

The certificate object for which you wish to return a summary string.

Return Value

A string that contains a human-readable summary of the contents of the certificate. Call the CFRelease function to release this object when you are finished with it. Returns NULL if the data passed in the certificate parameter is not a valid certificate object.

Discussion

Because all the data in the string comes from the certificate, the string is in whatever language is used in the certificate.

Availability
  • Available in OS X v10.6 and later.
Declared In
SecCertificate.h

SecCertificateCopyValues

Creates a dictionary that represents a certificate's contents.

CFDictionaryRef SecCertificateCopyValues (
   SecCertificateRef certificate,
   CFArrayRef keys,
   CFErrorRef *error
);
Parameters
certificate

The certificate from which values should be copied.

keys

An array of string OID values, or NULL. If non-NULL, these OID values determine which values from the certificate to return. If NULL, all values are returned.

Only OIDs that represent top-level keys in the returned dictionary can be specified. Unknown OIDs are ignored. For a list of common OIDs, see the SecCertificateOIDs.h header file.

error

A pointer to a CFErrorRef variable where an error object is stored upon failure. If not NULL, the caller is responsible for checking this variable and releasing the resulting object if it exists.

Return Value

Returns a dictionary containing the specified values from the certificate or NULL if an error occurs.

Each entry in this dictionary is itself a dictionary with the keys described in “SecCertificateCopyValues Property Keys” (kSecPropertyKeyType, for example).

Availability
  • Available in OS X v10.7 and later.
Declared In
SecCertificate.h

SecCertificateCreateWithData

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

SecCertificateRef SecCertificateCreateWithData (
   CFAllocatorRef allocator,
   CFDataRef data
);
Parameters
allocator

The CFAllocator object you wish to use to allocate the certificate object. Pass NULL to use the default allocator.

data

A DER (Distinguished Encoding Rules) representation of an X.509 certificate.

Return Value

The newly created certificate object. Call the CFRelease function to release this object when you are finished with it. Returns NULL if the data passed in the data parameter is not a valid DER-encoded X.509 certificate.

Discussion

The certificate object returned by this function is used as input to other functions in the API.

Availability
  • Available in OS X v10.6 and later.
Related Sample Code
Declared In
SecCertificate.h

SecCertificateGetItem

Unsupported.

OSStatus SecCertificateGetItem (
   SecCertificateRef certificate,
   SecKeychainItemRef *item
);
Availability
  • Unsupported.
Declared In
SecCertificate.h

SecCertificateGetTypeID

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

CFTypeID SecCertificateGetTypeID (
   void
);
Return Value

A value that identifies the opaque type of a SecCertificateRef object.

Discussion

This function returns a value that uniquely identifies the opaque type of a SecCertificateRef object. You can compare this value to the CFTypeID identifier obtained by calling the CFGetTypeID function on a specific object. These values might change from release to release or platform to platform.

Availability
  • Available in OS X v10.3 and later.
Declared In
SecCertificate.h

SecCertificateSetPreference

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

OSStatus SecCertificateSetPreference (
   SecCertificateRef certificate,
   CFStringRef name,
   uint32 keyUsage,
   CFDateRef date
);
Parameters
certificate

The certificate object identifying the preferred certificate.

name

A string containing an email address (RFC822) or other name with which the preferred certificate is to be associated.

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.

date

The date after which this preference is no longer valid. If supplied, the preferred certificate is changed only if this date is later than the currently saved setting. Pass NULL if this preference should not be restricted by date.

Discussion

This function is typically used to set the preferred encryption certificate for an email recipient, either manually (when encrypting email to a recipient) or automatically upon receipt of encrypted email.

Special Considerations

Use SecCertificateSetPreferred for new development instead.

Because this preference is stored in the default keychain, if the keychain is locked, the system asks the user for a password or other token to unlock it. This function can therefore block while waiting for user input.

Availability
  • Available in OS X v10.5 and later.
Declared In
SecCertificate.h

SecCertificateSetPreferred

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

OSStatus SecCertificateSetPreferred (
   SecCertificateRef certificate,
   CFStringRef name,
   CFArrayRef keyUsage
);
Parameters
certificate

The key to use as the preferred certificate for the specified name and key usage.

name

A string containing an email address (RFC 822) or other name for which a preferred certificate is requested.

keyUsage

An array containing a list of usage attributes (kSecAttrCanEncrypt, for example), or NULL if you want this certificate to be preferred for any usage. See Attribute Item Keys for a complete list of possible usage attributes.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecCertificate.h

SecCopyErrorMessageString

Returns a string describing an error.

CFStringRef SecCopyErrorMessageString (
   OSStatus status,
   void *reserved
);
Parameters
status

An error result code of type OSStatus or CSSM_RETURN, as returned by a security or CSSM function.

reserved

Reserved for future use. Pass NULL in this parameter.

Return Value

A reference to a localized error string, or NULL if no error string is available for the specified result code. You must release this reference when you are finished with it by calling the CFRelease function.

Availability
  • Available in OS X v10.5 and later.
Declared In
SecBase.h

SecIdentityCopyCertificate

Retrieves a certificate associated with an identity.

OSStatus SecIdentityCopyCertificate (
   SecIdentityRef identityRef,
   SecCertificateRef *certificateRef
);
Parameters
identityRef

The identity object for the identity whose certificate you wish to retrieve.

certificateRef

On return, points to the certificate object associated with the specified identity. Call the CFRelease function to release this object when you are finished with it.

Discussion

An identity is a digital certificate together with its associated private key.

For a certificate in a keychain, you can cast the SecCertificateRef data type to a SecKeychainItemRef for use with Keychain Services functions.

Availability
  • Available in OS X v10.3 and later.
Declared In
SecIdentity.h

SecIdentityCopyPreferred

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

SecIdentityRef SecIdentityCopyPreferred (
   CFStringRef name,
   CFArrayRef keyUsage,
   CFArrayRef validIssuers
);
Parameters
name

A string containing an email address (RFC 822) or other name for which a preferred identity is requested.

keyUsage

An array containing a list of usage attributes (kSecAttrCanEncrypt, for example), or NULL if you do not want to request an identity for a particular usage. See Attribute Item Keys for a complete list of possible usage attributes.

validIssuers

An array of CFDataRef objects whose contents are the subject names of allowable issuers, as returned by a call to SSLCopyDistinguishedNames. Pass NULL to allow any issuer.

Return Value

Returns an identity, or NULL if no identity from one of the specified issuers has been set as the preferred identity for the specified name and usage.

Discussion

If a preferred identity has not been set for the supplied name, this function returns NULL. Your code should then perform a search for possible identities by calling SecItemCopyMatching.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecIdentity.h

SecIdentityCopyPrivateKey

Retrieves the private key associated with an identity.

OSStatus SecIdentityCopyPrivateKey (
   SecIdentityRef identityRef,
   SecKeyRef *privateKeyRef
);
Parameters
identityRef

The identity object for the identity whose private key you wish to retrieve.

privateKeyRef

On return, points to the private key object for the specified identity. The private key must be of class type kSecPrivateKeyItemClass. Call the CFRelease function to release this object when you are finished with it.

Discussion

An identity is a digital certificate together with its associated private key.

Availability
  • Available in OS X v10.3 and later.
Related Sample Code
Declared In
SecIdentity.h

SecIdentityCopySystemIdentity

Obtains the system-wide identity associated with a specified domain.

OSStatus SecIdentityCopySystemIdentity (
   CFStringRef domain,
   SecIdentityRef *idRef,
   CFStringRef *actualDomain
);
Parameters
domain

The domain for which you want to find an identity, typically in reverse DNS notation, such as com.apple.security. You may also pass the values defined in “System Identity Domains.”

idRef

On return, the identity object of the system-wide identity associated with the specified domain. Call the CFRelease function to release this object when you are finished with it.

actualDomain

On return, the actual domain name of the returned identity object is returned here. This may be different from the requested domain. Pass NULL if you do not want this information.

Discussion

If no system-wide identity exists for the specified domain, a domain-specific alternate may be returned instead, typically (but not exclusively) the system-wide default identity (kSecIdentityDomainDefault).

Availability
  • Available in OS X v10.5 and later.
Declared In
SecIdentity.h

SecIdentityCreateWithCertificate

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

OSStatus SecIdentityCreateWithCertificate (
   CFTypeRef keychainOrArray,
   SecCertificateRef certificateRef,
   SecIdentityRef *identityRef
);
Parameters
keychainOrArray

A reference to a keychain or an array of keychains to search for the associated private key. Specify NULL to search the user's default keychain search list.

certificateRef

The certificate for which you want to create an identity.

identityRef

On return, an identity object for the certificate and its associated private key. Call the CFRelease function to release this object when you are finished with it.

Discussion

If the associated private key is not found in one of the specified keychains, this function fails with an appropriate error code (usually errSecItemNotFound), and does not return anything in the identityRef parameter.

Availability
  • Available in OS X v10.5 and later.
Declared In
SecIdentity.h

SecIdentityGetTypeID

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

CFTypeID SecIdentityGetTypeID (
   void
);
Return Value

A value that identifies the opaque type of a SecIdentityRef object.

Discussion

This function returns a value that uniquely identifies the opaque type of a SecIdentityRef object. You can compare this value to the CFTypeID identifier obtained by calling the CFGetTypeID function on a specific object. These values might change from release to release or platform to platform.

Availability
  • Available in OS X v10.3 and later.
Declared In
SecIdentity.h

SecIdentitySetPreferred

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

OSStatus SecIdentitySetPreferred (
   SecIdentityRef identity,
   CFStringRef name,
   CFArrayRef keyUsage
);
Parameters
identity

The identity to set as preferred for the specified name and key usage.

name

A string containing an email address (RFC 822) or other name for which a preferred certificate is requested.

keyUsage

An array containing a list of usage attributes (kSecAttrCanEncrypt, for example), or NULL if you want this identity to be preferred for any usage. See Attribute Item Keys for a complete list of possible usage attributes.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecIdentity.h

SecIdentitySetSystemIdentity

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

OSStatus SecIdentitySetSystemIdentity (
   CFStringRef domain,
   SecIdentityRef idRef
);
Parameters
domain

The domain to which the specified identity will be assigned, typically in reverse DNS notation, such as com.apple.security. You may also pass the values defined in “System Identity Domains.”

idRef

The identity to be assigned to the specified domain. Pass NULL to delete any currently-assigned identity for the specified domain; in this case, it is not an error if no identity exists for the specified domain.

Discussion

The caller must be running as root.

Availability
  • Available in OS X v10.5 and later.
Declared In
SecIdentity.h

SecKeyCreateFromData

Constructs a SecKeyRef object for a symmetric key.

SecKeyRef SecKeyCreateFromData (
   CFDictionaryRef parameters,
   CFDataRef keyData,
   CFErrorRef *error
);
Parameters
parameters

A parameter dictionary that describes the key. See the discussion for details.

keyData

A CFDataRef object that contains the raw key data.

error

A pointer to a CFErrorRef variable where an error object is stored upon failure. If not NULL, the caller is responsible for checking this variable and releasing the resulting object if it exists.

Return Value

Returns a SecKeyRef object containing the symmetric key.

Discussion

The parameters dictionary must contain (at minimum) an entry for the kSecAttrKeyType key with a value of kSecAttrKeyTypeAES or any other key type defined in Key Type Value.

The keys below may be optionally set in the parameters dictionary (with a CFBooleanRef value) to override the default key usage values:

These values default to true if no value is specified.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecKey.h

SecKeyDeriveFromPassword

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

SecKeyRef SecKeyDeriveFromPassword (
   CFStringRef password,
   CFDictionaryRef parameters,
   CFErrorRef *error
);
Parameters
password

The password from which the key should be derived.

parameters

A set of parameters for deriving the password.

error

A pointer to a CFErrorRef variable where an error object is stored upon failure. If not NULL, the caller is responsible for checking this variable and releasing the resulting object if it exists.

Return Value

Returns the derived SecKeyRef object, or NULL on error.

Discussion

The parameters dictionary must contain at least the following keys:

  • kSecKeyKeyType—the type of symmetric key to generate.

  • kSecAttrSalt—a CFDataRef object containing the salt value that is mixed into the pseudorandom rounds.

The parameters dictionary may contain the following optional keys:

Availability
  • Available in OS X v10.7 and later.
Declared In
SecKey.h

SecKeyGeneratePair

Creates an asymmetric key pair.

OSStatus SecKeyGeneratePair (
   CFDictionaryRef parameters,
   SecKeyRef *publicKey,
   SecKeyRef *privateKey
);
Parameters
parameters

A dictionary of key-value pairs that specify the type of keys to be generated.

publicKey

On return, points to the keychain item object of the new public key. Call the CFRelease function to release this object when you are finished with it.

privateKey

On return, points to the keychain item object of the new private key. Call the CFRelease function to release this object when you are finished with it.

Discussion

In order to generate a key pair, the dictionary passed in the parameters parameter must contain at least the following key-value pairs:

In addition, you can specify a number of other optional attributes for the public and private keys. The way you do this depends on whether you are writing code for OS X or iOS:

  • In OS X, add the key-value pairs to the parameters dictionary directly. The specified attributes are applied to both the public and private keys.

  • In iOS, add dictionaries for the keys kSecPublicKeyAttrs and kSecPrivateKeyAttrs to the parameters dictionary, and provide the attributes in those dictionaries. The attributes specified in these dictionaries are added to either the public or private key, respectively, allowing you to apply separate attributes to each key.

The possible attributes are as follows; for details on each attribute, see Keychain Services Reference:

Availability
  • Available in OS X v10.7 and later.
Declared In
SecKey.h

SecKeyGeneratePairAsync

Generates a public/private key pair.

void SecKeyGeneratePairAsync (
   CFDictionaryRef parameters,
   dispatch_queue_t deliveryQueue,
   SecKeyGeneratePairBlock result
);
Parameters
parameters

A key generation parameter dictionary. At minimum, this must contain kSecAttrKeyType and kSecAttrKeySizeInBits. In addition, this function assumes default values for the following keys:

These default values can be overridden by adding a value for the associated key in the parameter dictionary.

deliveryQueue

The dispatch queue on which the result block should be scheduled.

result

A block of type SecKeyGeneratePairBlock that gets called with the result upon completion.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecKey.h

SecKeyGenerateSymmetric

Generates a random symmetric key.

SecKeyRef SecKeyGenerateSymmetric (
   CFDictionaryRef parameters,
   CFErrorRef *error
);
Parameters
parameters

A key generation parameter dictionary. At minimum, this must contain kSecAttrKeyType and kSecAttrKeySizeInBits. In addition, this function assumes default values for the following keys:

These default values can be overridden by adding a value for the associated key in the parameter dictionary.

When used as a replacement for SecKeyGenerate, set the kSecUseKeychain key to the keychain (SecKeychainRef) into which the key should be stored, kSecAttrLabel to a user-visible label for the key, and kSecAttrApplicationLabel to an identifier defined by your application, for subsequent use in calls to SecItemCopyMatching. Additionally, you can specify keychain access controls for the key by setting kSecAttrAccess to a SecAccessRef object.

error

A pointer to a CFErrorRef variable where an error object is stored upon failure. If not NULL, the caller is responsible for checking this variable and releasing the resulting object if it exists.

Return Value

Returns a newly generated symmetric key, or NULL upon failure.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecKey.h

SecKeyGetBlockSize

Gets the block length associated with a cryptographic key.

size_t SecKeyGetBlockSize (
   SecKeyRef key
);
Parameters
key

The key for which you want the block length.

Return Value

The block length associated with the key in bytes. If the key is an RSA key, for example, this is the size of the modulus.

Availability
  • Available in OS X v10.6 and later.
Related Sample Code
Declared In
SecKey.h

SecKeyGetTypeID

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

CFTypeID SecKeyGetTypeID (
   void
);
Return Value

A value that identifies the opaque type of a SecKeyRef object.

Discussion

This function returns a value that uniquely identifies the opaque type of a SecKeyRef object. You can compare this value to the CFTypeID identifier obtained by calling the CFGetTypeID function on a specific object. These values might change from release to release or platform to platform.

Availability
  • Available in OS X v10.3 and later.
Related Sample Code
Declared In
SecKey.h

SecKeyUnwrapSymmetric

Unwraps a wrapped symmetric key.

SecKeyRef SecKeyUnwrapSymmetric (
   CFDataRef *keyToUnwrap,
   SecKeyRef unwrappingKey,
   CFDictionaryRef parameters,
   CFErrorRef *error
);
Parameters
keyToUnwrap

The wrapped key to unwrap.

unwrappingKey

The key that must be used to unwrap keyToUnwrap.

parameters

A parameter list for the unwrapping process. This is usually either an empty dictionary or a dictionary containing a value for kSecAttrSalt.

error

A pointer to a CFErrorRef variable where an error object is stored upon failure. If not NULL, the caller is responsible for checking this variable and releasing the resulting object if it exists.

Return Value

Returns the unwrapped key, or NULL upon failure.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecKey.h

SecKeyWrapSymmetric

Wraps a symmetric key with another key.

CFDataRef SecKeyWrapSymmetric (
   SecKeyRef keyToWrap,
   SecKeyRef wrappingKey,
   CFDictionaryRef parameters,
   CFErrorRef *error
);
Parameters
keyToWrap

The key to wrap.

wrappingKey

A parameter list for the unwrapping process. This is usually either an empty dictionary or a dictionary containing a value for kSecAttrSalt.

parameters

The key to use when wrapping keyToWrap.

error

A pointer to a CFErrorRef variable where an error object is stored upon failure. If not NULL, the caller is responsible for checking this variable and releasing the resulting object if it exists.

Return Value

Returns the wrapped key, or NULL upon error.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecKey.h

SecPKCS12Import

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

OSStatus SecPKCS12Import (
   CFDataRef pkcs12_data,
   CFDictionaryRef options,
   CFArrayRef *items
);
Parameters
pkcs12_data

The PKCS #12 data you wish to decode.

options

A dictionary of key-value pairs specifying options for the function.

items

On return, an array of CFDictionary key-value dictionaries. The function returns one dictionary for each item (identity or certificate) in the PKCS #12 blob. For a list of dictionary keys, see “PKCS #12 Import Item Keys.”

Return Value

A result code. The function returns errSecSuccess if there were no errors, errSecDecode if the blob can't be read or is malformed, and errSecAuthFailed if the password was not correct or data in the blob was damaged. See “Certificate, Key, and Trust Services Result Codes.”

Discussion

Your application can import a PKCS #12–formatted blob (a file with extension .p12) containing certificates and identities, where an identity is a digital certificate together with its associated private key. You can use the SecPKCS12Import function to obtain SecIdentityRef objects (including SecCertificateRef and SecKeyRef objects) for the identities in the blob, together with SecCertificateRef objects for the certificates in the blob needed to validate the identity, and SecTrustRef trust management objects needed to evaluate trust for the identities. You can then use the Keychain Services API (see Keychain Services Reference) to put the identities and associated certificates in the keychain.

Availability
  • Available in OS X v10.6 and later.
Related Sample Code
Declared In
SecImportExport.h

SecPolicyCopyProperties

Returns a dictionary containing a policy’s properties.

CFDictionaryRef SecPolicyCopyProperties (
   SecPolicyRef policyRef
);
Parameters
policyRef

The policy from which properties should be copied.

Return Value

For a list of valid property keys that can appear in the result dictionary, see “Security Policy Keys.”

Availability
  • Available in OS X v10.7 and later.
Declared In
SecPolicy.h

SecPolicyCreateBasicX509

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

SecPolicyRef SecPolicyCreateBasicX509 (
   void
);
Return Value

The policy object. Call the CFRelease function to release the object when you are finished with it.

Availability
  • Available in OS X v10.6 and later.
Related Sample Code
Declared In
SecPolicy.h

SecPolicyCreateSSL

Returns a policy object for evaluating SSL certificate chains.

SecPolicyRef SecPolicyCreateSSL (
   Boolean server,
   CFStringRef hostname
);
Parameters
server

Specify true to return a policy for SSL server certificates.

hostname

If you specify a value for this parameter, the policy will require the specified value to match the host name in the leaf certificate.

Return Value

The policy object. Call the CFRelease function to release the object when you are finished with it.

Availability
  • Available in OS X v10.6 and later.
Declared In
SecPolicy.h

SecPolicyGetTypeID

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

CFTypeID SecPolicyGetTypeID (
   void
);
Return Value

A value that identifies the opaque type of a SecPolicyRef object.

Discussion

This function returns a value that uniquely identifies the opaque type of a SecPolicyRef object. You can compare this value to the CFTypeID identifier obtained by calling the CFGetTypeID function on a specific object. These values might change from release to release or platform to platform.

Availability
  • Available in OS X v10.3 and later.
Declared In
SecPolicy.h

SecTrustCopyAnchorCertificates

Retrieves the anchor (root) certificates stored by OS X.

OSStatus SecTrustCopyAnchorCertificates (
   CFArrayRef *anchors
);
Parameters
anchors

On return, points to an array of certificate objects for trusted anchor (root) certificates, which is the default set of anchors for the caller. Call the CFRelease function to release the CFArrayRef object when you are finished with it.

Discussion

This function retrieves the certificates in the system’s store of anchor certificates (see SecTrustSetAnchorCertificates). You can use the SecCertificateRef objects retrieved by this function as input to other functions of this API, such as SecTrustCreateWithCertificates.

It is safe to call this function concurrently on two or more threads as long as it is not used to get values from a trust management object that is simultaneously being changed by another function. For example, you can call this function on two threads at the same time, but not if you are simultaneously calling the SecTrustSetAnchorCertificates function for the same trust management object on another thread.

Availability
  • Available in OS X v10.3 and later.
Declared In
SecTrust.h

SecTrustCopyCustomAnchorCertificates

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

OSStatus SecTrustCopyCustomAnchorCertificates (
   SecTrustRef trust,
   CFArrayRef *anchors
);
Parameters
trust

The trust management object from which you wish to retrieve the custom anchor certificates.

anchors

On return, a reference to an array of SecCertificateRef objects representing the set of anchor certificates that are considered valid (trusted) anchors by the SecTrustEvaluate function when verifying a certificate using the trust management object in the trust parameter. Returns NULL if no custom anchors have been specified. Call the CFRelease function to release this object when you are finished with it.

Discussion

You can use the SecTrustSetAnchorCertificates function to set custom anchor certificates.

It is safe to call this function concurrently on two or more threads as long as it is not used to get values from a trust management object that is simultaneously being changed by another function. For example, you can call this function on two threads at the same time, but not if you are simultaneously calling the SecTrustSetAnchorCertificates function for the same trust management object on another thread.

Availability
  • Available in OS X v10.5 and later.
Declared In
SecTrust.h

SecTrustCopyExceptions

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

CFDataRef SecTrustCopyExceptions(
   SecTrustRef trust
);
Parameters
trust

The evaluated trust management object whose policies you wish to retrieve.

Return Value

An opaque cookie. If you pass this cookie to SecTrustSetExceptions, that function sets a list of exceptions for future processing of the certificate. Once this list of exceptions are set, a subsequent call to SecTrustEvaluate for that certificate will return kSecTrustResultProceed.

Note: If a new error occurs that did not occur when this function was called originally, the subsequent call to SecTrustEvaluate can still fail. For example, if the certificate expires between calling SecTrustCopyExceptions and SecTrustEvaluate, evaluation will fail.

Discussion

Normally this API should only be called after asking the user how to proceed, and even then, only if the user explicitly tells your application to trust the current certificate chain in spite of the errors presented.

Availability
  • Available in OS X v10.9 and later.
Declared In
SecTrust.h

SecTrustCopyPolicies

Retrieves the policies used by a given trust management object.

OSStatus SecTrustCopyPolicies (
   SecTrustRef trust,
   CFArrayRef *policies
);
Parameters
trust

The trust management object whose policies you wish to retrieve.

policies

On return, an array of SecPolicyRef objects for the policies used by this trust management object. Call the CFRelease function to release this object when you are finished with it.

Discussion

It is safe to call this function concurrently on two or more threads as long as it is not used to get values from a trust management object that is simultaneously being changed by another function. For example, you can call this function on two threads at the same time, but not if you are simultaneously calling the SecTrustSetPolicies function for the same trust management object on another thread.

Availability
  • Available in OS X v10.3 and later.
Declared In
SecTrust.h

SecTrustCopyProperties

Returns an array containing the properties of a trust object.

CFArrayRef SecTrustCopyProperties (
   SecTrustRef trust
);
Parameters
trust

The trust object from which properties should be copied.

Return Value

Returns an array, or NULL if the trust object has not yet been evaluated. The caller is responsible for releasing this dictionary.

The result array is an ordered array of CFDictionaryRef dictionaries, one per certificate in the chain, beginning with the leaf node at index zero (0) and continuing up to the anchor (or the last certificate in the chain if no anchor was found).

The property dictionary at index zero may also include general information about the entire chain's validity in the context of this trust evaluation. See “Property Type Keys” for a list of currently defined keys.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecTrust.h

SecTrustCopyPublicKey

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

SecKeyRef SecTrustCopyPublicKey (
   SecTrustRef trust
);
Parameters
trust

The trust management object for the certificate that has been evaluated. Use the SecTrustCreateWithCertificates function to create a trust management object.

Return Value

The leaf certificate's public key, or NULL if it the public key could not be extracted (this can happen with DSA certificate chains if the parameters in the chain cannot be found). Call the CFRelease function to release this object when you are finished with it.

Discussion

You must call the SecTrustEvaluate function before calling this function. When you call this function, it attempts to return the public key of the leaf certificate, even if the trust evaluation was unsuccessful. Even if the trust evaluation was successful, this function might still return NULL—for example, if the leaf certificate’s key can’t be extracted for some reason.

Availability
  • Available in OS X v10.7 and later.
Related Sample Code
Declared In
SecTrust.h

SecTrustCreateWithCertificates

Creates a trust management object based on certificates and policies.

OSStatus SecTrustCreateWithCertificates (
   CFArrayRef certificates,
   CFTypeRef policies,
   SecTrustRef *trustRef
);
Parameters
certificates

The certificate to be verified, plus any other certificates you think might be useful for verifying the certificate. The certificate to be verified must be the first in the array. If you want to specify only one certificate, you can pass a SecCertificateRef object; otherwise, pass an array of SecCertificateRef objects.

policies

References to one or more policies to be evaluated. You can pass a single SecPolicyRef object, or an array of one or more SecPolicyRef objects. Use the SecPolicySearchCopyNext function (not available on iOS) to obtain policy objects. If you pass in multiple policies, all policies must verify for the certificate chain to be considered valid.

trustRef

On return, points to the newly created trust management object. Call the CFRelease function to release this object when you are finished with it.

Discussion

The trust management object includes a reference to the certificate to be verified, plus pointers to the policies to be evaluated for those certificates. You can optionally include references to other certificates, including anchor certificates, that you think might be in the certificate chain needed to verify the first (leaf) certificate. Any input certificates that turn out to be irrelevant are harmlessly ignored. Call the SecTrustEvaluate function to evaluate the trust for the returned trust management object.

If not all the certificates needed to verify the leaf certificate are included in the certificates parameter, SecTrustEvaluate searches for certificates in the keychain search list (see SecTrustSetKeychains) and in the system’s store of anchor certificates (see SecTrustSetAnchorCertificates). However, you should gain a significant performance benefit by passing in the entire certificate chain, in order, in the certificates parameter.

Availability
  • Available in OS X v10.3 and later.
Related Sample Code
Declared In
SecTrust.h

SecTrustEvaluate

Evaluates trust for the specified certificate and policies.

OSStatus SecTrustEvaluate (
   SecTrustRef trust,
   SecTrustResultType *result
);
Parameters
trust

The trust management object to evaluate. A trust management object includes the certificate to be verified plus the policy or policies to be used in evaluating trust. It can optionally also include other certificates to be used in verifying the first certificate. Use the SecTrustCreateWithCertificates function to create a trust management object.

result

On return, points to a result type reflecting the result of this evaluation. See “Trust Result Type Constants” for descriptions of possible values. See the discussion below for an explanation of how to handle specific values.

Discussion

This function evaluates a certificate’s validity to establish trust for a particular use—for example, in creating a digital signature or to establish a Secure Sockets Layer connection.

Before you call this function:

  • You can call the SecTrustSetVerifyDate function before calling SecTrustEvaluate to set the date and time to use when verifying the certificate. By default, SecTrustEvaluate uses the current date and time. (Note that some APIs such as CMS may set the verification date for you based on a trusted time stamp.)

  • In OS X, you can optionally call any of the SecTrustSet... functions (such as SecTrustSetParameters or SecTrustSetVerifyDate) to set values for parameters and options.

The SecTrustEvaluate function validates a certificate by verifying its signature plus the signatures of the certificates in its certificate chain, up to the anchor certificate, according to the policy or policies included in the trust management object.

For each policy, the function usually evaluates trust according to the user-specified trust setting (see SecTrustSettingsSetTrustSettings and SecTrustSettingsCopyTrustSettings). For an example of user-specified trust settings, use the Keychain Access utility and look at any certificate. As an exception, if your app has previously called SecTrustSetAnchorCertificates, the user-specified trust settings are ignored, and the certificate’s chain must contain one of the specified anchor certificates.

For each policy, SecTrustEvaluate constructs a certificate chain based on the policies requested. It then starts with the leaf certificate and checks each certificate in the chain in turn until it either reaches a defective certificate, runs out of certificates, or reaches a certificate with a non-default trust setting—usually an anchor certificate or a certificate that the user has explicitly chosen to trust or distrust—and stores the result of this trust evaluation in the trust management object. This design means that an explicit user-trust setting for a certificate at or near the leaf can override the behavior of a certificate closer to the root, but otherwise a failure at any point in the chain results in a failure.

If some of the certificates needed to verify the leaf certificate are missing from the trust management object, then SecTrustEvaluate searches for certificates in the following locations:

  • In any keychains currently on the caller’s keychain search list (see SecTrustSetKeychains).

  • Any certificates previously provided by calling SecTrustSetAnchorCertificates.

  • In a system-provided set of keychains provided for this purpose.

  • Over the network if certain extensions are present in the certificate used to build the chain.

As a rule, you should handle the various return values as follows:

  • kSecTrustResultUnspecified—Evaluation successfully reached an (implicitly trusted) anchor certificate without any evaluation failures, but never encountered any explicitly stated user-trust preference. This is the most common return value.

    Most apps should, by default, trust the chain. If you ask the user what to do, in OS X, you should use the SFCertificateTrustPanel class in the Security Interface Framework Reference.

  • kSecTrustResultProceed—The user explicitly chose to trust a certificate in the chain (usually by clicking a button in a certificate trust panel).

    Your app should trust the chain.

  • kSecTrustResultDeny—The user explicitly chose to not trust a certificate in the chain (usually by clicking the appropriate button in a certificate trust panel).

    Your app should not trust the chain.

  • kSecTrustResultConfirm—The user previously chose to always ask for permission before accepting one of the certificates in the chain. This return value is no longer used, but may occur in older versions of OS X.

    Either ask the user what to do or reject the certificate. If you ask the user what to do, in OS X, you should use the SFCertificateTrustPanel class in the Security Interface Framework Reference.

  • kSecTrustResultRecoverableTrustFailure—This means that you should not trust the chain as-is, but that the chain could be trusted with some minor change to the evaluation context, such as ignoring expired certificates or adding an additional anchor to the set of trusted anchors.

    The way you handle this depends on the OS.

    In iOS, you should typically refuse the certificate. However, if you are performing signature validation and you know when the message was originally received, you should check again using that date to see if the message was valid when you originally received it.

    In OS X, you can call the SecTrustGetTrustResult function to get more information about the results of the trust evaluation, or the SecTrustGetCssmResult function to get information about the evaluation in a form that can be passed to CSSM functions.

    Then, as appropriate, you can call one or more of the SecTrustSet... functions to correct or bypass the problem, or you can inform the user of the problem and call the SFCertificateTrustPanel class to let the user change the trust setting for the certificate.

    When you think you have corrected the problem, call SecTrustEvaluate again. Each time you call SecTrustEvaluate, it discards the results of any previous evaluation and replaces them with the new results.

    If the trust failure was caused by an untrusted root certificate and your app asks the user what to do, you should use the SFCertificateTrustPanel class in the Security Interface Framework Reference.

  • kSecTrustResultFatalTrustFailure—Evaluation failed because a certificate in the chain is defective. This usually represents a fundamental defect in the certificate data, such as an invalid encoding for a critical subjectAltName extension, an unsupported critical extension, or some other critical portion of the certificate that could not be successfully interpreted. Changing parameter values and calling SecTrustEvaluate again is unlikely to result in a successful reevaluation unless you provide different certificates.

  • kSecTrustResultOtherError—Evaluation failed for some other reason. This can be caused by either a revoked certificate or by OS-level errors that are unrelated to the certificates themselves.

Special Considerations

It is not safe to call this function concurrently with any other function that uses the same trust management object, or to re-enter this function for the same trust management object.

Because this function might look on the network for certificates in the certificate chain, the function might block while attempting network access. You should never call it from your main thread; call it only from within a function running on a dispatch queue or on a separate thread. Alternatively, in OS X, you can use SecTrustEvaluateAsync from your main thread. In iOS, you can do the same thing using dispatch_once.

Availability
  • Available in OS X v10.3 and later.
Related Sample Code
Declared In
SecTrust.h

SecTrustEvaluateAsync

Evaluates a trust object asynchronously on the specified dispatch queue.

OSStatus SecTrustEvaluateAsync (
   SecTrustRef trust,
   dispatch_queue_t queue,
   SecTrustCallback result
);
Parameters
trust

The trust management object to evaluate. A trust management object includes the certificate to be verified plus the policy or policies to be used in evaluating trust. It can optionally also include other certificates to be used in verifying the first certificate. Use the SecTrustCreateWithCertificates function to create a trust management object.

queue

The dispatch queue on which the result block should execute.

result

A block called with the result of evaluation. See “Trust Result Type Constants” for descriptions of possible values.

Discussion

This function is functionally equivalent to SecTrustEvaluate except that it performs evaluation asynchronously and calls a block when evaluation completes. For a detailed discussion of the evaluation process, see SecTrustEvaluate.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecTrust.h

SecTrustGetCertificateAtIndex

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

SecCertificateRef SecTrustGetCertificateAtIndex (
   SecTrustRef trust,
   CFIndex ix
);
Parameters
trust

The trust management object for the certificate that has been evaluated. Use the SecTrustCreateWithCertificates function to create a trust management object and the SecTrustEvaluate function to evaluate the certificate chain.

ix

The index number of the requested certificate. Index numbers start at 0 for the leaf certificate and end at the anchor (or the last certificate if no anchor was found). Use the SecTrustGetCertificateCount function to get the total number of certificates in the chain.

Return Value

A certificate object for the requested certificate.

Discussion

You must call the SecTrustEvaluate function before calling this function.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecTrust.h

SecTrustGetCertificateCount

Returns the number of certificates in an evaluated certificate chain.

CFIndex SecTrustGetCertificateCount (
   SecTrustRef trust
);
Parameters
trust

The trust management object for the certificate that has been evaluated. Use the SecTrustCreateWithCertificates function to create a trust management object and the SecTrustEvaluate function to evaluate the certificate chain.

Return Value

The number of certificates in the certificate chain.

Discussion

You must call the SecTrustEvaluate function before calling this function.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecTrust.h

SecTrustGetTrustResult

Returns the result code from the most recent trust evaluation.

OSStatus SecTrustGetTrustResult (
   SecTrustRef trustRef,
   SecTrustResultType *result
);
Parameters
trustRef

The trust object from which results should be obtained

result

The address where the numeric result should be stored.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.” If the trust object has not yet been evaluated, the result type is kSecTrustResultInvalid.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecTrust.h

SecTrustGetTypeID

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

CFTypeID SecTrustGetTypeID (
   void
);
Return Value

A value that identifies the opaque type of a SecTrustRef object.

Discussion

This function returns a value that uniquely identifies the opaque type of a SecTrustRef object. You can compare this value to the CFTypeID identifier obtained by calling the CFGetTypeID function on a specific object. These values might change from release to release or platform to platform.

Availability
  • Available in OS X v10.3 and later.
Declared In
SecTrust.h

SecTrustGetVerifyTime

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

CFAbsoluteTime SecTrustGetVerifyTime (
   SecTrustRef trust
);
Parameters
trust

The trust management object whose verification time you want to get. A trust management object includes one or more certificates plus the policy or policies to be used in evaluating trust. Use the SecTrustCreateWithCertificates function to create a trust management object.

Return Value

The absolute time at which the certificates should be checked for validity.

Discussion

This function returns the absolute time returned by:

  1. the CFDateGetAbsoluteTime function for the date passed in to the SecTrustSetVerifyDate function, if that was called, or

  2. the last value returned by the SecTrustGetVerifyTime function, if it was called before, or

  3. the value returned by the CFAbsoluteTimeGetCurrent function if neither SecTrustSetVerifyDate nor SecTrustGetVerifyTime were ever called.

It is safe to call this function concurrently on two or more threads as long as it is not used to get a value from a trust management object that is simultaneously being changed by another function. For example, you can call this function on two threads at the same time, but not if you are simultaneously calling the SecTrustSetVerifyDate function for the same trust management object on another thread.

Availability
  • Available in OS X v10.6 and later.
Declared In
SecTrust.h

SecTrustSetAnchorCertificates

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

OSStatus SecTrustSetAnchorCertificates (
   SecTrustRef trust,
   CFArrayRef anchorCertificates
);
Parameters
trust

The trust management object containing the certificate you want to evaluate. A trust management object includes the certificate to be verified plus the policy or policies to be used in evaluating trust. It can optionally also include other certificates to be used in verifying the first certificate. Use the SecTrustCreateWithCertificates function to create a trust management object.

anchorCertificates

A reference to an array of SecCertificateRef objects representing the set of anchor certificates that are to be considered valid (trusted) anchors by the SecTrustEvaluate function when verifying a certificate. Pass NULL to restore the default set of anchor certificates.

Discussion

The SecTrustEvaluate function looks for an anchor certificate in the array of certificates specified by the SecTrustSetAnchorCertificates function, or uses a default set provided by the system. In OS X v10.3, for example, the default set of anchors was in the keychain file /System/Library/Keychains/X509Anchors. If you want to create a set of anchor certificates by modifying the default set, call the SecTrustCopyAnchorCertificates function to obtain the current set of anchor certificates, modify that set as you wish, and create a new array of certificates. Then call SecTrustSetAnchorCertificates with the modified array.

The list of custom anchor certificates is stored in the trust management object and can be retrieved with the SecTrustCopyCustomAnchorCertificates function.

Note that when you call the SecTrustSetAnchorCertificates function, you are effectively telling the SecTrustEvaluate function to use the anchor certificates in the specified array to evaluate trust regardless of any user-specified trust settings for those certificates. Furthermore, any intermediate certificates based on those anchor certificates are also trusted without consulting user trust settings.

Use the SecTrustSetKeychains function to set the keychains searched for intermediate certificates in the certificate chain.

It is safe to call this function concurrently on two or more threads as long as it is not used to change the value of a trust management object that is simultaneously being used by another function. For example, you cannot call this function on one thread at the same time as you are calling the SecTrustEvaluate function for the same trust management object on another thread, but you can call this function and simultaneously evaluate a different trust management object on another thread. Similarly, calls to functions that return information about a trust management object (such as the SecTrustCopyCustomAnchorCertificates function) may fail or return an unexpected result if this function is simultaneously changing the same trust management object on another thread.

Availability
  • Available in OS X v10.3 and later.
Declared In
SecTrust.h

SecTrustSetAnchorCertificatesOnly

Reenables trusting built-in anchor certificates.

OSStatus SecTrustSetAnchorCertificatesOnly (
   SecTrustRef trust,
   Boolean anchorCertificatesOnly
);
Parameters
trust

The trust management object containing the certificate you want to evaluate. A trust management object includes the certificate to be verified plus the policy or policies to be used in evaluating trust. It can optionally also include other certificates to be used in verifying the first certificate. Use the SecTrustCreateWithCertificates function to create a trust management object.

anchorCertificatesOnly

If true, disables trusting any anchors other than the ones passed in with the SecTrustSetAnchorCertificates function.  If false, the built-in anchor certificates are also trusted. If SecTrustSetAnchorCertificates is called and SecTrustSetAnchorCertificatesOnly is not called, only the anchors explicitly passed in are trusted.

Discussion

It is safe to call this function concurrently on two or more threads as long as it is not used to change the value of a trust management object that is simultaneously being used by another function. For example, you cannot call this function on one thread at the same time as you are calling the SecTrustEvaluate function for the same trust management object on another thread, but you can call this function and simultaneously evaluate a different trust management object on another thread. Similarly, calls to functions that return information about a trust management object (such as the SecTrustCopyCustomAnchorCertificates function) may fail or return an unexpected result if this function is simultaneously changing the same trust management object on another thread.

Availability
  • Available in OS X v10.6 and later.
Declared In
SecTrust.h

SecTrustSetExceptions

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

bool SecTrustSetExceptions(
   SecTrustRef trust,
   CFDataRef exceptions
);
Parameters
trust

The trust management object whose exception list you wish to modify.

exceptions

An opaque cookie returned by a prior call to SecTrustCopyExceptions.

Return Value

Returns true if the exceptions cookies was valid and matches the current leaf certificate, false otherwise.

Important: Even if this function returns true, you must still call SecTrustEvaluate because the evaluation can still fail if something changes between the initial evaluation and the reevaluation.

Availability
  • Available in OS X v10.9 and later.
Declared In
SecTrust.h

SecTrustSetKeychains

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

OSStatus SecTrustSetKeychains (
   SecTrustRef trust,
   CFTypeRef keychainOrArray
);
Parameters
trust

The trust management object containing the certificate you want to evaluate. A trust management object includes the certificate to be verified plus the policy or policies to be used in evaluating trust. It can optionally also include other certificates to be used in verifying the first certificate. Use the SecTrustCreateWithCertificates function to create a trust management object.

keychainOrArray

A keychain object for a single keychain to search, an array of keychain objects for a set of keychains to search, or NULL to search the user’s default keychain search list. To prevent the SecTrustEvaluate function from searching any keychains at all, pass a CFArrayRef array with no elements.

Discussion

By default, SecTrustEvaluate uses the user’s keychain search list to look for intermediate certificates in the certificate chain. Use the SecTrustSetKeychains function to change the set of keychains to be searched. If you want to modify the default set of keychains, first call the SecKeychainCopySearchList function (see Keychain Services Reference) to obtain the current keychain search list, modify that set as you wish, and create a new search list. Then you can call SecTrustSetKeychains with the modified list.

Use the SecTrustSetAnchorCertificates function to set the array of anchor certificates searched.

It is safe to call this function concurrently on two or more threads as long as it is not used to change the value of a trust management object that is simultaneously being used by another function. For example, you cannot call this function on one thread at the same time as you are calling the SecTrustEvaluate function for the same trust management object on another thread, but you can call this function and simultaneously evaluate a different trust management object on another thread. Similarly, calls to functions that return information about a trust management object (such as the SecTrustCopyCustomAnchorCertificates function) may fail or return an unexpected result if this function is simultaneously changing the same trust management object on another thread.

Availability
  • Available in OS X v10.3 and later.
Declared In
SecTrust.h

SecTrustSetOptions

Sets option flags for customizing evaluation of a trust object.

OSStatus SecTrustSetOptions (
   SecTrustRef trustRef,
   SecTrustOptionFlags options
);
Parameters
trustRef

The trust object to modify.

options

The new set of option flags. For a list of options, see “Security Trust Option Flags”.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecTrust.h

SecTrustSetPolicies

Set the policies to use in an evaluation.

OSStatus SecTrustSetPolicies (
   SecTrustRef trust,
   CFTypeRef policies
);
Parameters
trust

The trust management object whose policy list you wish to set.

policies

An array of one or more SecPolicyRef objects for the policies to be used by this trust management object. A single policy object of type SecPolicyRef may also be passed, representing an array of one policy.

Discussion

The policies you set with this function replace any already in the trust management object.

It is safe to call this function concurrently on two or more threads as long as it is not used to change the value of a trust management object that is simultaneously being used by another function. For example, you cannot call this function on one thread at the same time as you are calling the SecTrustEvaluate function for the same trust management object on another thread, but you can call this function and simultaneously evaluate a different trust management object on another thread. Similarly, calls to functions that return information about a trust management object (such as the SecTrustCopyCustomAnchorCertificates function) may fail or return an unexpected result if this function is simultaneously changing the same trust management object on another thread.

Availability
  • Available in OS X v10.3 and later.
Declared In
SecTrust.h

SecTrustSettingsCopyCertificates

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

OSStatus SecTrustSettingsCopyCertificates (
   SecTrustSettingsDomain domain,
   CFArrayRef *certArray
);
Parameters
domain

The trust settings domain for which you want a list of certificates. For possible values, see “Trust Settings Domain Constants.”

certArray

On return, an array of SecCertificateRef objects representing the certificates that have trust settings in the specified domain. Call the CFRelease function to release this object when you are finished with it.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.” Returns errSecNoTrustSettings if no trust settings exist for the specified domain.

Availability
  • Available in OS X v10.5 and later.
Declared In
SecTrustSettings.h

SecTrustSettingsCopyModificationDate

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

OSStatus SecTrustSettingsCopyModificationDate (
   SecCertificateRef certRef,
   SecTrustSettingsDomain domain,
   CFDateRef *modificationDate
);
Parameters
certRef

The certificate for which you wish to obtain the modification time. Pass the value kSecTrustSettingsDefaultRootCertSetting to obtain the modification time for the default root certificate trust settings for the domain.

domain

The trust settings domain of the trust settings for which you wish to obtain the modification time (it’s possible for a single certificate to have trust settings in more than one domain). For possible values, see “Trust Settings Domain Constants.”

modificationDate

On return, the date and time at which the certificate’s trust settings were last modified. Call the CFRelease function to release this object when you are finished with it.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.” Returns errSecItemNotFound if no trust settings exist for the specified certificate and domain.

Availability
  • Available in OS X v10.5 and later.
Declared In
SecTrustSettings.h

SecTrustSettingsCopyTrustSettings

Obtains the trust settings for a certificate.

OSStatus SecTrustSettingsCopyTrustSettings (
   SecCertificateRef certRef,
   SecTrustSettingsDomain domain,
   CFArrayRef *trustSettings
);
Parameters
certRef

The certificate for which you want the trust settings. Pass the value kSecTrustSettingsDefaultRootCertSetting to obtain the default root certificate trust settings for the domain.

domain

The trust settings domain of the trust settings that you wish to obtain. For possible values, see “Trust Settings Domain Constants.”

trustSettings

On return, an array of CFDictionary objects specifying the trust settings for the certificate. For the contents of the dictionaries, see the discussion below. Call the CFRelease function to release this object when you are finished with it.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.” Returns errSecItemNotFound if no trust settings exist for the specified certificate and domain.

Discussion

Each certificate’s trust settings are expressed as a CFArray that includes any number (including zero) of dictionaries of type CFDictionary, each of which comprises one set of usage constraints. Each usage constraints dictionary contains zero or one of each of the following key-value pairs:

Key

Value

kSecTrustSettingsPolicy

A policy object (SecPolicyRef) specifying the certificate verification policy; for example: SSL, SMIME. Use the SecPolicySearchCopyNext function to obtain a policy object.

kSecTrustSettingsApplication

A trusted application reference (SecTrustedApplicationRef) for the application checking the certificate’s trust settings. Use the SecTrustedApplicationCreateFromPath function to get this reference.

kSecTrustSettingsPolicyString

ACFString containing policy-specific data. For the SMIME policy, this string contains an email address. For the SSL policy, it contains a host name.

kSecTrustSettingsKeyUsage

ACFNumber containing an SInt32 value specifying the operations for which the encryption key in this certificate can be used. For possible values, see “Trust Settings Key Use Constants.”

kSecTrustSettingsResult

A CFNumber containing an SInt32 value indicating the effective trust setting for this usage constraints dictionary. A given usage constraints dictionary is included in the evaluation of trust for a certificate only if the specified policy, application, and key use match the use for which the certificate is being evaluated. If this is the case, then the value of the kSecTrustSettingsResult key is ORed with the results from other dictionaries to determine the overall trust setting for the certificate.

If this key is not present, a default value of kSecTrustSettingsResultTrustRoot is assumed. Because only a root certificate can have this value, a usage constraints dictionary for a non-root certificate that is missing this key is not valid.

Possible values for this key are listed in “Trust Settings Result Constants.”

kSecTrustSettingsAllowedError

A CFNumber containing an SInt32 value indicating a CSSM_RETURN result code which, if encountered during certificate verification, is ignored for that certificate. These “allowed error” values are applied to the evaluation only if the usage constraints dictionary meets the criteria described with the kSecTrustSettingsResult key. A usage constraint dictionary with no constraints but with an allowed error value causes that error to always be allowed when the certificate is being evaluated.

The overall trust settings for a certificate are the sum of all the usage constraints dictionaries that match the use for which that certificate is being evaluated. Trust settings for a given use apply if any of the dictionaries in the certificate’s trust settings array satisfies the specified use. Thus, when a certificate has multiple usage constraints dictionaries in its trust settings array, the overall trust settings for the certificate are:

((usage constraint dictionary 0 component 0) AND (usage constraint dictionary 0 component 1) AND (...)) OR ((usage constraint dictionary 1 component 0) AND (usage constraint dictionary 1 component 1) AND (...)) OR (...) ...

If the value of the kSecTrustSettingsResult component is not kSecTrustSettingsResultUnspecified for a usage constraints dictionary that has no constraints, the default value kSecTrustSettingsResultTrustRoot is assumed. To specify a value for the kSecTrustSettingsAllowedError component without explicitly trusting or distrusting the associated certificate, specify a value of kSecTrustSettingsResultUnspecified for the kSecTrustSettingsResult component.

An empty trust settings array (that is, the trustSettings parameter returns a valid but empty CFArray) means "always trust this certificate” with an overall trust setting for the certificate of kSecTrustSettingsResultTrustRoot. Note that an empty trust settings array is not the same as no trust settings (the trustSettings parameter returns NULL), which means "this certificate must be verified to a known trusted certificate”.

Note the distinction between the results kSecTrustSettingsResultTrustRoot and kSecTrustSettingsResultTrustAsRoot: The former can only be applied to root (self-signed) certificates; the latter can only be applied to non-root certificates. Therefore, an empty trust settings array for a non-root certificate is invalid, because the default value of kSecTrustSettingsResultTrustRoot is not valid for a non-root certificate.

Special Considerations

When making changes to per-user trust settings, the user is prompted with an alert panel asking for authentication (user name and password or other credentials normally used for login). Therefore, it is not possible to modify per-user trust settings when not running in a GUI environment (that is, when the user is not logged in via the login window). When making changes to system-wide trust settings, the user is prompted with an alert panel asking for an administrator’s name and password unless the calling process is running as root, in which case no further authentication is needed.

Availability
  • Available in OS X v10.5 and later.
Declared In
SecTrustSettings.h

SecTrustSettingsCreateExternalRepresentation

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

OSStatus SecTrustSettingsCreateExternalRepresentation (
   SecTrustSettingsDomain domain,
   CFDataRef *trustSettings
);
Parameters
domain

The trust settings domain for which you want an external representation of trust settings. For possible values, see “Trust Settings Domain Constants.”

trustSettings

An external representation of the domain’s trust settings. Call the CFRelease function to release this object when you are finished with it.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.” Returns errSecNoTrustSettings if no trust settings exist for the specified domain.

Discussion

Trust settings for a certificate are associated with the hash of the certificate. Whenever the system encounters a certificate with the hash value associated with the trust settings, it applies those trust settings to the certificate. This function allows you to export trust settings to a portable data format that can subsequently be imported on another machine. You can use this ability, for example, to clone trust settings to all the machines within an enterprise or university.

Availability
  • Available in OS X v10.5 and later.
Declared In
SecTrustSettings.h

SecTrustSettingsImportExternalRepresentation

Imports trust settings into a trust domain.

OSStatus SecTrustSettingsImportExternalRepresentation (
   SecTrustSettingsDomain domain,
   CFDataRef trustSettings
);
Parameters
domain

The trust settings domain into which you want to import trust settings. For possible values, see “Trust Settings Domain Constants.”

trustSettings

An external representation of the trust settings (created by the SecTrustSettingsCreateExternalRepresentation function) that you want to import.

Discussion

Trust settings for a certificate are associated with the hash of the certificate. Whenever the system encounters a certificate with the hash value associated with the trust settings, it applies those trust settings to the certificate. This function allows you to import trust settings in a portable data format that was exported from another machine. You can use this ability, for example, to clone trust settings to all the machines within an enterprise or university.

Availability
  • Available in OS X v10.5 and later.
Declared In
SecTrustSettings.h

SecTrustSettingsRemoveTrustSettings

Deletes the trust settings for a certificate.

OSStatus SecTrustSettingsRemoveTrustSettings (
   SecCertificateRef certRef,
   SecTrustSettingsDomain domain
);
Parameters
certRef

The certificate whose trust settings you wish to remove. Pass the value kSecTrustSettingsDefaultRootCertSetting to remove the default root certificate trust settings for the domain.

domain

The trust settings domain for which you wish to remove the trust settings. For possible values, see “Trust Settings Domain Constants.”

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.” Returns errSecItemNotFound if no trust settings exist for the certificate.

Discussion

If a certificate has no trust settings, the certificate must be verified to a known, trusted certificate.

Availability
  • Available in OS X v10.5 and later.
Declared In
SecTrustSettings.h

SecTrustSettingsSetTrustSettings

Specifies trust settings for a certificate.

OSStatus SecTrustSettingsSetTrustSettings (
   SecCertificateRef certRef,
   SecTrustSettingsDomain domain,
   CFTypeRef trustSettingsDictOrArray
);
Parameters
certRef

The certificate for which you want to specify the trust settings. Pass the value kSecTrustSettingsDefaultRootCertSetting to set the default root certificate trust settings for the domain.

domain

The trust settings domain of the trust settings that you wish to specify. For possible values, see “Trust Settings Domain Constants.”

trustSettingsDictOrArray

The trust settings you wish to specify for this certificate, in the form of a CFDictionary object, a CFArray of CFDictionary objects, or NULL. The contents of CFDictionary objects used to specify trust settings are detailed in the SecTrustSettingsCopyTrustSettings function description. Pass NULL if you want to specify an empty trust settings array.

Discussion

If you pass NULL for the trustSettingsDictOrArray parameter, then the trust settings for this certificate are stored as an empty trust settings array, indicating "always trust this root certificate regardless of use." This setting is valid only for a self-signed (root) certificate. To instead remove all trust settings for the certificate (interpreted as "this certificate must be verified to a known trusted certificate"), use the SecTrustSettingsRemoveTrustSettings function.

If the specified certificate already has trust settings in the specified domain, this function replaces them.

Special Considerations

When making changes to per-user trust settings, the user is prompted with an alert panel asking for authentication (user name and password or other credentials normally used for login). Therefore, it is not possible to modify per-user trust settings when not running in a GUI environment (that is, when the user is not logged in via the login window). When making changes to system-wide trust settings, the user is prompted with an alert panel asking for an administrator’s name and password unless the calling process is running as root, in which case no further authentication is needed. Note that this function might block while waiting for user input.

Availability
  • Available in OS X v10.5 and later.
Declared In
SecTrustSettings.h

SecTrustSetVerifyDate

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

OSStatus SecTrustSetVerifyDate (
   SecTrustRef trust,
   CFDateRef verifyDate
);
Parameters
trust

The trust management object whose verification date you want to set. A trust management object includes one or more certificates plus the policy or policies to be used in evaluating trust. Use the SecTrustCreateWithCertificates function to create a trust management object.

verifyDate

The date and time to use when verifying the certificate.

Discussion

By default, the SecTrustEvaluate function uses the current date and time when verifying a certificate. However, you can use SecTrustSetVerifyDate to set another date and time to use when verifying a certificate. For example, you can determine whether the certificate was valid when the document was signed rather than whether it’s valid at the present time.

It is safe to call this function concurrently on two or more threads as long as it is not used to change the value of a trust management object that is simultaneously being used by another function. For example, you cannot call this function on one thread at the same time as you are calling the SecTrustEvaluate function for the same trust management object on another thread, but you can call this function and simultaneously evaluate a different trust management object on another thread. Similarly, calls to functions that return information about a trust management object (such as the SecTrustCopyCustomAnchorCertificates function) may fail or return an unexpected result if this function is simultaneously changing the same trust management object on another thread.

Availability
  • Available in OS X v10.3 and later.
Declared In
SecTrust.h

Data Types

CSSM_TP_APPLE_EVIDENCE_INFO

Contains information about a certificate evaluation.


typedef struct {
   CSSM_TP_APPLE_CERT_STATUS   StatusBits;
   uint32                      NumStatusCodes
   CSSM_RETURN                 *StatusCodes;
   uint32                      Index;
   CSSM_DL_DB_HANDLE           DlDbHandle
   CSSM_DB_UNIQUE_RECORD_PTR   UniqueRecord;
} CSSM_TP_APPLE_EVIDENCE_INFO;
Fields
StatusBits

Indicates whether the certificate is valid and where it was found; see “Certificate Status Constants.”

NumStatusCodes

The number of CSSM_RETURN structures returned in the StatusCodes field.

StatusCodes

An array of CSSM_RETURN values indicating what problems were found with the certificate. Apple-specific values are in cssmapple.h. Standard CSSM values are defined in cssmerr.h and are discussed in “Error Codes and Error Values” in the “Trust Policy Services API” chapter of Common Security: CDSA and CSSM, version 2 (with corrigenda) from The Open Group (http://www.opengroup.org/security/cdsa.htm

Index

An index into the standard set of certificates or anchor certificates if the certificate came from one of those sets.

DlDbHandle

A CSSM object that identifies a particular database. This field is used if the certificate did not come from the standard set of certificates or anchor certificates. This value is useful only as input to functions in the CSSM API.

UniqueRecord

A CSSM object that identifies a particular record in a database. This field is used if the certificate did not come from the standard set of certificates or anchor certificates. This value is useful only as in input to functions in the CSSM API.

Discussion

An array of these structures is returned by the SecTrustGetResult function; each one describes a certificate in the certificate chain.

Availability
  • Available in OS X v10.2 and later.
Declared In
cssmapple.h

SecCertificateRef

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

typedef struct __SecCertificate *SecCertificateRef;
Discussion

A SecCertificateRef object for a certificate that is stored in a keychain can be safely cast to a SecKeychainItemRef for manipulation as a keychain item. On the other hand, if the SecCertificateRef is not stored in a keychain, casting the object to a SecKeychainItemRef and passing it to Keychain Services functions returns errors.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecBase.h

SecIdentityRef

Abstract Core Foundation-type object representing an identity.

typedef struct __SecIdentity *SecIdentityRef;
Discussion

A SecIdentityRef object contains a SecKeyRef object and an associated SecCertificateRef object.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecBase.h

SecIdentitySearchRef

Contains information about an identity search.

typedef struct OpaqueSecIdentitySearchRef *SecIdentitySearchRef;
Availability
  • Available in OS X v10.2 and later.
Declared In
SecIdentitySearch.h

SecKeyRef

Abstract Core Foundation-type object representing an asymmetric key.

typedef struct __SecKey *SecKeyRef;
Discussion

A SecKeyRef object for a key that is stored in a keychain can be safely cast to a SecKeychainItemRef for manipulation as a keychain item. On the other hand, if the SecKeyRef is not stored in a keychain, casting the object to a SecKeychainItemRef and passing it to Keychain Services functions returns errors.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecBase.h

SecPolicyRef

Contains information about a policy.

typedef struct OpaqueSecPolicyRef *SecPolicyRef;
Availability
  • Available in OS X v10.2 and later.
Declared In
SecBase.h

SecPolicySearchRef

Contains information about a policy search.

typedef struct OpaquePolicySearchRef *SecPolicySearchRef;
Availability
  • Available in OS X v10.2 and later.
Declared In
SecPolicySearch.h

SecPublicKeyHash

Represents a 20-byte public key hash.

typedef UInt8 SecPublicKeyHash[20];
Discussion

The SecPublicKeyHash type represents a hash of a public key. You can use the constant kSecPublicKeyHashItemAttr as input to functions in the Keychain Services API to set or retrieve a certificate attribute value of this type. See Keychain Services Reference for information about getting and setting attribute values.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychainItem.h

SecTrustRef

Contains information about trust management.

typedef struct __SecTrust *SecTrustRef;
Availability
  • Available in OS X v10.2 and later.
Declared In
SecTrust.h

SecTrustUserSetting

Represents user-specified trust settings.

typedef SecTrustResultType SecTrustUserSetting;
Discussion

See “Trust Result Type Constants” for possible values.

Availability
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.9.
Declared In
SecTrust.h

SecKeyGeneratePairBlock

Block called with the results of a call to SecKeyGeneratePairAsync.

typedef void (^SecKeyGeneratePairBlock)(SecKeyRef publicKey, SecKeyRef privateKey,  CFErrorRef error);
Availability
  • Available in OS X v10.7 and later.
Declared In
SecKey.h

TypeDef

Block called with the results of a call to SecTrustEvaluateAsync.

typedef void (^SecTrustCallback)(SecTrustRef trustRef, SecTrustResultType trustResult);
Availability
  • Available in OS X v10.7 and later.
Declared In
SecTrust.h

Constants

Certificate Item Attribute Constants

Indicates certificate item attributes.

enum
{
   kSecSubjectItemAttr              = 'subj',
   kSecIssuerItemAttr               = 'issu',
   kSecSerialNumberItemAttr         = 'snbr',
   kSecPublicKeyHashItemAttr        = 'hpky',
   kSecSubjectKeyIdentifierItemAttr = 'skid',
   kSecCertTypeItemAttr             = 'ctyp',
   kSecCertEncodingItemAttr         = 'cenc'
};
Constants
kSecSubjectItemAttr

DER-encoded subject distinguished name.

Available in OS X v10.2 and later.

Declared in SecCertificate.h.

kSecIssuerItemAttr

DER-encoded issuer distinguished name.

Available in OS X v10.2 and later.

Declared in SecCertificate.h.

kSecSerialNumberItemAttr

DER-encoded certificate serial number (without the tag and length).

Available in OS X v10.2 and later.

Declared in SecCertificate.h.

kSecPublicKeyHashItemAttr

Public key hash.

Available in OS X v10.2 and later.

Declared in SecCertificate.h.

kSecSubjectKeyIdentifierItemAttr

Subject key identifier.

Available in OS X v10.2 and later.

Declared in SecCertificate.h.

kSecCertTypeItemAttr

Certificate type.

Available in OS X v10.2 and later.

Declared in SecCertificate.h.

kSecCertEncodingItemAttr

Certificate encoding.

Available in OS X v10.2 and later.

Declared in SecCertificate.h.

Certificate Status Constants

Specifies the status of a certificate.

typedef uint32 CSSM_TP_APPLE_CERT_STATUS;
enum
{
   CSSM_CERT_STATUS_EXPIRED            = 0x00000001,
   CSSM_CERT_STATUS_NOT_VALID_YET      = 0x00000002,
   CSSM_CERT_STATUS_IS_IN_INPUT_CERTS  = 0x00000004,
   CSSM_CERT_STATUS_IS_IN_ANCHORS      = 0x00000008,
   CSSM_CERT_STATUS_IS_ROOT            = 0x00000010,
   CSSM_CERT_STATUS_IS_FROM_NET        = 0x00000020
};
Constants
CSSM_CERT_STATUS_EXPIRED

The certificate has expired.

Available in OS X v10.2 and later.

Declared in cssmapple.h.

CSSM_CERT_STATUS_NOT_VALID_YET

The certificate is not yet valid. In addition to the expiration, or “Not Valid After,” date and time, each certificate has a “Not Valid Before” date and time.

Available in OS X v10.2 and later.

Declared in cssmapple.h.

CSSM_CERT_STATUS_IS_IN_INPUT_CERTS

This is one of the certificates included in the array of certificates passed to the SecTrustCreateWithCertificates function.

Available in OS X v10.2 and later.

Declared in cssmapple.h.

CSSM_CERT_STATUS_IS_IN_ANCHORS

This certificate was found in the system’s store of anchor certificates (see SecTrustSetAnchorCertificates).

Available in OS X v10.2 and later.

Declared in cssmapple.h.

CSSM_CERT_STATUS_IS_ROOT

The certificate is a root certificate. If this bit is set but the CSSM_CERT_STATUS_IS_IN_ANCHORS bit is not, then this is an untrusted anchor.

Available in OS X v10.2 and later.

Declared in cssmapple.h.

CSSM_CERT_STATUS_IS_FROM_NET

The certificate was obtained through some mechanism other than the certificates stored by the operating system and those passed into the SecTrustCreateWithCertificates function. For example, the certificate might have been fetched over a network.

Available in OS X v10.3 and later.

Declared in cssmapple.h.

Discussion

If none of these bits are set, the certificate came from a standard certificate search; see the description of the SecTrustSetKeychains function.

Digital Signature Padding Types

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

typedef uint32_t SecPadding;
enum
{
   kSecPaddingNone      = 0,
   kSecPaddingPKCS1     = 1,
   kSecPaddingPKCS1MD2  = 0x8000,
   kSecPaddingPKCS1MD5  = 0x8001,
   kSecPaddingPKCS1SHA1 = 0x8002,
};
Constants
kSecPaddingNone

No padding.

Available in OS X v10.6 and later.

Declared in SecKey.h.

kSecPaddingPKCS1

PKCS1 padding.

Available in OS X v10.6 and later.

Declared in SecKey.h.

kSecPaddingPKCS1MD2

Data to be signed is an MD2 hash.

Standard ASN.1 padding is done, as well as PKCS1 padding of the underlying RSA operation. Used with SecKeyRawSign and SecKeyRawVerify only.

Available in OS X v10.6 and later.

Declared in SecKey.h.

kSecPaddingPKCS1MD5

Data to be signed is an MD5 hash.

Standard ASN.1 padding is done, as well as PKCS1 padding of the underlying RSA operation. Used with SecKeyRawSign and SecKeyRawVerify only.

Available in OS X v10.6 and later.

Declared in SecKey.h.

kSecPaddingPKCS1SHA1

Data to be signed is a SHA1 hash.

Standard ASN.1 padding will be done, as well as PKCS1 padding of the underlying RSA operation. Used with SecKeyRawSign and SecKeyRawVerify only.

Available in OS X v10.6 and later.

Declared in SecKey.h.

Trust Result Type Constants

Specifies the trust result type.

typedef uint32_t SecTrustResultType;
enum {
   kSecTrustResultInvalid,
   kSecTrustResultProceed,
   kSecTrustResultConfirm,
   kSecTrustResultDeny,
   kSecTrustResultUnspecified,
   kSecTrustResultRecoverableTrustFailure,
   kSecTrustResultFatalTrustFailure,
   kSecTrustResultOtherError
};
Constants
kSecTrustResultInvalid

Invalid setting or result. Usually, this result indicates that the SecTrustEvaluate function did not complete successfully.

Available in OS X v10.2 and later.

Declared in SecTrust.h.

kSecTrustResultProceed

The user indicated that you may trust the certificate for the purposes designated in the specified policies. This value may be returned by the SecTrustEvaluate function or stored as part of the user trust settings. In the Keychain Access utility, this value is termed “Always Trust.”

Available in OS X v10.2 and later.

Declared in SecTrust.h.

kSecTrustResultConfirm

Confirmation from the user is required before proceeding. This value may be returned by the SecTrustEvaluate function or stored as part of the user trust settings. In the Keychain Access utility, this value is termed “Ask Permission.”

Available in OS X v10.0 and later.

Deprecated in OS X v10.9.

Declared in SecTrust.h.

kSecTrustResultDeny

The user specified that the certificate should not be trusted. This value may be returned by the SecTrustEvaluate function or stored as part of the user trust settings. In the Keychain Access utility, this value is termed “Never Trust.”

Available in OS X v10.2 and later.

Declared in SecTrust.h.

kSecTrustResultUnspecified

The user did not specify a trust setting. This value may be returned by the SecTrustEvaluate function or stored as part of the user trust settings. In the Keychain Access utility, this value is termed “Use System Policy.” This is the default user setting.

Available in OS X v10.2 and later.

Declared in SecTrust.h.

kSecTrustResultRecoverableTrustFailure

Trust denied; retry after changing settings. For example, if trust is denied because the certificate has expired, you can ask the user whether to trust the certificate anyway. If the user answers yes, then use the SecTrustSettingsSetTrustSettings function to set the user trust setting to kSecTrustResultProceed and call SecTrustEvaluate again. This value may be returned by the SecTrustEvaluate function but not stored as part of the user trust settings.

Available in OS X v10.2 and later.

Declared in SecTrust.h.

kSecTrustResultFatalTrustFailure

Trust denied; no simple fix is available. For example, if a certificate cannot be verified because it is corrupted, trust cannot be established without replacing the certificate. This value may be returned by the SecTrustEvaluate function but not stored as part of the user trust settings.

Available in OS X v10.2 and later.

Declared in SecTrust.h.

kSecTrustResultOtherError

A failure other than that of trust evaluation; for example, an internal failure of the SecTrustEvaluate function. This value may be returned by the SecTrustEvaluate function but not stored as part of the user trust settings.

Available in OS X v10.2 and later.

Declared in SecTrust.h.

Discussion

These constants may be returned by the SecTrustEvaluate function or stored as one of the user trust settings (see SecTrustSettingsSetTrustSettings), as noted. When evaluating user trust, SecTrustEvaluate starts with the leaf certificate and works through the chain down to the anchor. The SecTrustSettingsCopyTrustSettings function returns the user trust setting of the first certificate for which the setting is other than kSecTrustResultUnspecified. Similarly, the function uses the user trust setting of the first certificate for which the setting is other than kSecTrustResultUnspecified, regardless of the user trust settings of other certificates in the chain.

Action Data Flags

Specifies options for the AppleX509TP trust policy module’s default action.

typedef uint32 CSSM_APPLE_TP_ACTION_FLAGS;
enum {
   CSSM_TP_ACTION_ALLOW_EXPIRED        = 0x00000001,
   CSSM_TP_ACTION_LEAF_IS_CA           = 0x00000002,
   CSSM_TP_ACTION_FETCH_CERT_FROM_NET  = 0x00000004,
   CSSM_TP_ACTION_ALLOW_EXPIRED_ROOT   = 0x00000008
};
Constants
CSSM_TP_ACTION_ALLOW_EXPIRED

Ignore the expiration date and time for all certificates.

Available in OS X v10.2 and later.

Declared in cssmapple.h.

CSSM_TP_ACTION_LEAF_IS_CA

First certificate is that of a certification authority (CA). By formal definition, a valid certificate chain must begin with a certificate that is not a CA. Set this bit if you want to validate a partial chain, starting with a CA and working toward the anchor, or if you want to evaluate a single self-signed certificate as a one-certificate “chain” for testing purposes.

Available in OS X v10.3 and later.

Declared in cssmapple.h.

CSSM_TP_ACTION_FETCH_CERT_FROM_NET

Enable fetching intermediate certificates over the network using http or LDAP.

Available in OS X v10.3 and later.

Declared in cssmapple.h.

CSSM_TP_ACTION_ALLOW_EXPIRED_ROOT

Ignore the expiration date and time for root certificates only.

Available in OS X v10.2 and later.

Declared in cssmapple.h.

Discussion

See SecTrustSetParameters for more information about actions.

PKCS #12 Import Item Keys

Dictionary keys used in the dictionaries returned by the SecPKCS12Import function.

extern CFStringRef kSecImportItemLabel;
extern CFStringRef kSecImportItemKeyID;
extern CFStringRef kSecImportItemTrust;
extern CFStringRef kSecImportItemCertChain;
extern CFStringRef kSecImportItemIdentity;
Constants
kSecImportItemLabel

Item label.

The corresponding value is of type CFStringRef. The format of the string is implementation specific.

Available in OS X v10.6 and later.

Declared in SecImportExport.h.

kSecImportItemKeyID

Key ID.

The corresponding value is of type CFDataRef. This unique ID is often the SHA-1 digest of the public encryption key.

Available in OS X v10.6 and later.

Declared in SecImportExport.h.

kSecImportItemTrust

Trust management object.

The corresponding value is of type SecTrustRef. The trust reference returned by the SecPKCS12Import function has been evaluated against the basic X.509 policy and includes as complete a certificate chain as could be constructed from the certificates in the PKCS #12 blob, certificates on the keychain, and any other certificates available to the system. You can use the SecTrustEvaluate function if you want to know whether the certificate chain is complete and valid (according to the basic X.509 policy). There is no guarantee that the evaluation will succeed.

Available in OS X v10.6 and later.

Declared in SecImportExport.h.

kSecImportItemCertChain

Certificate list.

The corresponding value is of type CFArrayRef. The array consists of SecCertificateRef objects for all the certificates in the PKCS #12 blob. This list might differ from that in the trust management object if there is more than one identity in the blob or if the blob contains extra certificates (for example, an intermediate certificate that is not yet valid but might be needed to establish validity in the near future).

Available in OS X v10.6 and later.

Declared in SecImportExport.h.

kSecImportItemIdentity

Identity object.

The corresponding value is of type SecIdentityRef and represents one identity contained in the PKCS #12 blob.

Available in OS X v10.6 and later.

Declared in SecImportExport.h.

System Identity Domains

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

const CFStringRef kSecIdentityDomainDefault;
const CFStringRef kSecIdentityDomainKerberosKDC;
Constants
kSecIdentityDomainDefault

The system-wide default identity.

Available in OS X v10.5 and later.

Declared in SecIdentity.h.

kSecIdentityDomainKerberosKDC

Kerberos Key Distribution Center (KDC) identity.

Available in OS X v10.5 and later.

Declared in SecIdentity.h.

Discussion

These constants can be used with the SecIdentitySetSystemIdentity and SecIdentityCopySystemIdentity functions.

Key Credential Type Constants

The credential type to be returned by SecKeyGetCredentials.

typedef uint32 SecCredentialType;
   
enum
{
   kSecCredentialTypeDefault = 0,
   kSecCredentialTypeWithUI,
   kSecCredentialTypeNoUI
};
Constants
kSecCredentialTypeDefault

The default setting for determining whether to present UI is used.

The default setting can be changed with a call to SecKeychainSetUserInteractionAllowed.

Available in OS X v10.5 and later.

Declared in SecKey.h.

kSecCredentialTypeWithUI

Keychain operations on keys that have this credential are allowed to present UI if required.

Available in OS X v10.5 and later.

Declared in SecKey.h.

kSecCredentialTypeNoUI

Keychain operations on keys that have this credential are not allowed to present UI, and will fail if UI is required.

Available in OS X v10.5 and later.

Declared in SecKey.h.

Discussion

See the section “Servers and the Keychain” in the “OS X Keychain Services Tasks” chapter of Keychain Services Programming Guide for information on the use of UI with keychain tasks.

Trust Settings Domain Constants

The trust settings domains used by the trust settings API.

enum {     kSecTrustSettingsDomainUser = 0,
   kSecTrustSettingsDomainAdmin,
   kSecTrustSettingsDomainSystem }; typedef uint32 SecTrustSettingsDomain;
Constants
kSecTrustSettingsDomainUser

Per-user trust settings.

Available in OS X v10.5 and later.

Declared in SecTrustSettings.h.

kSecTrustSettingsDomainAdmin

Locally administered, system-wide trust settings.

Administrator privileges are required to make changes to this domain.

Available in OS X v10.5 and later.

Declared in SecTrustSettings.h.

kSecTrustSettingsDomainSystem

System trust settings.

These trust settings are immutable and comprise the set of trusted root certificates supplied in OS X. These settings are read-only, even by root.

Available in OS X v10.5 and later.

Declared in SecTrustSettings.h.

Trust Settings Key Use Constants

Allowed uses for the encryption key in a certificate.

enum {
   kSecTrustSettingsKeyUseSignature        = 0x00000001,
   kSecTrustSettingsKeyUseEnDecryptData    = 0x00000002,
   kSecTrustSettingsKeyUseEnDecryptKey     = 0x00000004,
   kSecTrustSettingsKeyUseSignCert         = 0x00000008,
   kSecTrustSettingsKeyUseSignRevocation   = 0x00000010,
   kSecTrustSettingsKeyUseKeyExchange      = 0x00000020,
   kSecTrustSettingsKeyUseAny              = 0xffffffff
};
typedef uint32 SecTrustSettingsKeyUsage;
Constants
kSecTrustSettingsKeyUseSignature

The key can be used to sign data or verify a signature.

Available in OS X v10.5 and later.

Declared in SecTrustSettings.h.

kSecTrustSettingsKeyUseEnDecryptData

The key can be used to encrypt or decrypt data.

Available in OS X v10.5 and later.

Declared in SecTrustSettings.h.

kSecTrustSettingsKeyUseEnDecryptKey

The key can be used to encrypt or decrypt (wrap or unwrap) a key.

Private keys must be wrapped before they can be exported from a keychain.

Available in OS X v10.5 and later.

Declared in SecTrustSettings.h.

kSecTrustSettingsKeyUseSignCert

The key can be used to sign a certificate or verify a signature.

Available in OS X v10.5 and later.

Declared in SecTrustSettings.h.

kSecTrustSettingsKeyUseSignRevocation

The key can be used to sign an OCSP (online certificate status protocol) message or CRL (certificate verification list), or to verify a signature.

OCSP messages and CRLs are used to revoke certificates.

Available in OS X v10.5 and later.

Declared in SecTrustSettings.h.

kSecTrustSettingsKeyUseKeyExchange

The key is a private key that has been shared using a key exchange protocol, such as Diffie-Hellman key exchange.

Available in OS X v10.5 and later.

Declared in SecTrustSettings.h.

kSecTrustSettingsKeyUseAny

The key can be used for any purpose.

This is the default key-use setting if no other key use is specified.

Available in OS X v10.5 and later.

Declared in SecTrustSettings.h.

Trust Settings Usage Constraints Dictionary Keys

The keys in one usage constraints dictionary.

#define kSecTrustSettingsPolicy          CFSTR("kSecTrustSettingsPolicy")
#define kSecTrustSettingsApplication     CFSTR("kSecTrustSettingsApplication")
#define kSecTrustSettingsPolicyString    CFSTR("kSecTrustSettingsPolicyString")
#define kSecTrustSettingsKeyUsage        CFSTR("kSecTrustSettingsKeyUsage")
#define kSecTrustSettingsAllowedError    CFSTR("kSecTrustSettingsAllowedError")
#define kSecTrustSettingsResult          CFSTR("kSecTrustSettingsResult")
Constants
kSecTrustSettingsPolicy

A policy object (SecPolicyRef) specifying the certificate verification policy.

Available in OS X v10.5 and later.

Declared in SecTrustSettings.h.

kSecTrustSettingsApplication

A trusted application reference (SecTrustedApplicationRef) for the application checking the certificate’s trust settings.

Available in OS X v10.5 and later.

Declared in SecTrustSettings.h.

kSecTrustSettingsPolicyString

ACFString containing policy-specific data.

For the SMIME policy, this string contains an email address. For the SSL policy, it contains a host name.

Available in OS X v10.5 and later.

Declared in SecTrustSettings.h.

kSecTrustSettingsKeyUsage

ACFNumber containing an SInt32 value specifying the operations for which the encryption key in this certificate can be used.

Available in OS X v10.5 and later.

Declared in SecTrustSettings.h.

kSecTrustSettingsAllowedError

A CFNumber containing an SInt32 value indicating a CSSM_RETURN result code which, if encountered during certificate verification, is ignored for that certificate.

Available in OS X v10.5 and later.

Declared in SecTrustSettings.h.

kSecTrustSettingsResult

A CFNumber containing an SInt32 value indicating the effective trust setting for this usage constraints dictionary.

Available in OS X v10.5 and later.

Declared in SecTrustSettings.h.

Trust Settings Result Constants

Effective trust settings for usage constraints dictionaries used by the SecTrustSettingsCopyTrustSettings and SecTrustSettingsSetTrustSettings functions.

enum {
   kSecTrustSettingsResultInvalid = 0,
   kSecTrustSettingsResultTrustRoot,
   kSecTrustSettingsResultTrustAsRoot,
   kSecTrustSettingsResultDeny,
   kSecTrustSettingsResultUnspecified
};
typedef uint32 SecTrustSettingsResult;
Constants
kSecTrustSettingsResultInvalid

Never valid in a trust settings array or in an API call.

Available in OS X v10.5 and later.

Declared in SecTrustSettings.h.

kSecTrustSettingsResultTrustRoot

This root certificate is explicitly trusted.

If the certificate is not a root (self-signed) certificate, the usage constraints dictionary is invalid.

Available in OS X v10.5 and later.

Declared in SecTrustSettings.h.

kSecTrustSettingsResultTrustAsRoot

This non-root certificate is explicitly trusted as if it were a trusted root.

Available in OS X v10.5 and later.

Declared in SecTrustSettings.h.

kSecTrustSettingsResultDeny

This certificate is explicitly distrusted.

Available in OS X v10.5 and later.

Declared in SecTrustSettings.h.

kSecTrustSettingsResultUnspecified

This certificate is neither trusted nor distrusted. This value can be used to specify an "allowed error" without assigning trust to a specific certificate.

This value can be used to specify an allowed error without assigning trust to the certificate.

Available in OS X v10.5 and later.

Declared in SecTrustSettings.h.

Default Root Certificate Trust Settings

A value indicating the default root certificate trust settings when used for a SecCertificateRef object in a trust settings API function.

#define kSecTrustSettingsDefaultRootCertSetting        ((SecCertificateRef)-1)
Constants
kSecTrustSettingsDefaultRootCertSetting

Default trust settings for root certificates.

Available in OS X v10.5 and later.

Declared in SecTrustSettings.h.

Discussion

Use this value with the SecTrustSettingsSetTrustSettings function to set the default trust settings for root certificates. When evaluating trust settings for a root certificate in a given domain, if no matching explicit trust settings exist for that certificate, then the default value for the effective trust setting is returned (assuming that a default has been set and that the result is not kSecTrustSettingsResultUnspecified).

SecCertificateCopyValues Property Keys

Keys in dictionary entries returned by SecCertificateCopyValues.

extern CFStringRef kSecPropertyKeyType;
extern CFStringRef kSecPropertyKeyLabel;
extern CFStringRef kSecPropertyKeyLocalizedLabel;
extern CFStringRef kSecPropertyKeyValue;
Constants
kSecPropertyKeyType

Describes the type in the describes the kSecPropertyKeyValue entry. Possible values are described in “Property Type Keys.”

Available in OS X v10.7 and later.

Declared in SecCertificate.h.

kSecPropertyKeyLabel

A label for the entry. This label may contain a descriptive (localized) string or an OID string.

Available in OS X v10.7 and later.

Declared in SecCertificate.h.

kSecPropertyKeyLocalizedLabel

A localized label of the entry.

Available in OS X v10.7 and later.

Declared in SecCertificate.h.

kSecPropertyKeyValue

The value for this entry. The value entry may be any Core Foundation type, but it is usually a CFStringRef, CFArrayRef or a CFDictionaryRef.

Available in OS X v10.7 and later.

Declared in SecCertificate.h.

Property Type Keys

Type values that can appear in the kSecPropertyKeyType key in dictionary entries returned by SecCertificateCopyValues.

extern CFStringRef kSecPropertyTypeWarning;
extern CFStringRef kSecPropertyTypeSuccess;
extern CFStringRef kSecPropertyTypeSection;
extern CFStringRef kSecPropertyTypeData;
extern CFStringRef kSecPropertyTypeString;
extern CFStringRef kSecPropertyTypeURL;
extern CFStringRef kSecPropertyTypeDate;
extern CFTypeRef kSecPropertyTypeTitle;
extern CFTypeRef kSecPropertyTypeError;
Constants
kSecPropertyTypeWarning

Specifies a key whose value is a CFStringRef object describing a trust evaluation warning.

Available in OS X v10.7 and later.

Declared in SecCertificate.h.

kSecPropertyTypeSuccess

Specifies a key whose value is a CFStringRef object describing a trust evaluation success.

Available in OS X v10.7 and later.

Declared in SecCertificate.h.

kSecPropertyTypeSection

Specifies a key whose value is a CFStringRef object describing the name of a field in the certificate (CFSTR("Subject Name"), for example).

Available in OS X v10.7 and later.

Declared in SecCertificate.h.

kSecPropertyTypeData

Specifies a key whose value is a CFDataRef object.

Available in OS X v10.7 and later.

Declared in SecCertificate.h.

kSecPropertyTypeString

Specifies a key whose value is a CFStringRef object containing a string.

Available in OS X v10.7 and later.

Declared in SecCertificate.h.

kSecPropertyTypeURL

Specifies a key whose value is a CFStringRef object containing a URL.

Available in OS X v10.7 and later.

Declared in SecCertificate.h.

kSecPropertyTypeDate

Specifies a key whose value is a CFStringRef object containing a date (or a string listing the bytes of an invalid date).

Available in OS X v10.7 and later.

Declared in SecCertificate.h.

kSecPropertyTypeTitle

Specifies a key whose value is a CFStringRef object containing the title (display name) of the certificate.

Available in OS X v10.7 and later.

Declared in SecTrust.h.

kSecPropertyTypeError

Specifies a key whose value is a CFStringRef object containing the reason for a trust evaluation failure.

Available in OS X v10.7 and later.

Declared in SecTrust.h.

Certificate Usage Constants

Constants that represent allowed certificate use.

extern const CFStringRef kSecCertificateUsageSigning;
extern const CFStringRef kSecCertificateUsageSigningAndEncrypting;
extern const CFStringRef kSecCertificateUsageDeriveAndSign;
Constants
kSecCertificateUsageSigning

The certificate can be used for signing.

Available in OS X v10.7 and later.

Declared in SecCertificate.h.

kSecCertificateUsageSigningAndEncrypting

The certificate can be used for signing and encrypting.

Available in OS X v10.7 and later.

Declared in SecCertificate.h.

kSecCertificateUsageDeriveAndSign

The certificate can be used for signing and for deriving another key.

Available in OS X v10.7 and later.

Declared in SecCertificate.h.

Security Policy Keys

Policy keys used by SecPolicyCopyProperties and SecPolicySetProperties.

extern CFTypeRef kSecPolicyOid
extern CFTypeRef kSecPolicyName
extern CFTypeRef kSecPolicyClient
extern CFTypeRef kSecPolicyKU_DigitalSignature;
extern CFTypeRef kSecPolicyKU_NonRepudiation;
extern CFTypeRef kSecPolicyKU_KeyEncipherment;
extern CFTypeRef kSecPolicyKU_DataEncipherment;
extern CFTypeRef kSecPolicyKU_KeyAgreement;
extern CFTypeRef kSecPolicyKU_KeyCertSign;
extern CFTypeRef kSecPolicyKU_CRLSign;
extern CFTypeRef kSecPolicyKU_EncipherOnly;
extern CFTypeRef kSecPolicyKU_DecipherOnly;
Constants
kSecPolicyOid

The object identifier that defines the policy type (CFStringRef). All policies have a value for this key.

Available in OS X v10.7 and later.

Declared in SecPolicy.h.

kSecPolicyName

A name (CFStringRef) that the certificate must match to satisfy this policy. For SSL/TLS, this specifies the server name which must match the common name of the certificate. For S/MIME, this specifies the RFC 822 email address.

Available in OS X v10.7 and later.

Declared in SecPolicy.h.

kSecPolicyClient

If true, indicates this policy should be evaluated against the client certificate. If false, the policy is evaluated against the certificate for the server. Default is false.

Available in OS X v10.7 and later.

Declared in SecPolicy.h.

kSecPolicyKU_DigitalSignature

If true, the certificate’s key usage must allow it to be used for signing.

Available in OS X v10.7 and later.

Declared in SecPolicy.h.

kSecPolicyKU_NonRepudiation

If true, the certificate’s key usage must allow it to be used for non-repudiation.

Available in OS X v10.7 and later.

Declared in SecPolicy.h.

kSecPolicyKU_KeyEncipherment

If true, the certificate’s key usage must allow it to be used for key encryption.

Available in OS X v10.7 and later.

Declared in SecPolicy.h.

kSecPolicyKU_DataEncipherment

If true, the certificate’s key usage must allow it to be used for data encryption.

Available in OS X v10.7 and later.

Declared in SecPolicy.h.

kSecPolicyKU_KeyAgreement

If true, the certificate’s key usage must allow it to be used for key agreement.

Available in OS X v10.7 and later.

Declared in SecPolicy.h.

kSecPolicyKU_KeyCertSign

If true, the certificate’s key usage must allow it to be used for signing certificates.

Available in OS X v10.7 and later.

Declared in SecPolicy.h.

kSecPolicyKU_CRLSign

If true, the certificate’s key usage must allow it to be used for signing certificate revocation lists (CRLs).

Available in OS X v10.7 and later.

Declared in SecPolicy.h.

kSecPolicyKU_EncipherOnly

If true, the certificate’s key usage must allow it to be used only for encryption.

Available in OS X v10.7 and later.

Declared in SecPolicy.h.

kSecPolicyKU_DecipherOnly

If true, the certificate’s key usage must allow it to be used only for decryption.

Available in OS X v10.7 and later.

Declared in SecPolicy.h.

Security Trust Option Flags

Trust option flags used for SecTrustSetOptions.

enum {
   kSecTrustOptionAllowExpired       = 0x00000001,
   kSecTrustOptionLeafIsCA           = 0x00000002,
   kSecTrustOptionFetchIssuerFromNet = 0x00000004,
   kSecTrustOptionAllowExpiredRoot   = 0x00000008,
   kSecTrustOptionRequireRevPerCert  = 0x00000010,
   kSecTrustOptionImplicitAnchors    = 0x00000040
};
typedef uint32_t SecTrustOptionFlags;
Constants
kSecTrustOptionAllowExpired

Allow expired certificates (except for the root certificate).

Available in OS X v10.7 and later.

Declared in SecTrust.h.

kSecTrustOptionLeafIsCA

Allow CA certificates as leaf certificates.

Available in OS X v10.7 and later.

Declared in SecTrust.h.

kSecTrustOptionFetchIssuerFromNet

Allow network downloads of CA certificates.

Available in OS X v10.7 and later.

Declared in SecTrust.h.

kSecTrustOptionAllowExpiredRoot

Allow expired root certificates.

Available in OS X v10.7 and later.

Declared in SecTrust.h.

kSecTrustOptionRequireRevPerCert

Require a positive revocation check for each certificate.

Available in OS X v10.7 and later.

Declared in SecTrust.h.

kSecTrustOptionImplicitAnchors

Treat properly self-signed certificates as anchors implicitly.

Available in OS X v10.7 and later.

Declared in SecTrust.h.

Supported Key sizes

Supported sizes for keys of various common types.

enum
{
   kSecDefaultKeySize  = 0,
   
   // Symmetric Keysizes - default is currently kSecAES128 for AES.
   kSec3DES192         = 192,
   kSecAES128          = 128,
   kSecAES192          = 192,
   kSecAES256          = 256,
   
   // Supported ECC Keys for Suite-B from RFC 4492 section 5.1.1.
   // default is currently kSecp256r1
   kSecp192r1          = 192,
   kSecp256r1          = 256,
   kSecp384r1          = 384,
   kSecp521r1          = 521,  // Yes,
   521
   
   // Boundaries for RSA KeySizes - default is currently 2048
   // RSA keysizes must be multiples of 8
   kSecRSAMin          = 1024,
   kSecRSAMax          = 4096
};
typedef uint32_t SecKeySizes;
Constants
kSecDefaultKeySize

The default key size for the specified type.

Available in OS X v10.7 and later.

Declared in SecKey.h.

kSec3DES192

192-bit DES.

Available in OS X v10.7 and later.

Declared in SecKey.h.

kSecAES128

128-bit AES.

Available in OS X v10.7 and later.

Declared in SecKey.h.

kSecAES192

192-bit AES.

Available in OS X v10.7 and later.

Declared in SecKey.h.

kSecAES256

256-bit AES.

Available in OS X v10.7 and later.

Declared in SecKey.h.

kSecp192r1

192-bit ECC Keys for Suite-B from RFC 4492 section 5.1.1.

Available in OS X v10.7 and later.

Declared in SecKey.h.

kSecp256r1

256-bit ECC Keys for Suite-B from RFC 4492 section 5.1.1.

Available in OS X v10.7 and later.

Declared in SecKey.h.

kSecp384r1

384-bit ECC Keys for Suite-B from RFC 4492 section 5.1.1.

Available in OS X v10.7 and later.

Declared in SecKey.h.

kSecp521r1

521-bit ECC Keys for Suite-B from RFC 4492 section 5.1.1.

Available in OS X v10.7 and later.

Declared in SecKey.h.

kSecRSAMin

1024 bits is the minimum size for an RSA key.

Available in OS X v10.7 and later.

Declared in SecKey.h.

kSecRSAMax

4096 bits is the maximum size for an RSA key.

Available in OS X v10.7 and later.

Declared in SecKey.h.

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.

   
extern CFTypeRef kSecPolicyAppleX509Basic;
extern CFTypeRef kSecPolicyAppleSSL;
extern CFTypeRef kSecPolicyAppleSMIME;
extern CFTypeRef kSecPolicyAppleEAP;
extern CFTypeRef kSecPolicyAppleIPsec;
extern CFTypeRef kSecPolicyAppleiChat
extern CFTypeRef kSecPolicyApplePKINITClient;
extern CFTypeRef kSecPolicyApplePKINITServer;
extern CFTypeRef kSecPolicyAppleCodeSigning;
extern CFTypeRef kSecPolicyMacAppStoreReceipt;
extern CFTypeRef kSecPolicyAppleIDValidation;
extern CFTypeRef kSecPolicyAppleTimeStamping;
Constants
kSecPolicyAppleX509Basic

Basic X509-style certificate evaluation.

Available in OS X v10.7 and later.

Declared in SecPolicy.h.

kSecPolicyAppleSSL

Basic X509 plus host name verification per RFC 2818.

Available in OS X v10.7 and later.

Declared in SecPolicy.h.

kSecPolicyAppleSMIME

Basic X509 plus email address verification and KeyUsage enforcement per RFC 2632.

Available in OS X v10.7 and later.

Declared in SecPolicy.h.

kSecPolicyAppleEAP

Extensible Authentication Protocol. Functionally identical to SSL policy. A separate OID is provided to facilitate per-policy, per-certificate trust settings using the SecTrust mechanism.

Available in OS X v10.7 and later.

Declared in SecPolicy.h.

kSecPolicyAppleIPsec

Policy for use in IPsec communication. Functionally identical to SSL policy. A separate OID is provided to facilitate per-policy, per-certificate trust settings using the SecTrust mechanism.

Available in OS X v10.7 and later.

Declared in SecPolicy.h.

kSecPolicyAppleiChat

Policy for use in iChat.

Available in OS X v10.7 and later.

Deprecated in OS X v10.9.

Declared in SecPolicy.h.

kSecPolicyApplePKINITClient

Kerberos Pkinit client certificate validation.

Available in OS X v10.7 and later.

Declared in SecPolicy.h.

kSecPolicyApplePKINITServer

Kerberos Pkinit server certificate validation.

Available in OS X v10.7 and later.

Declared in SecPolicy.h.

kSecPolicyAppleCodeSigning

Policy for use in evaluating Apple code signing certificates. To learn more about code signing certificates, read App Distribution Guide.

Available in OS X v10.7 and later.

Declared in SecPolicy.h.

kSecPolicyMacAppStoreReceipt

Policy for use in evaluating Mac App Store receipts.

Available in OS X v10.7 and later.

Declared in SecPolicy.h.

kSecPolicyAppleIDValidation

Policy for use in evaluating Apple ID certificates. To learn more about Apple ID certificates, read App Distribution Guide.

Available in OS X v10.7 and later.

Declared in SecPolicy.h.

kSecPolicyAppleTimeStamping

Policy that causes evaluation of the validity of the time stamp on a signature. This can be used to allow verification that a certificate was valid at the time that something was signed with that certificate even if the certificate is no longer valid.

Available in OS X v10.8 and later.

Declared in SecPolicy.h.

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.

Result CodeValueDescription
errSecSuccess0

No error.

Available in OS X v10.6 and later.

errSecUnimplemented-4

The function or operation is not implemented.

Available in OS X v10.6 and later.

errSecParam-50

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

Available in OS X v10.6 and later.

errSecAllocate-108

Failed to allocate memory.

Available in OS X v10.6 and later.

errSecNotAvailable –25291

No keychain is available.

Available in OS X v10.2 and later.

errSecReadOnly –25292

A read-only error occurred.

Available in OS X v10.2 and later.

errSecAuthFailed –25293

Authorization or authentication failed.

Available in OS X v10.2 and later.

errSecNoSuchKeychain –25294

The keychain does not exist.

Available in OS X v10.2 and later.

errSecInvalidKeychain –25295

The keychain is not valid.

Available in OS X v10.2 and later.

errSecDuplicateKeychain –25296

A keychain with the same name already exists.

Available in OS X v10.2 and later.

errSecDuplicateItem –25299

An item with the same primary key attributes already exists.

Available in OS X v10.2 and later.

errSecItemNotFound –25300

The item cannot be found.

Available in OS X v10.2 and later.

errSecBufferTooSmall –25301

The buffer is too small.

Available in OS X v10.2 and later.

errSecDataTooLarge –25302

The data is too large for the particular data type.

Available in OS X v10.2 and later.

errSecNoSuchAttr –25303

The attribute does not exist.

Available in OS X v10.2 and later.

errSecInvalidItemRef –25304

The item object is invalid.

Available in OS X v10.2 and later.

errSecInvalidSearchRef –25305

The search object is invalid.

Available in OS X v10.2 and later.

errSecNoSuchClass –25306

The specified item does not appear to be a valid keychain item.

Available in OS X v10.2 and later.

errSecNoDefaultKeychain –25307

A default keychain does not exist.

Available in OS X v10.2 and later.

errSecInteractionNotAllowed –25308

Interaction with the user is required in order to grant access or process a request; however, user interaction with the Security Server has been disabled by the program.

Available in OS X v10.2 and later.

errSecReadOnlyAttr –25309

The attribute is read-only.

Available in OS X v10.2 and later.

errSecWrongSecVersion –25310

The version is incorrect.

Available in OS X v10.2 and later.

errSecKeySizeNotAllowed –25311

The key size is not allowed.

Available in OS X v10.2 and later.

errSecNoStorageModule –25312

No storage module is available.

Available in OS X v10.2 and later.

errSecNoCertificateModule –25313

No certificate module is available.

Available in OS X v10.2 and later.

errSecNoPolicyModule –25314

No policy module is available.

Available in OS X v10.2 and later.

errSecInteractionRequired –25315

Interaction with the user is required in order to grant access or process a request; however, user interaction with the Security Server is impossible because the program is operating in a session incapable of graphics (such as a root session or ssh session).

Available in OS X v10.2 and later.

errSecDataNotAvailable –25316

The data is not available.

Available in OS X v10.2 and later.

errSecDataNotModifiable –25317

The data is not modifiable.

Available in OS X v10.2 and later.

errSecCreateChainFailed –25318

One or more certificates required in order to validate this certificate cannot be found.

Available in OS X v10.2 and later.

errSecInvalidPrefsDomain –25319

The preference domain specified is invalid. This error can occur in OS X v10.3 and later.

Available in OS X v10.3 and later.

errSecACLNotSimple –25240

The access control list is not in standard simple form.

Available in OS X v10.2 and later.

errSecPolicyNotFound –25241

The policy specified cannot be found.

Available in OS X v10.2 and later.

errSecInvalidTrustSetting –25242

The trust setting is invalid.

Available in OS X v10.2 and later.

errSecNoAccessForItem –25243

The specified item has no access control.

Available in OS X v10.2 and later.

errSecInvalidOwnerEdit –25244

An invalid attempt has been made to change the owner of an item.

Available in OS X v10.2 and later.

errSecTrustNotAvailable –25245

No trust results are available.

Available in OS X v10.3 and later.

errSecDecode-26275

Unable to decode the provided data.

Available in OS X v10.6 and later.