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:

Determine identity by matching a certificate with a private key
Create and request certificate objects
Import certificates, keys, and identities
Create public-private key pairs
Represent trust policies

Concurrency Considerations

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

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.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

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

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

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.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

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.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

Availability

Available in OS X v10.5 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.

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

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

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.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

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.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

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

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

Discussion

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

Availability

Available in OS X v10.2 and later.

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.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

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.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

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

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

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.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

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.
kSecAttrPRF - the algorithm to use for the pseudorandom-function.
If zero, this defaults to kSecAttrPRFHmacAlgSHA1. For a list of possible values, see “kSecAttrPRF Value Constants” in Keychain Services Reference.
kSecAttrRounds—the number of times to call the pseudorandom function. If zero, the count is computed so that computation will take 1/10 of a second (on average).
kSecAttrKeySizeInBits—a CFNumberRef value containing the requested key size in bits. The key size must be valid for the key type.

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.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

Discussion

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

A kSecAttrKeyType key with a value of any key type defined in SecItem.h (see Keychain Services Reference), for example, kSecAttrKeyTypeRSA.
A kSecAttrKeySizeInBits key with a value specifying the requested key size in bits. This can be specified as either a CFNumberRef or CFStringRef value. For example, RSA keys may have key size values of 512, 768, 1024, or 2048.

In addition, you can specify a number of attributes for the public and private keys individually. You can do so either by adding key-value pairs to the dictionary directly, or by adding either or both of the keys kSecPrivateKeyAttrs and kSecPublicKeyAttrs. Each of these keys takes as a value a dictionary of key-value pairs that you can use to set these attributes. The possible attributes are as follows; for details on each attribute, see Keychain Services Reference:

kSecAttrLabel—Default NULL.
kSecAttrIsPermanent—If this key is present and has a Boolean value of true, the key or key pair is added to the default keychain.
kSecAttrApplicationTag—Default NULL.
kSecAttrEffectiveKeySize—Default (NULL) sets the effective key size to the same as the total key size (kSecAttrKeySizeInBits).
kSecAttrCanEncrypt—Default false for private keys, true for public keys.
kSecAttrCanDecrypt—Default true for private keys, false for public keys.
kSecAttrCanDerive—Default true.
kSecAttrCanSign—Default true for private keys, false for public keys.
kSecAttrCanVerify—Default false for private keys, true for public keys.
kSecAttrCanUnwrap—Default true for private keys, false for public keys.

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:

kSecAttrLabel defaults to NULL.
kSecAttrIsPermanent if this key is present and has a value of kCFBooleanTrue, the key or key pair will be added to the default keychain.
kSecAttrApplicationTag defaults to NULL.
kSecAttrEffectiveKeySize defaults to NULL, which means the effective key size is the same as the key size (kSecAttrKeySizeInBits).
kSecAttrCanEncrypt defaults to kCFBooleanFalse for private keys, kCFBooleanTrue for public keys.
kSecAttrCanDecrypt defaults to kCFBooleanTrue for private keys, kCFBooleanFalse for public keys.
kSecAttrCanDerive defaults to kCFBooleanTrue.
kSecAttrCanSign defaults to kCFBooleanTrue for private keys, kCFBooleanFalse for public keys.
kSecAttrCanVerify defaults to kCFBooleanFalse for private keys, kCFBooleanTrue for public keys.
kSecAttrCanWrap defaults to kCFBooleanFalse for private keys, kCFBooleanTrue for public keys.
kSecAttrCanUnwrap defaults to kCFBooleanTrue for private keys, kCFBooleanFalse for public 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:

kSecAttrLabel defaults to NULL.
kSecAttrIsPermanent if this key is present and has a value of kCFBooleanTrue, the key or key pair will be added to the default keychain.
kSecAttrApplicationTag defaults to NULL.
kSecAttrEffectiveKeySize defaults to NULL, which means the effective key size is the same as the key size (kSecAttrKeySizeInBits).
kSecAttrCanEncrypt defaults to kCFBooleanFalse for private keys, kCFBooleanTrue for public keys.
kSecAttrCanDecrypt defaults to kCFBooleanTrue for private keys, kCFBooleanFalse for public keys.
kSecAttrCanDerive defaults to kCFBooleanTrue.
kSecAttrCanSign defaults to kCFBooleanTrue for private keys, kCFBooleanFalse for public keys.
kSecAttrCanVerify defaults to kCFBooleanFalse for private keys, kCFBooleanTrue for public keys.
kSecAttrCanWrap defaults to kCFBooleanFalse for private keys, kCFBooleanTrue for public keys.
kSecAttrCanUnwrap defaults to kCFBooleanTrue for private keys, kCFBooleanFalse for public 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.

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.2 and later.

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.

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.

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

SecPolicyCreateWithOID

Returns a policy object for the specified policy type object identifier.

SecPolicyRef SecPolicyCreateWithOID (
   CFTypeRef policyOID
);

Parameters

policyOID: The object identifier (OID) of the policy type for this policy.

Availability

Available in OS X v10.7 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.2 and later.

Declared In

SecPolicy.h

SecPolicySetProperties

Sets properties for a policy.

OSStatus SecPolicySetProperties (
   SecPolicyRef policyRef,
   CFDictionaryRef properties
);

Parameters

policyRef: The policy to alter
properties: A CFDictionaryRef object containing the new set of properties. For a list of valid property keys, see “Security Policy Keys.”
Note: The property kSecPolicyOid is read-only and thus cannot be changed by this function.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

Availability

Available in OS X v10.7 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.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

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

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

Discussion

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

Availability

Available in OS X v10.5 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.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

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

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.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

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.2 and later.

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.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

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.2 and later.

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.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

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.2 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:

the CFDateGetAbsoluteTime function for the date passed in to the SecTrustSetVerifyDate function, if that was called, or
the last value returned by the SecTrustGetVerifyTime function, if it was called before, or
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.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

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

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

Discussion

Availability

Available in OS X v10.6 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.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

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.

Availability

Available in OS X v10.2 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”.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

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.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

Discussion

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

Availability

Available in OS X v10.5 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`	A`CFString` containing policy-specific data. For the SMIME policy, this string contains an email address. For the SSL policy, it contains a host name.
`kSecTrustSettingsKeyUsage`	A`CFNumber` 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.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

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.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

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

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.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.”

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.

Availability

Available in OS X v10.2 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.

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.2 and later.

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 “Keychain Services Tasks for OS X” 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.

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 Tools Workflow Guide for Mac or Tools Workflow Guide for iOS.

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 Tools Workflow Guide for Mac.

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 Code	Value	Description
`errSecSuccess`	0	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.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

Certificate, Key, and Trust Services Reference

Overview

Concurrency Considerations

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

Parameters

Return Value

Discussion

Special Considerations

Availability

Declared In

SecCertificateCopyCommonName

Parameters

Return Value

Availability

Declared In

SecCertificateCopyData

Parameters

Return Value

Availability

See Also

Declared In

SecCertificateCopyEmailAddresses

Parameters

Return Value

Discussion

Availability

Declared In

SecCertificateCopyLongDescription

Parameters

Return Value

Discussion

Availability

Declared In

SecCertificateCopyNormalizedIssuerContent

Parameters

Return Value

Discussion

Availability

Declared In

SecCertificateCopyNormalizedSubjectContent

Parameters

Return Value

Discussion

Availability

Declared In

SecCertificateCopyPreferred

Parameters

Return Value

Discussion

Availability

See Also

Declared In

SecCertificateCopyPublicKey

Parameters

Return Value

Availability

Declared In

SecCertificateCopySerialNumber

Parameters

Return Value

Availability

Declared In

SecCertificateCopyShortDescription

Parameters

Return Value

Discussion

Availability

Declared In

SecCertificateCopySubjectSummary

Parameters