Deprecated Certificate, Key, and Trust Services Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Available in OS X v10.2 through OS X v10.6

SecTrustGetCSSMAnchorCertificates

Retrieves the CSSM anchor certificates. (Available in OS X v10.2 through OS X v10.6. Use the SecTrustCopyAnchorCertificates function for new development instead.)

OSStatus SecTrustGetCSSMAnchorCertificates (
   const CSSM_DATA **cssmAnchors,
   uint32 *cssmAnchorCount
);
Parameters
cssmAnchors

On return, points to an array of anchor certificates. This array is allocated by the system; you should not deallocate it. This data is not guaranteed to remain valid indefinitely; you should retrieve the data immediately and either pass it to other functions or copy it for future use.

cssmAnchorCount

On return, points to the number of CSSM_DATA structures returned in the cssmAnchors parameter.

Discussion

This function returns the certificates in the system’s store of anchor certificates (see SecTrustSetAnchorCertificates. You can use the CSSM_DATA structures returned by this function as input to functions in the CSSM API.

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.

Special Considerations

Calls to the underlying CSSM API are deprecated. To get references to the anchor certificates in a form appropriate for calls to the Certificate, Key, and Trust API, use the SecTrustCopyAnchorCertificates function instead.

Availability
  • Available in OS X v10.2 through OS X v10.6.
  • Deprecated in OS X v10.5.
Declared In
SecTrust.h

SecTrustGetUserTrust

Retrieves the user-specified trust setting for a certificate and policy. (Available in OS X v10.2 through OS X v10.6. Use SecTrustSettingsCopyTrustSettings for new development instead.)

OSStatus SecTrustGetUserTrust (
   SecCertificateRef certificate,
   SecPolicyRef policy,
   SecTrustUserSetting *trustSetting
);
Parameters
certificate

The certificate object from which to obtain the user-specified trust setting.

policy

The policy object for the policy for which to obtain the user-specified trust setting. Use the SecPolicySearchCopyNext function to obtain a policy object.

trustSetting

On return, points to the user-specified trust setting for the specified certificate and policy.

Discussion

Each certificate has one user-specified trust setting per policy. For each policy, the user can specify that the certificate is always to be trusted, is never to be trusted, or can be trusted only after permission is requested from—and granted by—the user. It is also possible for there to be no user-specified trust setting for a policy. See SecTrustEvaluate for a discussion of the use of user-specified trust settings in a trust evaluation.

The SecTrustGetUserTrust function returns the effective user trust setting for the certificate and policy specified. You can obtain a certificate from a keychain and typecast the keychain item object (data type SecKeychainItemRef) to a certificate object (SecCertificateRef).

See “Trust Result Type Constants” for values and descriptions of the user-specified trust settings. The user can set these values in the Keychain Access utility. If you provide your own UI for these settings, you can use the SecTrustSettingsSetTrustSettings function to set them.

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 SecTrustSetVerifyDate function for the same trust management object on another thread.

Special Considerations

Prior to OS X v10.5, the SecTrustSetUserTrust function did not require user authentication in order to change trust settings. Starting with OS X v10.5, that function is a shell for the SecTrustSettingsSetTrustSettings function, which requires the user to authenticate before changing trust settings. Therefore, the function might block while waiting for user input.

Availability
  • Available in OS X v10.2 through OS X v10.6.
  • Deprecated in OS X v10.5.
Declared In
SecTrust.h

SecTrustSetUserTrust

Sets the user-specified trust settings of a certificate and policy. (Available in OS X v10.2 through OS X v10.6. Use SecTrustSettingsSetTrustSettings for new development instead.)

OSStatus SecTrustSetUserTrust (
   SecCertificateRef certificate,
   SecPolicyRef policy,
   SecTrustUserSetting trustSetting
);
Parameters
certificate

The certificate object for which to set the user-specified trust settings. Use the SecCertificateCreateFromData function to obtain a certificate object.

policy

The policy object for the policy for which to set the user-specified trust settings. Use the SecPolicySearchCopyNext function to obtain a policy object.

trustSetting

The user-specified trust setting to be set. See “Trust Result Type Constants” for possible values.

Discussion

Each certificate has one user-specified trust setting per policy. These trust settings are used by the SecTrustEvaluate function when evaluating trust. See “Trust Result Type Constants” for values and descriptions of the user-specified trust settings. The user can set these values in the Keychain Access utility. Under certain circumstances, it might be appropriate for an administrative application to change a user trust setting. In that case, you can use the SecTrustSetUserTrust function to do so. You can obtain a certificate from a keychain and typecast the keychain item object (data type SecKeychainItemRef) to a certificate object (SecCertificateRef).

When you call the SecTrustSetUserTrust function, the user might be prompted to confirm the new setting before it is changed.

Special Considerations

Prior to OS X v10.5, this function did not require user authentication in order to change trust settings. Starting with OS X v10.5, this function is a shell for the SecTrustSettingsSetTrustSettings function, which requires the user to authenticate before changing trust settings. Therefore, it is not possible to modify per-user trust settings when not running in a GUI environment (that is, when the user is not logged in via the login window). When making changes to system-wide trust settings, the user is prompted with an alert panel asking for an administrator’s name and password unless the calling process is running as root, in which case no further authentication is needed. Note that this function might block while waiting for user input.

Availability
  • Available in OS X v10.2 through OS X v10.6.
  • Deprecated in OS X v10.5.
Declared In
SecTrust.h

Deprecated in OS X v10.7

SecCertificateCopyPreference

Retrieves the preferred certificate for the specified name and key use. (Deprecated in OS X v10.7.)

OSStatus SecCertificateCopyPreference (
   CFStringRef name,
   uint32 keyUsage,
   SecCertificateRef *certificate
);
Parameters
name

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

keyUsage

A key use value, as defined in Security.framework/cssmtype.h. Pass 0 to ignore this parameter.

certificate

On return, a reference to the preferred certificate, or NULL if none was found. Call the CFRelease function to release this object when you are finished with it.

Discussion

This function is typically used to obtain the preferred encryption certificate for an email recipient.

Special Considerations

Use SecCertificateCopyPreferred for new development instead.

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

SecCertificateCreateFromData

Creates a certificate object based on the specified data, type, and encoding. (Deprecated in OS X v10.7.)

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 Security.framework/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 Security.framework/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.

Discussion

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

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

SecCertificateGetAlgorithmID

Retrieves the algorithm identifier for a certificate. (Deprecated in OS X v10.7.)

OSStatus SecCertificateGetAlgorithmID (
   SecCertificateRef certificate,
   const CSSM_X509_ALGORITHM_IDENTIFIER **algid
);
Parameters
certificate

The certificate object from which to retrieve the algorithm identifier.

algid

On return, points to a struct that identifies the algorithm for this certificate. This pointer remains valid until the certificate reference is released. Do not attempt to free this pointer.

Discussion

The CSSM_X509_ALGORITHM_IDENTIFIER struct is defined in Security.framework/x509defs.h and discussed in Common Security: CDSA and CSSM, version 2 (with corrigenda) from The Open Group (http://www.opengroup.org/security/cdsa.htm). Possible algorithms are enumerated in Security.framework/oidsalg.h.

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

SecCertificateGetCLHandle

Retrieves the certificate library handle from a certificate object. (Deprecated in OS X v10.7.)

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.

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
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecCertificate.h

SecCertificateGetData

Retrieves the data for a certificate. (Deprecated in OS X v10.7.)

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.

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
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecCertificate.h

SecCertificateGetIssuer

Unsupported. (Deprecated in OS X v10.7.)

OSStatus SecCertificateGetIssuer (
   SecCertificateRef certificate,
   const CSSM_X509_NAME **issuer
);
Availability
  • Unsupported.
  • Deprecated in OS X v10.7.
Declared In
SecCertificate.h

SecCertificateGetSubject

Unsupported. (Deprecated in OS X v10.7.)

OSStatus SecCertificateGetSubject (
   SecCertificateRef certificate,
   const CSSM_X509_NAME **subject
);
Availability
  • Unsupported.
  • Deprecated in OS X v10.7.
Declared In
SecCertificate.h

SecCertificateGetType

Retrieves the type of a specified certificate. (Deprecated in OS X v10.7.)

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 Security.framework/cssmtype.h. You must allocate the space for a CSSM_CERT_TYPE structure before calling this function.

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

SecIdentityCopyPreference

Returns the preferred identity for the specified name and key use. (Deprecated in OS X v10.7.)

OSStatus SecIdentityCopyPreference (
   CFStringRef name,
   CSSM_KEYUSE keyUsage,
   CFArrayRef validIssuers,
   SecIdentityRef *identity
);
Parameters
name

A string containing a URI, RFC822 email address, DNS hostname, or other name that uniquely identifies the service requiring an identity.

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.

validIssuers

An array of CFDataRef instances whose contents are the subject names of allowable issuers, as returned by a call to SSLCopyDistinguishedNames (Security.framework/SecureTransport.h). Pass NULL if you don’t want to limit the search to specific issuers.

identity

On return, a reference to the preferred identity, or NULL if none was found. Call the CFRelease function to release this object when you are finished with it.

Discussion

If a preferred identity has not been set for the specified name, the returned identity reference is NULL. You should then typically perform a search for possible identities, using SecIdentitySearchCreate and SecIdentitySearchCopyNext, allowing the user to choose from a list if more than one is found.

Special Considerations

Use SecIdentityCopyPreferred for new development instead.

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

SecIdentitySearchCopyNext

Finds the next identity matching specified search criteria (Deprecated in OS X v10.7.)

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
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecIdentitySearch.h

SecIdentitySearchCreate

Creates a search object for finding identities. (Deprecated in OS X v10.7.)

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

A CSSM key use value as defined in Security.framework/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 0 if you want all identities returned by this search. Pass 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.

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
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecIdentitySearch.h

SecIdentitySearchGetTypeID

Returns the unique identifier of the opaque type to which a SecIdentitySearch object belongs. (Deprecated in OS X v10.7.)

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
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecIdentitySearch.h

SecIdentitySetPreference

Sets the preferred identity for the specified name and key use. (Deprecated in OS X v10.7.)

OSStatus SecIdentitySetPreference (
   SecIdentityRef identity,
   CFStringRef name,
   CSSM_KEYUSE keyUsage
);
Parameters
identity

A reference to the preferred identity.

name

A string containing a URI, RFC822 email address, DNS host name, or other name that uniquely identifies a service requiring this identity.

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.

Special Considerations

Use SecIdentitySetPreferred for new development instead.

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

SecKeyCreatePair

Creates an asymmetric key pair and stores it in a keychain. (Deprecated in OS X v10.7.)

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 Security.framework/cssmtype.h. Algorithms supported by the AppleCSP module are listed in Apple Cryptographic Service Provider Functional Specification. This parameter is ignored if the contextHandle parameter is not 0.

keySizeInBits

A key size for the key pair. See Apple Cryptographic Service Provider Functional Specification for permissible key sizes for each algorithm supported by the AppleCSP module.

contextHandle

A CSSM CSP 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 Security.framework/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 Security.framework/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 Security.framework/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 Security.framework/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.

Discussion

This function uses default values for any attributes required by specific key-generation algorithms. Algorithms supported by the AppleCSP module are listed in Apple Cryptographic Service Provider Functional Specification. For details about algorithms and default values for key-generation parameters, download the CDSA security framework from Apple’s Open Source website at http://opensource.apple.com/ 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 algorithms—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 after calling this function.

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

SecKeyGenerate

Creates a symmetric key and optionally stores it in a keychain. (Deprecated in OS X v10.7.)

OSStatus SecKeyGenerate (
   SecKeychainRef keychainRef,
   CSSM_ALGORITHMS algorithm,
   uint32 keySizeInBits,
   CSSM_CC_HANDLE contextHandle,
   CSSM_KEYUSE keyUsage,
   uint32 keyAttr,
   SecAccessRef initialAccess,
   SecKeyRef *keyRef
);
Parameters
keychainRef

The keychain in which to store the generated key. Specify NULL to generate a transient key.

algorithm

The algorithm to use in generating the symmetric key. Possible values are defined in cssmtype.h. Algorithms supported by the AppleCSP module are listed in Apple Cryptographic Service Provider Functional Specification. This parameter is ignored if the contextHandle parameter is not 0.

keySizeInBits

A key size for the key pair. This parameter is ignored if the contextHandle parameter is not 0.

contextHandle

A CSSM CSP handle, or 0. If this argument is not 0, the algorithm and keySizeInBits parameters are ignored.

keyUsage

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

keyAttr

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

initialAccess

An access object that sets the initial access control list for the key returned. See “Creating an Access Object” in Keychain Services Reference for functions that create an access object. This parameter is ignored if you specify NULL for the keychainRef parameter.

keyRef

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.

Discussion

Key-generation algorithms supported by the AppleCSP module are listed in Apple Cryptographic Service Provider Functional Specification. For details about algorithms and default values for key-generation parameters, download the CDSA security framework from Apple’s Open Source website at http://opensource.apple.com/ 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 algorithms—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 after calling this function.

Special Considerations

Use SecKeyGenerateSymmetric instead.

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

SecKeyGetCredentials

Returns an access credential for a key. (Deprecated in OS X v10.7.)

OSStatus SecKeyGetCredentials (
   SecKeyRef keyRef,
   CSSM_ACL_AUTHORIZATION_TAG operation,
   SecCredentialType credentialType,
   const CSSM_ACCESS_CREDENTIALS **outCredentials
);
Parameters
keyRef

The key for which you want an access credential.

operation

The type of operation to be performed with this key. Possible values are listed under “Authorization tag types” in Security.framework/cssmtype.h.

credentialType

The type of credential requested. See “Key Credential Type Constants” for possible values.

outCredentials

On return, points to an access credential for the specified key. This pointer remains valid until the key reference is released. Do not attempt to modify or free this data.

Discussion

An access credential is required as an input to a number of CSSM functions.

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

SecKeyGetCSPHandle

Returns the CSSM CSP handle for a key. (Deprecated in OS X v10.7.)

OSStatus SecKeyGetCSPHandle (
   SecKeyRef keyRef,
   CSSM_CSP_HANDLE *cspHandle
);
Parameters
keyRef

The key for which you want a CSSM CSP handle.

cspHandle

On return, points to the CSSM CSP handle for the specified key. This pointer remains valid until the key reference is released. Do not attempt to modify or free this data.

Discussion

A CSSM CSP handle is required as an input to a number of CSSM functions.

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

SecKeyGetCSSMKey

Retrieves a pointer to the CSSM_KEY structure containing the key stored in a keychain item. (Deprecated in OS X v10.7.)

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.

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
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecKey.h

SecPolicyGetOID

Retrieves a policy’s object identifier. (Deprecated in OS X v10.7.)

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.

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
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.7.
Declared In
SecPolicy.h

SecPolicyGetTPHandle

Retrieves the trust policy handle for a policy object. (Deprecated in OS X v10.7.)

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.

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
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.7.
Declared In
SecPolicy.h

SecPolicyGetValue

Retrieves a policy’s value. (Deprecated in OS X v10.7.)

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.

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
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.7.
Declared In
SecPolicy.h

SecPolicySearchCopyNext

Retrieves a policy object for the next policy matching specified search criteria. (Deprecated in OS X v10.7.)

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
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecPolicySearch.h

SecPolicySearchCreate

Creates a search object for finding policies. (Deprecated in OS X v10.7.)

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 Security.framework/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.

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
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecPolicySearch.h

SecPolicySearchGetTypeID

Returns the unique identifier of the opaque type to which a SecPolicySearch object belongs. (Deprecated in OS X v10.7.)

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
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecPolicySearch.h

SecPolicySetValue

Sets a policy's value. (Deprecated in OS X v10.7.)

OSStatus SecPolicySetValue (
   SecPolicyRef policyRef,
   const CSSM_DATA *value
);
Parameters
policyRef

The policy object whose value you wish to set.

value

The value to be set into the policy object, replacing any previous value.

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
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.7.
Declared In
SecPolicy.h

SecTrustGetCssmResult

Retrieves the CSSM trust result. (Deprecated in OS X v10.7.)

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.

Discussion

After calling the SecTrustEvaluate function, you can call the SecTrustGetTrustResult 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 SecTrustGetTrustResult 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.

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 SecTrustSetVerifyDate function for the same trust management object on another thread.

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

SecTrustGetCssmResultCode

Retrieves the CSSM result code from the most recent trust evaluation for a trust management object. (Deprecated in OS X v10.7.)

OSStatus SecTrustGetCssmResultCode (
   SecTrustRef trust,
   OSStatus *resultCode
);
Parameters
trust

The trust management object for which you wish to retrieve a result code.

resultCode

On return, the CSSM result code produced by the most recent call to the SecTrustEvaluate function for the trust management object specified in the trust parameter. The value of this parameter is undefined if SecTrustEvaluate has not been called.

Return Value

A result code. See “Certificate, Key, and Trust Services Result Codes.” Returns errSecTrustNotAvailable if the SecTrustEvaluate function has not been called for the specified trust.

Discussion

Whereas the SecTrustEvaluate function returns one of the Security Framework result codes (see “Certificate, Key, and Trust Services Result Codes”), the SecTrustGetCssmResultCode function returns the CSSM result code as enumerated in Security.framework/cssmerr.h. Call this function to get a more specific reason for a failure than provided by SecTrustEvaluate. Other functions that might be of interest are the SecTrustGetTrustResult function, which returns detailed results for each certificate in the certificate chain, and the SecTrustGetCssmResult function, which returns the results in a format that can be passed directly to CSSM functions.

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 SecTrustSetVerifyDate function for the same trust management object on another thread.

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

SecTrustGetResult

Retrieves details on the outcome of a call to the function SecTrustEvaluate. (Deprecated in OS X v10.7.)

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.

Discussion

After calling the SecTrustEvaluate function, you can call the SecTrustGetResult 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.

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 SecTrustSetVerifyDate function for the same trust management object on another thread.

Special Considerations

Use SecTrustGetTrustResult for new development instead.

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

SecTrustGetTPHandle

Retrieves the trust policy handle. (Deprecated in OS X v10.7.)

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.

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.

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 SecTrustSetVerifyDate function for the same trust management object on another thread.

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

SecTrustSetParameters

Sets the action and action data for a trust management object. (Deprecated in OS X v10.7.)

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 Apple Trust Policy Module Functional Specification.

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 Apple Trust Policy Module Functional Specification.

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.

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.
  • Deprecated in OS X v10.7.
Declared In
SecTrust.h

Deprecated in OS X v10.9

SecPolicyCreateWithOID

Returns a policy object for the specified policy type object identifier. (Deprecated in OS X v10.9.)

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.
  • Deprecated in OS X v10.9.
Declared In
SecPolicy.h

SecPolicySetProperties

Sets properties for a policy. (Deprecated in OS X v10.9.)

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.

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