Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

Certificate, Key, and Trust Services Reference

Framework
Security/Security.h
Declared in
SecBase.h
SecCertificate.h
SecIdentity.h
SecIdentitySearch.h
SecKey.h
SecKeychainItem.h
SecPolicy.h
SecPolicySearch.h
SecTrust.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:

Certificate, Key, and Trust Services can be used in Carbon, Cocoa, and UNIX applications running in Mac OS X.

Functions by Task

Getting Type Identifiers

Managing Certificates

Managing Identities

Managing Keys

Managing Policies

Managing Trust

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.

Availability
Declared In
SecCertificate.h

SecCertificateCreateFromData

Creates a certificate object based on the specified data, type, and encoding.

OSStatus SecCertificateCreateFromData (
   const CSSM_DATA *data,
   CSSM_CERT_TYPE type,
   CSSM_CERT_ENCODING encoding,
   SecCertificateRef *certificate
);

Parameters
data

A pointer to the certificate data. The data must be an X509 certificate in binary format.

type

The certificate type as defined in cssmtype.h. Permissible values are CSSM_CERT_X_509v1, CSSM_CERT_X_509v2, and CSSM_CERT_X_509v3. If you are unsure of the certificate type, use CSSM_CERT_X_509v3.

encoding

The certificate encoding as defined in cssmtype.h. Permissible values are CSSM_CERT_ENCODING_BER and CSSM_CERT_ENCODING_DER. If you are unsure of the encoding, use CSSM_CERT_ENCODING_BER.

certificate

On return, points to the newly created certificate 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 certificate object returned by this function is used as input to several other functions in the API.

Availability
Declared In
SecCertificate.h

SecCertificateGetCLHandle

Retrieves the certificate library handle from a certificate object.

OSStatus SecCertificateGetCLHandle (
   SecCertificateRef certificate,
   CSSM_CL_HANDLE *clHandle
);

Parameters
certificate

The certificate object from which to obtain the certificate library handle.

clHandle

On return, points to the certificate library handle of the specified certificate. This handle remains valid until the certificate object is released.

Return Value

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

Discussion

The certificate library handle is the CSSM identifier of the certificate library module that is managing the certificate. The certificate library handle is used as an input to a number of CSSM functions.

Availability
Declared In
SecCertificate.h

SecCertificateGetData

Retrieves the data for a certificate.

OSStatus SecCertificateGetData (
   SecCertificateRef certificate,
   CSSM_DATA_PTR data
);

Parameters
certificate

A certificate object for the certificate from which to retrieve the data.

data

On return, points to the data for the certificate specified. You must allocate the space for a CSSM_DATA structure before calling this function. This data pointer is only guaranteed to remain valid as long as the certificate remains unchanged and valid.

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, obtained from an identity with the SecIdentityCopyCertificate function, or obtained over a network (see Secure Transport Reference).

Availability
Declared In
SecCertificate.h

SecCertificateGetIssuer

Unsupported.

OSStatus SecCertificateGetIssuer (
   SecCertificateRef certificate,
   CSSM_X509_NAME *issuer
);

Availability
Declared In
SecCertificate.h

SecCertificateGetItem

Unsupported.

OSStatus SecCertificateGetItem (
   SecCertificateRef certificate,
   SecKeychainItemRef *item
);

Availability
Declared In
SecCertificate.h

SecCertificateGetSubject

Unsupported.

OSStatus SecCertificateGetSubject (
   SecCertificateRef certificate,
   CSSM_X509_NAME *subject
);

Availability
Declared In
SecCertificate.h

SecCertificateGetType

Retrieves the type of a specified certificate.

OSStatus SecCertificateGetType (
   SecCertificateRef certificate,
   CSSM_CERT_TYPE *certificateType
);

Parameters
certificate

A certificate object for the certificate for which to obtain the type.

certificateType

On return, points to the type of the specified certificate. Certificate types are defined in cssmtype.h. You must allocate the space for a CSSM_CERT_TYPE structure before calling this function.

Return Value

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

Availability
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
Declared In
SecCertificate.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. To get an identity object for an identity in a keychain, use the SecIdentitySearchCopyNext function.

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

Availability
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. 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. To get an identity object for an identity in the keychain, use the SecIdentitySearchCopyNext function.

Availability
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
Declared In
SecIdentity.h

SecIdentitySearchCopyNext

Finds the next identity matching specified search criteria

OSStatus SecIdentitySearchCopyNext (
   SecIdentitySearchRef searchRef,
   SecIdentityRef *identity
);

Parameters
searchRef

An identity search object specifying the search criteria for this search. You create the identity search object by calling the SecIdentitySearchCreate function.

identity

On return, points to the identity object of the next matching identity (if any). Call the CFRelease function to release this object when finished with it.

Return Value

A result code. When there are no more identities that match the parameters specified to SecIdentitySearchCreate, errSecItemNotFound is returned. See “Certificate, Key, and Trust Services Result Codes.”

Availability
Declared In
SecIdentitySearch.h

SecIdentitySearchCreate

Creates a search object for finding identities.

OSStatus SecIdentitySearchCreate (
   CFTypeRef keychainOrArray,
   CSSM_KEYUSE keyUsage,
   SecIdentitySearchRef *searchRef
);

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

keyUsage

ACSSM key use value as defined in cssmtype.h. (Note that, because key recovery is not implemented, the SIGN_RECOVER and VERIFY_RECOVER constants are not supported.) Use this parameter to filter the search by specifying the key use for the identity. Pass in 0 if you want all identities returned by this search. Pass in CSSM_KEYUSE_ANY to limit the identities returned to those that can be used for every operation.

searchRef

On return, points to the identity search object. Call the CFRelease function to release this object when you are done with it.

Return Value

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

Discussion

You can OR CSSM_KEYUSE values together to set more than one value for key use. Use the returned search object in calls to the SecIdentitySearchCopyNext function to obtain identities that match the search criteria.

Availability
Declared In
SecIdentitySearch.h

SecIdentitySearchGetTypeID

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

CFTypeID SecIdentitySearchGetTypeID (
   void
);

Return Value

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

Discussion

This function returns a value that uniquely identifies the opaque type of a SecIdentitySearchRef 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
Declared In
SecIdentitySearch.h

SecKeyCreatePair

Creates an asymmetric key pair and stores it in a keychain.

OSStatus SecKeyCreatePair (
   SecKeychainRef keychainRef,
   CSSM_ALGORITHMS algorithm,
   uint32 keySizeInBits,
   CSSM_CC_HANDLE contextHandle,
   CSSM_KEYUSE publicKeyUsage,
   uint32 publicKeyAttr,
   CSSM_KEYUSE privateKeyUsage,
   uint32 privateKeyAttr,
   SecAccessRef initialAccess,
   SecKeyRef *publicKey,
   SecKeyRef *privateKey
);

Parameters
keychainRef

The keychain object for the keychain in which to store the private and public key items. Specify NULL for the default keychain.

algorithm

The algorithm to use to generate the key pair. Possible values are defined in cssmtype.h. Algorithms supported by the AppleCSP module are listed in Security Release Notes. This parameter is ignored if the contextHandle parameter is not 0.

keySizeInBits

A key size for the key pair. See Security Release Notes for permissible key sizes for each algorithm supported by the AppleCSP module.

contextHandle

An optional CSSM_CC_HANDLE or 0. If this argument is not 0, the algorithm and keySizeInBits parameters are ignored.

publicKeyUsage

A bit mask indicating all permitted uses for the new public key. The possible values for the CSSM_KEYUSE data type are defined in cssmtype.h.

publicKeyAttr

A bit mask defining attribute values for the new public key. The bit mask values are equivalent to those defined for CSSM_KEYATTR_FLAGS in cssmtype.h.

privateKeyUsage

A bit mask indicating all permitted uses for the new private key. The possible values for the CSSM_KEYUSE data type are defined in cssmtype.h.

privateKeyAttr

A bit mask defining attribute values for the new private key. The bit mask values are defined in CSSM_KEYATTR_FLAGS in cssmtype.h. Supported values are CSSM_KETATTR_EXTRACTABLE (the key can be taken out of the keychain) and CSSM_KEYATTR_SENSITIVE (an extractable key can be taken out of the keychain only in wrapped form—that is, encrypted). (Note that you must set both of these bits if you want the key to be extractable in wrapped form.) For any other value of this attribute, the key cannot be taken out of the keychain under any circumstances.

initialAccess

An access object that sets the initial access control list for each of the keys returned. See “Creating an Access Object” in Keychain Services Reference for functions that create an access object. For default access, specify NULL. The default is free access to the tool or application that calls this function, with attempted access to sensitive information by any other application causing a confirmation dialog to be displayed.

publicKey

On return, points to the keychain item object of the new public key. Use this object as input to the SecKeyGetCSSMKey function to obtain the CSSM_KEY.structure containing the 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. Use this object as input to the SecKeyGetCSSMKey function to obtain the CSSM_KEY.structure containing the 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

This function uses default values for any attributes required by specific key-generation algorithms. Algorithms supported by the AppleCSP module are listed in Security Release Notes. For details about algorithms and default values for key-generation parameters, download the CDSA security framework from the ADC website at http://developer.apple.com/darwin/projects/security/ and read the file Supported_CSP_Algorithms.doc in the Documentation folder.

If you need extra parameters to generate a key—as required by some algortihms—call SecKeychainGetCSPHandle to obtain a CSSM CSP handle and then call CSSM_CSP_CreateKeyGenContext, to create a context. With this context, use CSSM_UpdateContextAttributes to add additional parameters. Finally, call CSSM_DeleteContext to dispose of the context.

Availability
Declared In
SecKey.h

SecKeyGetCSSMKey

Retrieves a pointer to the CSSM_KEY structure containing the key stored in a keychain item.

OSStatus SecKeyGetCSSMKey (
   SecKeyRef key,
   const CSSM_KEY **cssmKey
);

Parameters
key

A keychain key item object.

cssmKey

A pointer to a CSSM_KEY structure for the specified key. You should not modify or free this data, because it is owned by the system.

Return Value

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

Discussion

The CSSM_KEY structure is used to represent keys in CSSM and is used as an input value to several CSSM functions. The CSSM_KEY structure is valid until the keychain item object is released.

Availability
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
Declared In
SecKey.h

SecPolicyGetOID

Retrieves a policy’s object identifier.

OSStatus SecPolicyGetOID (
   SecPolicyRef policyRef,
   CSSM_OID *oid
);

Parameters
policyRef

The policy object for which to obtain the object identifier. You can obtain a policy object with the SecPolicySearchCopyNext function.

oid

On return, points to the policy’s object identifier. This identifier is owned by the policy object and remains valid until that object is destroyed; do not release it separately.

Return Value

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

Discussion

The policy’s object identifier, in the form of a CSSM_OID structure, is used in the CSSM API together with the policy’s value. Use the SecPolicyGetValue function to obtain the value that corresponds to this object identifier.

Availability
Declared In
SecPolicy.h

SecPolicyGetTPHandle

Retrieves the trust policy handle for a policy object.

OSStatus SecPolicyGetTPHandle (
   SecPolicyRef policyRef,
   CSSM_TP_HANDLE *tpHandle
);

Parameters
policyRef

The policy object from which to obtain the trust policy handle.

tpHandle

On return, points to the policy object’s trust policy handle. The handle remains valid until the policy object is released.

Return Value

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

Discussion

The trust policy handle is the CSSM identifier of the trust policy module that is managing the certificate. The trust policy handle is uses as an input to a number of CSSM functions.

Availability
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
Declared In
SecPolicy.h

SecPolicyGetValue

Retrieves a policy’s value.

OSStatus SecPolicyGetValue (
   SecPolicyRef policyRef,
   CSSM_DATA *value
);

Parameters
policyRef

The policy object for which to retrieve the value.

value

On return, points to the policy’s value. This value is owned by the policy object and remains valid until that object is destroyed; do not release it separately.

Return Value

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

Discussion

A policy’s value is defined and interpreted by the policy. If you are using CSSM, you can specify object-identifier–policy-value pairs as input to the CSSM_TP_POLICYINFO function. Use the SecPolicyGetOID function to obtain the object identifier (OID) for a policy.

Depending on how the policy uses the value, the value can be specific to a transaction. Because some other process might be using this policy object, it is best not to assign a new value to the policy using the same policy object. Instead, obtain a new policy object before assigning a new value to the policy.

Availability
Declared In
SecPolicy.h

SecPolicySearchCopyNext

Retrieves a policy object for the next policy matching specified search criteria.

OSStatus SecPolicySearchCopyNext (
   SecPolicySearchRef searchRef,
   SecPolicyRef *policyRef
);

Parameters
searchRef

A policy search object specifying the search criteria for this search. You create the policy search object by calling the SecPolicySearchCreate function.

policyRef

On return, points to the policy object for the next policy (if any) matching the specified search criteria. Call the CFRelease function to release this object when you are finished with it.

Return Value

A result code. When there are no more policies that match the parameters specified to SecPolicySearchCreate, errSecPolicyNotFound is returned. See “Certificate, Key, and Trust Services Result Codes.”

Availability
Declared In
SecPolicySearch.h

SecPolicySearchCreate

Creates a search object for finding policies.

OSStatus SecPolicySearchCreate (
   CSSM_CERT_TYPE certType,
   const CSSM_OID *policyOID,
   const CSSM_DATA *value,
   SecPolicySearchRef *searchRef
);

Parameters
certType

The type of certificates a policy uses, as defined in cssmtype.h. Permissible values are CSSM_CERT_X_509v1, CSSM_CERT_X_509v2, and CSSM_CERT_X_509v3. If you are unsure of the certificate type, use CSSM_CERT_X_509v3.

policyOID

A pointer to a BER-encoded policy object identifier that uniquely specifies the policy. See “AppleX509TP Trust Policies” for a list of policies and object identifiers provided by the AppleX509TP module.

value

A pointer to an optional, policy-defined value. The contents of this value depend on the policy object identifier specified. (Note that this parameter refers to the value stored in MDS and is not related to the value parameter of the SecPolicyGetValue function.) Currently the function does not use this parameter; pass NULL for this pointer.

searchRef

On return, points to the newly created policy search 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

You use the search object created by this function in subsequent calls to the SecPolicySearchCopyNext function to obtain trust policy objects. Policies are stored in the Module Directory Services (MDS) database. MDS is described in detail in “Part 8: Module Directory Service (MDS)” of Common Security: CDSA and CSSM, version 2 (with corrigenda) from The Open Group (http://www.opengroup.org/security/cdsa.htm).

Availability
Declared In
SecPolicySearch.h

SecPolicySearchGetTypeID

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

CFTypeID SecPolicySearchGetTypeID (
   void
);

Return Value

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

Discussion

This function returns a value that uniquely identifies the opaque type of a SecPolicySearchRef 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
Declared In
SecPolicySearch.h

SecTrustCopyAnchorCertificates

Retrieves the anchor (root) certificates stored by Mac 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. If you want references to the anchor certificates in a form appropriate for calls to the CSSM API, use the SecTrustGetCSSMAnchorCertificates function instead.

Availability
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 specifyonly 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 to obtain policy objects.

trustRef

On return, points to the newly createdtrust 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
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.

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 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 evaluates trust according to the user-specified trust setting (see SecTrustSetUserTrust and SecTrustGetUserTrust). For an example of user-specified trust settings, use the Keychain Access utility and look at any certificate.

For each policy, SecTrustEvaluate starts with the leaf certificate and checks each certificate in the chain, in turn, for a valid user-specified trust setting. It uses the first such value it finds for the trust evaluation. For example, if the user-specified trust for the leaf certificate is not set, the first intermediate certificate is set to “Always Trust,” and one of the other intermediate certificates is set to “Never Trust,” SecTrustEvaluate trusts the certificate. Thus, you can use a user-specified trust setting for a certificate closer to the leaf to override a setting closer to the anchor.

If there is no user-specified trust setting for the entire certificate chain, the SecTrustEvaluate function returns kSecTrustResultUnspecified as the result type. In that case, you should call the SFCertificateTrustPanel class in the Security Interface Framework Reference to let the user specify a trust setting for the certificate. Alternately, you can use a default value. If you use a default value, you should provide a preference setting so that the user can change the default.

If SecTrustEvaluate returns kSecTrustResultRecoverableTrustFailure as the result type, you can call the SecTrustGetResult function for details of the problem. 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 SecTrustEvaluate returns kSecTrustResultFatalTrustFailure, on the other hand, changing parameter values and calling SecTrustEvaluate again is unlikely to be successful.

If not all the certificates needed to verify the leaf certificate are included in the trust management object, then SecTrustEvaluate searches for certificates in the keychain search list (see SecTrustSetKeychains) and in the system’s store of anchor certificates (see SecTrustSetAnchorCertificates).

By default, SecTrustEvaluate uses the current date and time when verifying a certificate. However, you can call the SecTrustSetVerifyDate function before calling SecTrustEvaluate to set an other date and time to use when verifying the certificate.

Before you call SecTrustEvaluate, you can optionally use the SecTrustSetParameters function to set one or more actions to modify the evaluation or to pass data required by an action.

The results of the trust evaluation are stored in the trust management object. Call the SecTrustGetResult 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.

Availability
Declared In
SecTrust.h

SecTrustGetCssmResult

Retrieves the CSSM trust result.

OSStatus SecTrustGetCssmResult (
   SecTrustRef trust,
   CSSM_TP_VERIFY_CONTEXT_RESULT_PTR *result
);

Parameters
trust

A trust management object that has previously been sent to the SecTrustEvaluate function for evaluation.

result

On return, points to the CSSM trust result pointer. You should not modify or free this data, as it is owned by the system.

Return Value

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

Discussion

After calling the SecTrustEvaluate function, you can call the SecTrustGetResult function or the SecTrustGetCssmResult function to get information about the certificates in the certificate chain and everything that might be wrong with each certificate. Whereas the SecTrustGetResult function returns the information in a form that you can interpret without extensive knowledge of CSSM, the SecTrustGetCssmResult function returns information in a form that can be passed directly to CSSM functions. See Common Security: CDSA and CSSM, version 2 (with corrigenda) from The Open Group (http://www.opengroup.org/security/cdsa.htm for more information about the CSSM_TP_VERIFY_CONTEXT_RESULT structure pointed to by the result parameter.

Availability
Declared In
SecTrust.h

SecTrustGetResult

Retrieves details on the outcome of a call to the function SecTrustEvaluate.

OSStatus SecTrustGetResult (
   SecTrustRef trustRef,
   SecTrustResultType *result,
   CFArrayRef *certChain,
   CSSM_TP_APPLE_EVIDENCE_INFO **statusChain
);

Parameters
trustRef

A trust management object that has previously been sent to the SecTrustEvaluate function for evaluation.

result

A pointer to the result type returned in the result parameter by the SecTrustEvaluate function.

certChain

On return, points to an array of certificates that constitute the certificate chain used to verify the input certificate. Call the CFRelease function to release this object when you are finished with it.

statusChain

On return, points to an array of CSSM_TP_APPLE_EVIDENCE_INFO structures, one for each certificate in the certificate chain. The first item in the array corresponds to the leaf certificate, and the last item corresponds to the anchor (assuming that verification of the chain did not fail before reaching the anchor certificate). Each structure describes the status of one certificate in the chain. This structure is defined in cssmapple.h. Do not attempt to free this pointer; it remains valid until the trust management object is released or until the next call to the function SecTrustEvaluate that uses this trust management object.

Return Value

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

Discussion

After calling the SecTrustEvaluate function, you can call the SecTrustGetCssmResult function or the SecTrustGetCssmResult function to get detailed information about the results of the evaluation. Whereas the SecTrustGetResult function returns the information in a form that you can interpret without extensive knowledge of CSSM, the SecTrustGetCssmResult function returns information in a form that can be passed directly to CSSM functions.

You can call the SFCertificateTrustPanel class in the Security Interface Framework Reference to display these results to the user.

Availability
Declared In
SecTrust.h

SecTrustGetTPHandle

Retrieves the trust policy handle.

OSStatus SecTrustGetTPHandle (
   SecTrustRef trust,
   CSSM_TP_HANDLE *handle
);

Parameters
trust

The trust management object from which to obtain the trust policy handle. 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.

handle

On return, points to a CSSM trust policy handle. This handle remains valid until the trust management object is released or until the next call to the function SecTrustEvaluate that uses this trust management object.

Return Value

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

Discussion

The trust policy handle is the CSSM identifier of the trust policy module that is managing the certificate. The trust policy handle is used as an input to a number of CSSM functions.

Availability
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
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 anchor certificates. This is the set of certificates that will 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 Mac OS X v10.3, for example, the default set of anchors is 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.

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

Availability
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
Declared In
SecTrust.h

SecTrustSetParameters

Sets the action and action data for a trust management object. 

OSStatus SecTrustSetParameters (
   SecTrustRef trustRef,
   CSSM_TP_ACTION action,
   CFDataRef actionData
);

Parameters
trustRef

The trust management object to which you want to add an action or set action data. 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.

action

A CSSM trust action. Pass CSSM_TP_ACTION_DEFAULT for the default action. Other actions available, if any, are described in the documentation for the trust policy module. For the AppleX509TP module, see the Security Release Notes.

actionData

A reference to action data. “Action Data Flags” lists possible values for this parameter for the AppleX509TP trust policy module’s default action. For other actions (if any), the possible values for the action data are specified in the Security Release Notes.

Return Value

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

Discussion

Before you call SecTrustEvaluate, you can optionally use this function to set one or more action flags or to set action data. Actions, where available, affect the trust evaluation for all policies being evaluated. For example, if you set the action data for the default action to CSSM_TP_ACTION_ALLOW_EXPIRED, then the SecTrustEvaluate function ignores the certificate’s expiration date and time.

Availability
Declared In
SecTrust.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 an other 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
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
Declared In
cssmapple.h

SecCertificateRef

Contains information about a certificate.

typedef struct OpaqueSecCertificateRef *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 will return errors.

Availability
Declared In
SecBase.h

SecIdentityRef

Contains information about an identity.

typedef struct OpaqueSecIdentityRef *SecIdentityRef;

Availability
Declared In
SecBase.h

SecIdentitySearchRef

Contains information about an identity search.

typedef struct OpaqueSecIdentitySearchRef *SecIdentitySearchRef;

Availability
Declared In
SecIdentitySearch.h

SecKeyRef

Contains information about a key.

typedef struct OpaqueSecKeyRef *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 will return errors.

Availability
Declared In
SecBase.h

SecPolicyRef

Contains information about a policy.

typedef struct OpaqueSecPolicyRef *SecPolicyRef;

Availability
Declared In
SecBase.h

SecPolicySearchRef

Contains information about a policy search.

typedef struct OpaquePolicySearchRef *SecPolicySearchRef;

Availability
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
Declared In
SecKeychainItem.h

SecTrustRef

Contains information about trust management.

typedef struct OpaqueSecTrustRef *SecTrustRef;

Availability
Declared In
SecTrust.h

SecTrustUserSetting

Represents user-specified trust settings.

typedef SecTrustResultType SecTrustUserSetting;

Discussion

See “Trust Result Type Constants” for possible values.

Availability
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 Mac OS X v10.2 and later.

Declared in SecCertificate.h

kSecIssuerItemAttr

DER-encoded issuer distinguished name.

Available in Mac OS X v10.2 and later.

Declared in SecCertificate.h

kSecSerialNumberItemAttr

DER-encoded certificate serial number.

Available in Mac OS X v10.2 and later.

Declared in SecCertificate.h

kSecPublicKeyHashItemAttr

Public key hash.

Available in Mac OS X v10.2 and later.

Declared in SecCertificate.h