Mac Developer Library

Developer

Security Framework Reference Certificate, Key, and Trust Services Reference

Options
Deployment Target:

On This Page
Language:

Certificate, Key, and Trust Services Reference

Certificate, Key, and Trust Services provides a C API for managing certificates, public and private keys, and trust policies. You can use these services in your application to:

  • Determine identity by matching a certificate with a private key

  • Create and request certificate objects

  • Import certificates, keys, and identities

  • Create public-private key pairs

  • Represent trust policies

Concurrency Considerations

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

On OS X v10.6, some functions can block while waiting for input from the user (for example, when the user is asked to unlock a keychain or give permission to change trust settings). In general, it is safe to use the functions in this API from threads other than your main thread, but you should avoid calling the function from multiple operations, work queues, or threads concurrently. Instead, function calls should be serialized (or confined to a single thread) to prevent any potential problems. Exceptions are noted in the discussions of the relevant functions.

Functions

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

    Declaration

    Swift

    func SecCertificateGetTypeID() -> CFTypeID

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func SecIdentityGetTypeID() -> CFTypeID

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

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

    Declaration

    Swift

    func SecKeyGetTypeID() -> CFTypeID

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func SecPolicyGetTypeID() -> CFTypeID

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

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

    Declaration

    Swift

    func SecTrustGetTypeID() -> CFTypeID

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.3 and later.

  • Adds a certificate to a keychain.

    Declaration

    Swift

    func SecCertificateAddToKeychain(_ certificate: SecCertificate!, _ keychain: SecKeychain!) -> OSStatus

    Objective-C

    OSStatus SecCertificateAddToKeychain ( SecCertificateRef certificate, SecKeychainRef keychain );

    Parameters

    certificate

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

    keychain

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

    Return Value

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

    Discussion

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

    Special Considerations

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Objective-C

    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.

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

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

    Declaration

    Swift

    func SecCertificateCreateWithData(_ allocator: CFAllocator!, _ data: CFData!) -> Unmanaged<SecCertificate>!

    Objective-C

    SecCertificateRef SecCertificateCreateWithData ( CFAllocatorRef allocator, CFDataRef data );

    Parameters

    allocator

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

    data

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

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Swift

    func SecCertificateCopyData(_ certificate: SecCertificate!) -> Unmanaged<CFData>!

    Objective-C

    CFDataRef SecCertificateCopyData ( SecCertificateRef certificate );

    Parameters

    certificate

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

    Return Value

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.6 and later.

  • Retrieves the common name of the subject of a certificate.

    Declaration

    Swift

    func SecCertificateCopyCommonName(_ certificate: SecCertificate!, _ commonName: UnsafeMutablePointer<Unmanaged<CFString>?>) -> OSStatus

    Objective-C

    OSStatus SecCertificateCopyCommonName ( SecCertificateRef certificate, CFStringRef *commonName );

    Parameters

    certificate

    The certificate object from which to retrieve the common name.

    commonName

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

    Return Value

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.5 and later.

  • Retrieves the email addresses for the subject of a certificate.

    Declaration

    Swift

    func SecCertificateCopyEmailAddresses(_ certificate: SecCertificate!, _ emailAddresses: UnsafeMutablePointer<Unmanaged<CFArray>?>) -> OSStatus

    Objective-C

    OSStatus SecCertificateCopyEmailAddresses ( SecCertificateRef certificate, CFArrayRef *emailAddresses );

    Parameters

    certificate

    The certificate object from which to retrieve the email addresses.

    emailAddresses

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

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.5 and later.

  • Returns a copy of the long description of a certificate.

    Declaration

    Swift

    func SecCertificateCopyLongDescription(_ alloc: CFAllocator!, _ certificate: SecCertificate!, _ error: UnsafeMutablePointer<Unmanaged<CFError>?>) -> Unmanaged<CFString>!

    Objective-C

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

    Parameters

    alloc

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

    certificate

    The certificate from which the long description should be copied.

    error

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

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func SecCertificateCopyNormalizedIssuerContent(_ certificate: SecCertificate!, _ error: UnsafeMutablePointer<Unmanaged<CFError>?>) -> Unmanaged<CFData>!

    Objective-C

    CFDataRef SecCertificateCopyNormalizedIssuerContent ( SecCertificateRef certificate, CFErrorRef *error );

    Parameters

    certificate

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

    error

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

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func SecCertificateCopyNormalizedSubjectContent(_ certificate: SecCertificate!, _ error: UnsafeMutablePointer<Unmanaged<CFError>?>) -> Unmanaged<CFData>!

    Objective-C

    CFDataRef SecCertificateCopyNormalizedSubjectContent ( SecCertificateRef certificate, CFErrorRef *error );

    Parameters

    certificate

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

    error

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

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

  • Retrieves the preferred certificate for the specified name and key use.

    Declaration

    Objective-C

    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.

    Return Value

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

    Discussion

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

    Special Considerations

    Use SecCertificateCopyPreferred for new development instead.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

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

    Declaration

    Swift

    func SecCertificateCopyPreferred(_ name: CFString!, _ keyUsage: CFArray!) -> Unmanaged<SecCertificate>!

    Objective-C

    SecCertificateRef SecCertificateCopyPreferred ( CFStringRef name, CFArrayRef keyUsage );

    Parameters

    name

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

    keyUsage

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

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

  • Retrieves the public key from a certificate.

    Declaration

    Swift

    func SecCertificateCopyPublicKey(_ certificate: SecCertificate!, _ key: UnsafeMutablePointer<Unmanaged<SecKey>?>) -> OSStatus

    Objective-C

    OSStatus SecCertificateCopyPublicKey ( SecCertificateRef certificate, SecKeyRef *key );

    Parameters

    certificate

    The certificate object from which to retrieve the public key.

    key

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

    Return Value

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.3 and later.

  • Returns a copy of a certificate’s serial number.

    Declaration

    Swift

    func SecCertificateCopySerialNumber(_ certificate: SecCertificate!, _ error: UnsafeMutablePointer<Unmanaged<CFError>?>) -> Unmanaged<CFData>!

    Objective-C

    CFDataRef SecCertificateCopySerialNumber ( SecCertificateRef certificate, CFErrorRef *error );

    Parameters

    certificate

    The certificate from which the serial number should be copied.

    error

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

    Return Value

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

  • Returns a copy of the short description of a certificate.

    Declaration

    Swift

    func SecCertificateCopyShortDescription(_ alloc: CFAllocator!, _ certificate: SecCertificate!, _ error: UnsafeMutablePointer<Unmanaged<CFError>?>) -> Unmanaged<CFString>!

    Objective-C

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

    Parameters

    alloc

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

    certificate

    The certificate from which the short description should be copied.

    error

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

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

  • Returns a human-readable summary of a certificate.

    Declaration

    Swift

    func SecCertificateCopySubjectSummary(_ certificate: SecCertificate!) -> Unmanaged<CFString>!

    Objective-C

    CFStringRef SecCertificateCopySubjectSummary ( SecCertificateRef certificate );

    Parameters

    certificate

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

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.6 and later.

  • Creates a dictionary that represents a certificate's contents.

    Declaration

    Swift

    func SecCertificateCopyValues(_ certificate: SecCertificate!, _ keys: CFArray!, _ error: UnsafeMutablePointer<Unmanaged<CFError>?>) -> Unmanaged<CFDictionary>!

    Objective-C

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

    Parameters

    certificate

    The certificate from which values should be copied.

    keys

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

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

    error

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

    Return Value

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

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

  • Retrieves the algorithm identifier for a certificate.

    Declaration

    Objective-C

    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.

    Return Value

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

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

  • Retrieves the certificate library handle from a certificate object.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

  • Retrieves the data for a certificate.

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

  • Unsupported.

    Declaration

    Objective-C

    OSStatus SecCertificateGetIssuer ( SecCertificateRef certificate, const CSSM_X509_NAME **issuer );

    Import Statement

    Objective-C

    @import Security;

    Availability

    Unsupported.

    Deprecated in OS X v10.7.

  • Unsupported.

    Declaration

    Objective-C

    OSStatus SecCertificateGetItem ( SecCertificateRef certificate, SecKeychainItemRef *item );

    Import Statement

    Objective-C

    @import Security;

    Availability

    Unsupported.

    Not available to 64-bit applications.

  • Unsupported.

    Declaration

    Objective-C

    OSStatus SecCertificateGetSubject ( SecCertificateRef certificate, const CSSM_X509_NAME **subject );

    Import Statement

    Objective-C

    @import Security;

    Availability

    Unsupported.

    Deprecated in OS X v10.7.

  • Retrieves the type of a specified certificate.

    Declaration

    Objective-C

    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.

    Return Value

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

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

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

    Declaration

    Swift

    func SecCertificateSetPreference(_ certificate: SecCertificate!, _ name: CFString!, _ keyUsage: uint32, _ date: CFDate!) -> OSStatus

    Objective-C

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

    Parameters

    certificate

    The certificate object identifying the preferred certificate.

    name

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

    keyUsage

    A key use value, as defined in Security.framework/cssmtype.h. Pass 0 if you don’t want to specify a particular key use.

    date

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

    Return Value

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

    Discussion

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

    Special Considerations

    Use SecCertificateSetPreferred for new development instead.

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func SecCertificateSetPreferred(_ certificate: SecCertificate!, _ name: CFString!, _ keyUsage: CFArray!) -> OSStatus

    Objective-C

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

    Parameters

    certificate

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

    name

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

    keyUsage

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

    Return Value

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

  • Retrieves a certificate associated with an identity.

    Declaration

    Swift

    func SecIdentityCopyCertificate(_ identityRef: SecIdentity!, _ certificateRef: UnsafeMutablePointer<Unmanaged<SecCertificate>?>) -> OSStatus

    Objective-C

    OSStatus SecIdentityCopyCertificate ( SecIdentityRef identityRef, SecCertificateRef *certificateRef );

    Parameters

    identityRef

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

    certificateRef

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

    Return Value

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

    Discussion

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

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.3 and later.

  • Returns the preferred identity for the specified name and key use.

    Declaration

    Objective-C

    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.

    Return Value

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

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

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

    Declaration

    Swift

    func SecIdentityCopyPreferred(_ name: CFString!, _ keyUsage: CFArray!, _ validIssuers: CFArray!) -> Unmanaged<SecIdentity>!

    Objective-C

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

    Parameters

    name

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

    keyUsage

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

    validIssuers

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

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

  • Retrieves the private key associated with an identity.

    Declaration

    Swift

    func SecIdentityCopyPrivateKey(_ identityRef: SecIdentity!, _ privateKeyRef: UnsafeMutablePointer<Unmanaged<SecKey>?>) -> OSStatus

    Objective-C

    OSStatus SecIdentityCopyPrivateKey ( SecIdentityRef identityRef, SecKeyRef *privateKeyRef );

    Parameters

    identityRef

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

    privateKeyRef

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

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func SecIdentityCopySystemIdentity(_ domain: CFString!, _ idRef: UnsafeMutablePointer<Unmanaged<SecIdentity>?>, _ actualDomain: UnsafeMutablePointer<Unmanaged<CFString>?>) -> OSStatus

    Objective-C

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

    Parameters

    domain

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

    idRef

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

    actualDomain

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

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func SecIdentityCreateWithCertificate(_ keychainOrArray: AnyObject!, _ certificateRef: SecCertificate!, _ identityRef: UnsafeMutablePointer<Unmanaged<SecIdentity>?>) -> OSStatus

    Objective-C

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

    Parameters

    keychainOrArray

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

    certificateRef

    The certificate for which you want to create an identity.

    identityRef

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

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.5 and later.

  • Finds the next identity matching specified search criteria

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

  • Creates a search object for finding identities.

    Declaration

    Objective-C

    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.

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

  • Sets the preferred identity for the specified name and key use.

    Declaration

    Objective-C

    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.

    Return Value

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

    Special Considerations

    Use SecIdentitySetPreferred for new development instead.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

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

    Declaration

    Swift

    func SecIdentitySetPreferred(_ identity: SecIdentity!, _ name: CFString!, _ keyUsage: CFArray!) -> OSStatus

    Objective-C

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

    Parameters

    identity

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

    name

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

    keyUsage

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

    Return Value

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func SecIdentitySetSystemIdentity(_ domain: CFString!, _ idRef: SecIdentity!) -> OSStatus

    Objective-C

    OSStatus SecIdentitySetSystemIdentity ( CFStringRef domain, SecIdentityRef idRef );

    Parameters

    domain

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

    idRef

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

    Return Value

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

    Discussion

    The caller must be running as root.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func SecPKCS12Import(_ pkcs12_data: CFData!, _ options: CFDictionary!, _ items: UnsafeMutablePointer<Unmanaged<CFArray>?>) -> OSStatus

    Objective-C

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

    Parameters

    pkcs12_data

    The PKCS #12 data you wish to decode.

    options

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

    items

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

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Objective-C

    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.

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

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

    See Also

    SecKeyGenerate

  • Constructs a SecKeyRef object for a symmetric key.

    Declaration

    Swift

    func SecKeyCreateFromData(_ parameters: CFDictionary!, _ keyData: CFData!, _ error: UnsafeMutablePointer<Unmanaged<CFError>?>) -> Unmanaged<SecKey>!

    Objective-C

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

    Parameters

    parameters

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

    keyData

    A CFDataRef object that contains the raw key data.

    error

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

    Return Value

    Returns a SecKeyRef object containing the symmetric key.

    Discussion

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

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

    These values default to true if no value is specified.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func SecKeyDeriveFromPassword(_ password: CFString!, _ parameters: CFDictionary!, _ error: UnsafeMutablePointer<Unmanaged<CFError>?>) -> Unmanaged<SecKey>!

    Objective-C

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

    Parameters

    password

    The password from which the key should be derived.

    parameters

    A set of parameters for deriving the password.

    error

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

    Return Value

    Returns the derived SecKeyRef object, or NULL on error.

    Discussion

    The parameters dictionary must contain at least the following keys:

    • kSecKeyKeyType—the type of symmetric key to generate.

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

    The parameters dictionary may contain the following optional keys:

    • kSecAttrPRF - the algorithm to use for the pseudorandom-function.

      If zero, this defaults to kSecAttrPRFHmacAlgSHA1. For a list of possible values, see kSecAttrPRF Value Constants.

    • kSecAttrRounds—the number of times to call the pseudorandom function. If zero, the count is computed so that computation will take 1/10 of a second (on average).

    • kSecAttrKeySizeInBits—a CFNumberRef value containing the requested key size in bits. The key size must be valid for the key type. Defaults to 128 if not provided.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

  • Creates a symmetric key and optionally stores it in a keychain.

    Declaration

    Objective-C

    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.

    Return Value

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

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

    See Also

    SecKeyCreatePair

  • Creates an asymmetric key pair.

    Declaration

    Swift

    func SecKeyGeneratePair(_ parameters: CFDictionary!, _ publicKey: UnsafeMutablePointer<Unmanaged<SecKey>?>, _ privateKey: UnsafeMutablePointer<Unmanaged<SecKey>?>) -> OSStatus

    Objective-C

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

    Parameters

    parameters

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

    publicKey

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

    privateKey

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

    Return Value

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

    Discussion

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

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

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

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

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

  • Generates a public/private key pair.

    Declaration

    Swift

    func SecKeyGeneratePairAsync(_ parameters: CFDictionary!, _ deliveryQueue: dispatch_queue_t!, _ result: SecKeyGeneratePairBlock!)

    Objective-C

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

    Parameters

    parameters

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

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

    deliveryQueue

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

    result

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

  • Generates a random symmetric key.

    Declaration

    Swift

    func SecKeyGenerateSymmetric(_ parameters: CFDictionary!, _ error: UnsafeMutablePointer<Unmanaged<CFError>?>) -> Unmanaged<SecKey>!

    Objective-C

    SecKeyRef SecKeyGenerateSymmetric ( CFDictionaryRef parameters, CFErrorRef *error );

    Parameters

    parameters

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

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

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

    error

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

    Return Value

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

  • Unwraps a wrapped symmetric key.

    Declaration

    Swift

    func SecKeyUnwrapSymmetric(_ keyToUnwrap: UnsafeMutablePointer<Unmanaged<CFData>?>, _ unwrappingKey: SecKey!, _ parameters: CFDictionary!, _ error: UnsafeMutablePointer<Unmanaged<CFError>?>) -> Unmanaged<SecKey>!

    Objective-C

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

    Parameters

    keyToUnwrap

    The wrapped key to unwrap.

    unwrappingKey

    The key that must be used to unwrap keyToUnwrap.

    parameters

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

    error

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

    Return Value

    Returns the unwrapped key, or NULL upon failure.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

  • Wraps a symmetric key with another key.

    Declaration

    Swift

    func SecKeyWrapSymmetric(_ keyToWrap: SecKey!, _ wrappingKey: SecKey!, _ parameters: CFDictionary!, _ error: UnsafeMutablePointer<Unmanaged<CFError>?>) -> Unmanaged<CFData>!

    Objective-C

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

    Parameters

    keyToWrap

    The key to wrap.

    wrappingKey

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

    parameters

    The key to use when wrapping keyToWrap.

    error

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

    Return Value

    Returns the wrapped key, or NULL upon error.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

  • Returns an access credential for a key.

    Declaration

    Objective-C

    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.

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

  • Returns the CSSM CSP handle for a key.

    Declaration

    Objective-C

    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.

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

  • Gets the block length associated with a cryptographic key.

    Declaration

    Swift

    func SecKeyGetBlockSize(_ key: SecKey!) -> UInt

    Objective-C

    size_t SecKeyGetBlockSize ( SecKeyRef key );

    Parameters

    key

    The key for which you want the block length.

    Return Value

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

  • Returns a dictionary containing a policy’s properties.

    Declaration

    Swift

    func SecPolicyCopyProperties(_ policyRef: SecPolicy!) -> Unmanaged<CFDictionary>!

    Objective-C

    CFDictionaryRef SecPolicyCopyProperties ( SecPolicyRef policyRef );

    Parameters

    policyRef

    The policy from which properties should be copied.

    Return Value

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func SecPolicyCreateBasicX509() -> Unmanaged<SecPolicy>!

    Objective-C

    SecPolicyRef SecPolicyCreateBasicX509 ( void );

    Return Value

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.6 and later.

  • Returns a policy object for evaluating SSL certificate chains.

    Declaration

    Swift

    func SecPolicyCreateSSL(_ server: Boolean, _ hostname: CFString!) -> Unmanaged<SecPolicy>!

    Objective-C

    SecPolicyRef SecPolicyCreateSSL ( Boolean server, CFStringRef hostname );

    Parameters

    server

    Specify true on the client side to return a policy for SSL server certificates.

    hostname

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

    Return Value

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Objective-C

    SecPolicyRef SecPolicyCreateWithOID ( CFTypeRef policyOID );

    Parameters

    policyOID

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

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.7 and later.

    Deprecated in OS X v10.9.

  • Retrieves a policy’s object identifier.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.7.

  • Retrieves the trust policy handle for a policy object.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.7.

  • Retrieves a policy’s value.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.7.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

  • Creates a search object for finding policies.

    Declaration

    Objective-C

    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.

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

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

  • Sets properties for a policy.

    Declaration

    Objective-C

    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.

    Return Value

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

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.7 and later.

    Deprecated in OS X v10.9.

  • Sets a policy's value.

    Declaration

    Objective-C

    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.

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.7.

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

    Declaration

    Swift

    func SecTrustCopyAnchorCertificates(_ anchors: UnsafeMutablePointer<Unmanaged<CFArray>?>) -> OSStatus

    Objective-C

    OSStatus SecTrustCopyAnchorCertificates ( CFArrayRef *anchors );

    Parameters

    anchors

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

    Return Value

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

    Discussion

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

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func SecTrustCopyCustomAnchorCertificates(_ trust: SecTrust!, _ anchors: UnsafeMutablePointer<Unmanaged<CFArray>?>) -> OSStatus

    Objective-C

    OSStatus SecTrustCopyCustomAnchorCertificates ( SecTrustRef trust, CFArrayRef *anchors );

    Parameters

    trust

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

    anchors

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

    Return Value

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

    Discussion

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

    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.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func SecTrustCopyExceptions(_ trust: SecTrust!) -> Unmanaged<CFData>!

    Objective-C

    CFDataRef SecTrustCopyExceptions ( SecTrustRef trust );

    Parameters

    trust

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

    Return Value

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

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

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.9 and later.

  • Returns an array containing the properties of a trust object.

    Declaration

    Swift

    func SecTrustCopyProperties(_ trust: SecTrust!) -> Unmanaged<CFArray>!

    Objective-C

    CFArrayRef SecTrustCopyProperties ( SecTrustRef trust );

    Parameters

    trust

    The trust object from which properties should be copied.

    Return Value

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

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

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

  • Retrieves the policies used by a given trust management object.

    Declaration

    Swift

    func SecTrustCopyPolicies(_ trust: SecTrust!, _ policies: UnsafeMutablePointer<Unmanaged<CFArray>?>) -> OSStatus

    Objective-C

    OSStatus SecTrustCopyPolicies ( SecTrustRef trust, CFArrayRef *policies );

    Parameters

    trust

    The trust management object whose policies you wish to retrieve.

    policies

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

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func SecTrustCopyPublicKey(_ trust: SecTrust!) -> Unmanaged<SecKey>!

    Objective-C

    SecKeyRef SecTrustCopyPublicKey ( SecTrustRef trust );

    Parameters

    trust

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

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

  • Creates a trust management object based on certificates and policies.

    Declaration

    Swift

    func SecTrustCreateWithCertificates(_ certificates: AnyObject!, _ policies: AnyObject!, _ trustRef: UnsafeMutablePointer<Unmanaged<SecTrust>?>) -> OSStatus

    Objective-C

    OSStatus SecTrustCreateWithCertificates ( CFTypeRef certificates, CFTypeRef policies, SecTrustRef *trust );

    Parameters

    certificates

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

    policies

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

    trustRef

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

    Return Value

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

    Discussion

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

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.3 and later.

  • Evaluates trust for the specified certificate and policies.

    Declaration

    Swift

    func SecTrustEvaluate(_ trust: SecTrust!, _ result: UnsafeMutablePointer<SecTrustResultType>) -> OSStatus

    Objective-C

    OSStatus SecTrustEvaluate ( SecTrustRef trust, SecTrustResultType *result );

    Parameters

    trust

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

    result

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

    Return Value

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

    Discussion

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

    Before you call this function:

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

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

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

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

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

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

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

    • Any certificates previously provided by calling SecTrustSetAnchorCertificates.

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

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

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

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

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

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

      Your app should trust the chain.

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

      Your app should not trust the chain.

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

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

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

      The way you handle this depends on the OS.

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

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

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

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

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

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

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

    Special Considerations

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

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.3 and later.

  • Evaluates a trust object asynchronously on the specified dispatch queue.

    Declaration

    Swift

    func SecTrustEvaluateAsync(_ trust: SecTrust!, _ queue: dispatch_queue_t!, _ result: SecTrustCallback!) -> OSStatus

    Objective-C

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

    Parameters

    trust

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

    queue

    The dispatch queue on which the result block should execute.

    result

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

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

  • Returns the number of certificates in an evaluated certificate chain.

    Declaration

    Swift

    func SecTrustGetCertificateCount(_ trust: SecTrust!) -> CFIndex

    Objective-C

    CFIndex SecTrustGetCertificateCount ( SecTrustRef trust );

    Parameters

    trust

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

    Return Value

    The number of certificates in the certificate chain.

    Discussion

    You must call the SecTrustEvaluate function before calling this function.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func SecTrustGetCertificateAtIndex(_ trust: SecTrust!, _ ix: CFIndex) -> Unmanaged<SecCertificate>!

    Objective-C

    SecCertificateRef SecTrustGetCertificateAtIndex ( SecTrustRef trust, CFIndex ix );

    Parameters

    trust

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

    ix

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

    Return Value

    A certificate object for the requested certificate.

    Discussion

    You must call the SecTrustEvaluate function before calling this function.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

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

    Retrieves the CSSM anchor certificates.

    Deprecation Statement

    Use the SecTrustCopyAnchorCertificates function for new development instead.

    Declaration

    Objective-C

    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.

    Return Value

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

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

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

    Deprecated in OS X v10.5.

  • Retrieves the CSSM trust result.

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.7.

  • Retrieves the CSSM result code from the most recent trust evaluation for a trust management object.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.7.

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

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.7.

  • Retrieves the trust policy handle.

    Declaration

    Objective-C

    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.

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.7.

  • Returns the result code from the most recent trust evaluation.

    Declaration

    Swift

    func SecTrustGetTrustResult(_ trustRef: SecTrust!, _ result: UnsafeMutablePointer<SecTrustResultType>) -> OSStatus

    Objective-C

    OSStatus SecTrustGetTrustResult ( SecTrustRef trust, SecTrustResultType *result );

    Parameters

    trustRef

    The trust object from which results should be obtained

    result

    The address where the numeric result should be stored.

    Return Value

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

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

    Retrieves the user-specified trust setting for a certificate and policy.

    Deprecation Statement

    Use SecTrustSettingsCopyTrustSettings for new development instead.

    Declaration

    Objective-C

    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.

    Return Value

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

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

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

    Deprecated in OS X v10.5.

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

    Declaration

    Swift

    func SecTrustGetVerifyTime(_ trust: SecTrust!) -> CFAbsoluteTime

    Objective-C

    CFAbsoluteTime SecTrustGetVerifyTime ( SecTrustRef trust );

    Parameters

    trust

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

    Return Value

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

    Discussion

    This function returns the absolute time returned by:

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

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

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

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Swift

    func SecTrustSetAnchorCertificates(_ trust: SecTrust!, _ anchorCertificates: CFArray!) -> OSStatus

    Objective-C

    OSStatus SecTrustSetAnchorCertificates ( SecTrustRef trust, CFArrayRef anchorCertificates );

    Parameters

    trust

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

    anchorCertificates

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

    Return Value

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

    Discussion

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

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

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

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

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.3 and later.

  • Reenables trusting built-in anchor certificates.

    Declaration

    Swift

    func SecTrustSetAnchorCertificatesOnly(_ trust: SecTrust!, _ anchorCertificatesOnly: Boolean) -> OSStatus

    Objective-C

    OSStatus SecTrustSetAnchorCertificatesOnly ( SecTrustRef trust, Boolean anchorCertificatesOnly );

    Parameters

    trust

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

    anchorCertificatesOnly

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

    Return Value

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

    Discussion

    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.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Swift

    func SecTrustSetExceptions(_ trust: SecTrust!, _ exceptions: CFData!) -> Bool

    Objective-C

    bool SecTrustSetExceptions ( SecTrustRef trust, CFDataRef exceptions );

    Parameters

    trust

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

    exceptions

    An opaque cookie returned by a prior call to SecTrustCopyExceptions.

    Return Value

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

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.9 and later.

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

    Declaration

    Swift

    func SecTrustSetKeychains(_ trust: SecTrust!, _ keychainOrArray: AnyObject!) -> OSStatus

    Objective-C

    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.

    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.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.3 and later.

  • Sets option flags for customizing evaluation of a trust object.

    Declaration

    Swift

    func SecTrustSetOptions(_ trustRef: SecTrust!, _ options: SecTrustOptionFlags) -> OSStatus

    Objective-C

    OSStatus SecTrustSetOptions ( SecTrustRef trustRef, SecTrustOptionFlags options );

    Parameters

    trustRef

    The trust object to modify.

    options

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

    Return Value

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Objective-C

    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.

    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.

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.7.

  • Set the policies to use in an evaluation.

    Declaration

    Swift

    func SecTrustSetPolicies(_ trust: SecTrust!, _ policies: AnyObject!) -> OSStatus

    Objective-C

    OSStatus SecTrustSetPolicies ( SecTrustRef trust, CFTypeRef policies );

    Parameters

    trust

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

    policies

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

    Return Value

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

    Discussion

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

    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.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.3 and later.

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

    Sets the user-specified trust settings of a certificate and policy.

    Deprecation Statement

    Use SecTrustSettingsSetTrustSettings for new development instead.

    Declaration

    Objective-C

    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.

    Return Value

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

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

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

    Deprecated in OS X v10.5.

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

    Declaration

    Swift

    func SecTrustSetVerifyDate(_ trust: SecTrust!, _ verifyDate: CFDate!) -> OSStatus

    Objective-C

    OSStatus SecTrustSetVerifyDate ( SecTrustRef trust, CFDateRef verifyDate );

    Parameters

    trust

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

    verifyDate

    The date and time to use when verifying the certificate.

    Return Value

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

    Discussion

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

    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.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func SecTrustSettingsCopyCertificates(_ domain: SecTrustSettingsDomain, _ certArray: UnsafeMutablePointer<Unmanaged<CFArray>?>) -> OSStatus

    Objective-C

    OSStatus SecTrustSettingsCopyCertificates ( SecTrustSettingsDomain domain, CFArrayRef *certArray );

    Parameters

    domain

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

    certArray

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

    Return Value

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func SecTrustSettingsCopyModificationDate(_ certRef: SecCertificate!, _ domain: SecTrustSettingsDomain, _ modificationDate: UnsafeMutablePointer<Unmanaged<CFDate>?>) -> OSStatus

    Objective-C

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

    Parameters

    certRef

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

    domain

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

    modificationDate

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

    Return Value

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.5 and later.

  • Obtains the trust settings for a certificate.

    Declaration

    Swift

    func SecTrustSettingsCopyTrustSettings(_ certRef: SecCertificate!, _ domain: SecTrustSettingsDomain, _ trustSettings: UnsafeMutablePointer<Unmanaged<CFArray>?>) -> OSStatus

    Objective-C

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

    Parameters

    certRef

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

    domain

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

    trustSettings

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

    Return Value

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

    Discussion

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

    Key

    Value

    kSecTrustSettingsPolicy

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

    kSecTrustSettingsApplication

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

    kSecTrustSettingsPolicyString

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

    kSecTrustSettingsKeyUsage

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

    kSecTrustSettingsResult

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

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

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

    kSecTrustSettingsAllowedError

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

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

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

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

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

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

    Special Considerations

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func SecTrustSettingsCreateExternalRepresentation(_ domain: SecTrustSettingsDomain, _ trustSettings: UnsafeMutablePointer<Unmanaged<CFData>?>) -> OSStatus

    Objective-C

    OSStatus SecTrustSettingsCreateExternalRepresentation ( SecTrustSettingsDomain domain, CFDataRef *trustSettings );

    Parameters

    domain

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

    trustSettings

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

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.5 and later.

  • Imports trust settings into a trust domain.

    Declaration

    Swift

    func SecTrustSettingsImportExternalRepresentation(_ domain: SecTrustSettingsDomain, _ trustSettings: CFData!) -> OSStatus

    Objective-C

    OSStatus SecTrustSettingsImportExternalRepresentation ( SecTrustSettingsDomain domain, CFDataRef trustSettings );

    Parameters

    domain

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

    trustSettings

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

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.5 and later.

  • Deletes the trust settings for a certificate.

    Declaration

    Swift

    func SecTrustSettingsRemoveTrustSettings(_ certRef: SecCertificate!, _ domain: SecTrustSettingsDomain) -> OSStatus

    Objective-C

    OSStatus SecTrustSettingsRemoveTrustSettings ( SecCertificateRef certRef, SecTrustSettingsDomain domain );

    Parameters

    certRef

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

    domain

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

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.5 and later.

  • Specifies trust settings for a certificate.

    Declaration

    Swift

    func SecTrustSettingsSetTrustSettings(_ certRef: SecCertificate!, _ domain: SecTrustSettingsDomain, _ trustSettingsDictOrArray: AnyObject!) -> OSStatus

    Objective-C

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

    Parameters

    certRef

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

    domain

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

    trustSettingsDictOrArray

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

    Return Value

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

    Discussion

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

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

    Special Considerations

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.5 and later.

  • Returns a string describing an error.

    Declaration

    Swift

    func SecCopyErrorMessageString(_ status: OSStatus, _ reserved: UnsafeMutablePointer<Void>) -> Unmanaged<CFString>!

    Objective-C

    CFStringRef SecCopyErrorMessageString ( OSStatus status, void *reserved );

    Parameters

    status

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

    reserved

    Reserved for future use. Pass NULL in this parameter.

    Return Value

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.3 and later.

Data Types

  • Contains information about a certificate evaluation.

    Declaration

    Swift

    struct CSSM_TP_APPLE_EVIDENCE_INFO { var StatusBits: CSSM_TP_APPLE_CERT_STATUS var NumStatusCodes: uint32 var StatusCodes: UnsafeMutablePointer<CSSM_RETURN> var Index: uint32 var DlDbHandle: CSSM_DL_DB_HANDLE var UniqueRecord: CSSM_DB_UNIQUE_RECORD_PTR }

    Objective-C

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

    Fields

    StatusBits

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

    NumStatusCodes

    The number of CSSM_RETURN structures returned in the StatusCodes field.

    StatusCodes

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

    Index

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

    DlDbHandle

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

    UniqueRecord

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

    Discussion

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

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    typealias SecCertificateRef = SecCertificate

    Objective-C

    typedef struct __SecCertificate *SecCertificateRef;

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Abstract Core Foundation-type object representing an identity.

    Declaration

    Swift

    typealias SecIdentityRef = SecIdentity

    Objective-C

    typedef struct __SecIdentity *SecIdentityRef;

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Contains information about an identity search.

    Declaration

    Swift

    typealias SecIdentitySearchRef = SecIdentitySearch

    Objective-C

    typedef struct OpaqueSecIdentitySearchRef *SecIdentitySearchRef;

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Abstract Core Foundation-type object representing an asymmetric key.

    Declaration

    Swift

    typealias SecKeyRef = SecKey

    Objective-C

    typedef struct __SecKey *SecKeyRef;

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Contains information about a policy.

    Declaration

    Swift

    typealias SecPolicyRef = SecPolicy

    Objective-C

    typedef struct OpaqueSecPolicyRef *SecPolicyRef;

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Contains information about a policy search.

    Declaration

    Swift

    typealias SecPolicySearchRef = SecPolicySearch

    Objective-C

    typedef struct OpaquePolicySearchRef *SecPolicySearchRef;

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Represents a 20-byte public key hash.

    Declaration

    Swift

    typealias SecPublicKeyHash = (UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8)

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Contains information about trust management.

    Declaration

    Swift

    typealias SecTrustRef = SecTrust

    Objective-C

    typedef struct __SecTrust *SecTrustRef;

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Represents user-specified trust settings.

    Declaration

    Objective-C

    typedef SecTrustResultType SecTrustUserSetting;

    Discussion

    See Trust Result Type Constants for possible values.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.9.

  • Block called with the results of a call to SecKeyGeneratePairAsync.

    Declaration

    Swift

    typealias SecKeyGeneratePairBlock = (SecKey!, SecKey!, CFError!) -> Void

    Objective-C

    typedef void (^SecKeyGeneratePairBlock)(SecKeyRef publicKey, SecKeyRef privateKey, CFErrorRef error);

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

  • Block called with the results of a call to SecTrustEvaluateAsync.

    Declaration

    Swift

    typealias SecTrustCallback = (SecTrust!, SecTrustResultType) -> Void

    Objective-C

    typedef void (^SecTrustCallback)(SecTrustRef trustRef, SecTrustResultType trustResult);

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

Constants

  • Indicates certificate item attributes.

    Declaration

    Swift

    var kSecSubjectItemAttr: Int { get } var kSecIssuerItemAttr: Int { get } var kSecSerialNumberItemAttr: Int { get } var kSecPublicKeyHashItemAttr: Int { get } var kSecSubjectKeyIdentifierItemAttr: Int { get } var kSecCertTypeItemAttr: Int { get } var kSecCertEncodingItemAttr: Int { get }

    Objective-C

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

    Constants

    • kSecSubjectItemAttr

      kSecSubjectItemAttr

      DER-encoded subject distinguished name.

      Available in OS X v10.2 and later.

    • kSecIssuerItemAttr

      kSecIssuerItemAttr

      DER-encoded issuer distinguished name.

      Available in OS X v10.2 and later.

    • kSecSerialNumberItemAttr

      kSecSerialNumberItemAttr

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

      Available in OS X v10.2 and later.

    • kSecPublicKeyHashItemAttr

      kSecPublicKeyHashItemAttr

      Public key hash.

      Available in OS X v10.2 and later.

    • kSecSubjectKeyIdentifierItemAttr

      kSecSubjectKeyIdentifierItemAttr

      Subject key identifier.

      Available in OS X v10.2 and later.

    • kSecCertTypeItemAttr

      kSecCertTypeItemAttr

      Certificate type.

      Available in OS X v10.2 and later.

    • kSecCertEncodingItemAttr

      kSecCertEncodingItemAttr

      Certificate encoding.

      Available in OS X v10.2 and later.

  • Specifies the status of a certificate.

    Declaration

    Swift

    typealias CSSM_TP_APPLE_CERT_STATUS = uint32

    Objective-C

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

    Constants

    • CSSM_CERT_STATUS_EXPIRED

      CSSM_CERT_STATUS_EXPIRED

      The certificate has expired.

      Available in OS X v10.2 and later.

    • CSSM_CERT_STATUS_NOT_VALID_YET

      CSSM_CERT_STATUS_NOT_VALID_YET

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

      Available in OS X v10.2 and later.

    • CSSM_CERT_STATUS_IS_IN_INPUT_CERTS

      CSSM_CERT_STATUS_IS_IN_INPUT_CERTS

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

      Available in OS X v10.2 and later.

    • CSSM_CERT_STATUS_IS_IN_ANCHORS

      CSSM_CERT_STATUS_IS_IN_ANCHORS

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

      Available in OS X v10.2 and later.

    • CSSM_CERT_STATUS_IS_ROOT

      CSSM_CERT_STATUS_IS_ROOT

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

      Available in OS X v10.2 and later.

    • CSSM_CERT_STATUS_IS_FROM_NET

      CSSM_CERT_STATUS_IS_FROM_NET

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

      Available in OS X v10.3 and later.

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    typealias SecPadding = UInt32

    Objective-C

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

    Constants

    • kSecPaddingNone

      kSecPaddingNone

      No padding.

      Available in OS X v10.6 and later.

    • kSecPaddingPKCS1

      kSecPaddingPKCS1

      PKCS1 padding.

      Available in OS X v10.6 and later.

    • kSecPaddingPKCS1MD2

      kSecPaddingPKCS1MD2

      Data to be signed is an MD2 hash.

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

      Available in OS X v10.6 and later.

    • kSecPaddingPKCS1MD5

      kSecPaddingPKCS1MD5

      Data to be signed is an MD5 hash.

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

      Available in OS X v10.6 and later.

    • kSecPaddingPKCS1SHA1

      kSecPaddingPKCS1SHA1

      Data to be signed is a SHA1 hash.

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

      Available in OS X v10.6 and later.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.6 and later.

  • Use these dictionary keys with the SecKeyGeneratePair function.

    Declaration

    Swift

    var kSecPrivateKeyAttrs: Unmanaged<AnyObject>! var kSecPublicKeyAttrs: Unmanaged<AnyObject>!

    Objective-C

    CFTypeRef kSecPrivateKeyAttrs; CFTypeRef kSecPublicKeyAttrs;

    Constants

    • kSecPrivateKeyAttrs

      kSecPrivateKeyAttrs

      Private cryptographic key attributes.

      The corresponding value is a CFDictionaryRef dictionary containing key-value pairs for attributes specific to the private key to be generated.

      Available in OS X v10.8 and later.

    • kSecPublicKeyAttrs

      kSecPublicKeyAttrs

      Public cryptographic key attributes.

      The corresponding value is a CFDictionaryRef dictionary containing key-value pairs for attributes specific to the public key to be generated.

      Available in OS X v10.8 and later.

  • Specifies the trust result type.

    Declaration

    Swift

    typealias SecTrustResultType = UInt32

    Objective-C

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

    Constants

    • kSecTrustResultInvalid

      kSecTrustResultInvalid

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

      Available in OS X v10.2 and later.

    • kSecTrustResultProceed

      kSecTrustResultProceed

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

      Available in OS X v10.2 and later.

    • kSecTrustResultConfirm

      kSecTrustResultConfirm

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

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • kSecTrustResultDeny

      kSecTrustResultDeny

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

      Available in OS X v10.2 and later.

    • kSecTrustResultUnspecified

      kSecTrustResultUnspecified

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

      Available in OS X v10.2 and later.

    • kSecTrustResultRecoverableTrustFailure

      kSecTrustResultRecoverableTrustFailure

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

      Available in OS X v10.2 and later.

    • kSecTrustResultFatalTrustFailure

      kSecTrustResultFatalTrustFailure

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

      Available in OS X v10.2 and later.

    • kSecTrustResultOtherError

      kSecTrustResultOtherError

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

      Available in OS X v10.2 and later.

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    typealias CSSM_APPLE_TP_ACTION_FLAGS = uint32

    Objective-C

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

    Constants

    • CSSM_TP_ACTION_ALLOW_EXPIRED

      CSSM_TP_ACTION_ALLOW_EXPIRED

      Ignore the expiration date and time for all certificates.

      Available in OS X v10.2 and later.

    • CSSM_TP_ACTION_LEAF_IS_CA

      CSSM_TP_ACTION_LEAF_IS_CA

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

      Available in OS X v10.3 and later.

    • CSSM_TP_ACTION_FETCH_CERT_FROM_NET

      CSSM_TP_ACTION_FETCH_CERT_FROM_NET

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

      Available in OS X v10.3 and later.

    • CSSM_TP_ACTION_ALLOW_EXPIRED_ROOT

      CSSM_TP_ACTION_ALLOW_EXPIRED_ROOT

      Ignore the expiration date and time for root certificates only.

      Available in OS X v10.2 and later.

    Discussion

    See SecTrustSetParameters for more information about actions.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    var kSecImportItemLabel: Unmanaged<CFString>! var kSecImportItemKeyID: Unmanaged<CFString>! var kSecImportItemTrust: Unmanaged<CFString>! var kSecImportItemCertChain: Unmanaged<CFString>! var kSecImportItemIdentity: Unmanaged<CFString>!

    Objective-C

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

    Constants

    • kSecImportItemLabel

      kSecImportItemLabel

      Item label.

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

      Available in OS X v10.6 and later.

    • kSecImportItemKeyID

      kSecImportItemKeyID

      Key ID.

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

      Available in OS X v10.6 and later.

    • kSecImportItemTrust

      kSecImportItemTrust

      Trust management object.

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

      Available in OS X v10.6 and later.

    • kSecImportItemCertChain

      kSecImportItemCertChain

      Certificate list.

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

      Available in OS X v10.6 and later.

    • kSecImportItemIdentity

      kSecImportItemIdentity

      Identity object.

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

      Available in OS X v10.6 and later.

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

    Declaration

    Swift

    let kSecIdentityDomainDefault: CFString! let kSecIdentityDomainKerberosKDC: CFString!

    Objective-C

    const CFStringRef kSecIdentityDomainDefault; const CFStringRef kSecIdentityDomainKerberosKDC;

    Constants

    • kSecIdentityDomainDefault

      kSecIdentityDomainDefault

      The system-wide default identity.

      Available in OS X v10.5 and later.

    • kSecIdentityDomainKerberosKDC

      kSecIdentityDomainKerberosKDC

      Kerberos Key Distribution Center (KDC) identity.

      Available in OS X v10.5 and later.

    Discussion

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

  • The credential type to be returned by SecKeyGetCredentials.

    Declaration

    Swift

    typealias SecCredentialType = uint32

    Objective-C

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

    Constants

    • kSecCredentialTypeDefault

      kSecCredentialTypeDefault

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

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

      Available in OS X v10.5 and later.

    • kSecCredentialTypeWithUI

      kSecCredentialTypeWithUI

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

      Available in OS X v10.5 and later.

    • kSecCredentialTypeNoUI

      kSecCredentialTypeNoUI

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

      Available in OS X v10.5 and later.

    Discussion

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

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.5 and later.

  • The trust settings domains used by the trust settings API.

    Declaration

    Swift

    typealias SecTrustSettingsDomain = uint32

    Objective-C

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

    Constants

    • kSecTrustSettingsDomainUser

      kSecTrustSettingsDomainUser

      Per-user trust settings.

      Available in OS X v10.5 and later.

    • kSecTrustSettingsDomainAdmin

      kSecTrustSettingsDomainAdmin

      Locally administered, system-wide trust settings.

      Administrator privileges are required to make changes to this domain.

      Available in OS X v10.5 and later.

    • kSecTrustSettingsDomainSystem

      kSecTrustSettingsDomainSystem

      System trust settings.

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

      Available in OS X v10.5 and later.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.5 and later.

  • Allowed uses for the encryption key in a certificate.

    Declaration

    Swift

    typealias SecTrustSettingsKeyUsage = uint32

    Objective-C

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

    Constants

    • kSecTrustSettingsKeyUseSignature

      kSecTrustSettingsKeyUseSignature

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

      Available in OS X v10.5 and later.

    • kSecTrustSettingsKeyUseEnDecryptData

      kSecTrustSettingsKeyUseEnDecryptData

      The key can be used to encrypt or decrypt data.

      Available in OS X v10.5 and later.

    • kSecTrustSettingsKeyUseEnDecryptKey

      kSecTrustSettingsKeyUseEnDecryptKey

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

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

      Available in OS X v10.5 and later.

    • kSecTrustSettingsKeyUseSignCert

      kSecTrustSettingsKeyUseSignCert

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

      Available in OS X v10.5 and later.

    • kSecTrustSettingsKeyUseSignRevocation

      kSecTrustSettingsKeyUseSignRevocation

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

      OCSP messages and CRLs are used to revoke certificates.

      Available in OS X v10.5 and later.

    • kSecTrustSettingsKeyUseKeyExchange

      kSecTrustSettingsKeyUseKeyExchange

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

      Available in OS X v10.5 and later.

    • kSecTrustSettingsKeyUseAny

      kSecTrustSettingsKeyUseAny

      The key can be used for any purpose.

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

      Available in OS X v10.5 and later.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.5 and later.

  • The keys in one usage constraints dictionary.

    Declaration

    Objective-C

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

    Constants

    • kSecTrustSettingsPolicy

      kSecTrustSettingsPolicy

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

      Available in OS X v10.5 and later.

    • kSecTrustSettingsApplication

      kSecTrustSettingsApplication

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

      Available in OS X v10.5 and later.

    • kSecTrustSettingsPolicyString

      kSecTrustSettingsPolicyString

      ACFString containing policy-specific data.

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

      Available in OS X v10.5 and later.

    • kSecTrustSettingsKeyUsage

      kSecTrustSettingsKeyUsage

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

      Available in OS X v10.5 and later.

    • kSecTrustSettingsAllowedError

      kSecTrustSettingsAllowedError

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

      Available in OS X v10.5 and later.

    • kSecTrustSettingsResult

      kSecTrustSettingsResult

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

      Available in OS X v10.5 and later.

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

    Declaration

    Swift

    typealias SecTrustSettingsResult = uint32

    Objective-C

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

    Constants

    • kSecTrustSettingsResultInvalid

      kSecTrustSettingsResultInvalid

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

      Available in OS X v10.5 and later.

    • kSecTrustSettingsResultTrustRoot

      kSecTrustSettingsResultTrustRoot

      This root certificate is explicitly trusted.

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

      Available in OS X v10.5 and later.

    • kSecTrustSettingsResultTrustAsRoot

      kSecTrustSettingsResultTrustAsRoot

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

      Available in OS X v10.5 and later.

    • kSecTrustSettingsResultDeny

      kSecTrustSettingsResultDeny

      This certificate is explicitly distrusted.

      Available in OS X v10.5 and later.

    • kSecTrustSettingsResultUnspecified

      kSecTrustSettingsResultUnspecified

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

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

      Available in OS X v10.5 and later.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Objective-C

    #define kSecTrustSettingsDefaultRootCertSetting ((SecCertificateRef)-1)

    Constants

    • kSecTrustSettingsDefaultRootCertSetting

      kSecTrustSettingsDefaultRootCertSetting

      Default trust settings for root certificates.

      Available in OS X v10.5 and later.

    Discussion

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

  • Keys in dictionary entries returned by SecCertificateCopyValues.

    Declaration

    Swift

    var kSecPropertyKeyType: Unmanaged<CFString>! var kSecPropertyKeyLabel: Unmanaged<CFString>! var kSecPropertyKeyLocalizedLabel: Unmanaged<CFString>! var kSecPropertyKeyValue: Unmanaged<CFString>!

    Objective-C

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

    Constants

    • kSecPropertyKeyType

      kSecPropertyKeyType

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

      Available in OS X v10.7 and later.

    • kSecPropertyKeyLabel

      kSecPropertyKeyLabel

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

      Available in OS X v10.7 and later.

    • kSecPropertyKeyLocalizedLabel

      kSecPropertyKeyLocalizedLabel

      A localized label of the entry.

      Available in OS X v10.7 and later.

    • kSecPropertyKeyValue

      kSecPropertyKeyValue

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

      Available in OS X v10.7 and later.

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

    Declaration

    Swift

    var kSecPropertyTypeWarning: Unmanaged<CFString>! var kSecPropertyTypeSuccess: Unmanaged<CFString>! var kSecPropertyTypeSection: Unmanaged<CFString>! var kSecPropertyTypeData: Unmanaged<CFString>! var kSecPropertyTypeString: Unmanaged<CFString>! var kSecPropertyTypeURL: Unmanaged<CFString>! var kSecPropertyTypeDate: Unmanaged<CFString>! var kSecPropertyTypeTitle: Unmanaged<AnyObject>! var kSecPropertyTypeError: Unmanaged<AnyObject>!

    Objective-C

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

    Constants

    • kSecPropertyTypeWarning

      kSecPropertyTypeWarning

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

      Available in OS X v10.7 and later.

    • kSecPropertyTypeSuccess

      kSecPropertyTypeSuccess

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

      Available in OS X v10.7 and later.

    • kSecPropertyTypeSection

      kSecPropertyTypeSection

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

      Available in OS X v10.7 and later.

    • kSecPropertyTypeData

      kSecPropertyTypeData

      Specifies a key whose value is a CFDataRef object.

      Available in OS X v10.7 and later.

    • kSecPropertyTypeString

      kSecPropertyTypeString

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

      Available in OS X v10.7 and later.

    • kSecPropertyTypeURL

      kSecPropertyTypeURL

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

      Available in OS X v10.7 and later.

    • kSecPropertyTypeDate

      kSecPropertyTypeDate

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

      Available in OS X v10.7 and later.

    • kSecPropertyTypeTitle

      kSecPropertyTypeTitle

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

      Available in OS X v10.7 and later.

    • kSecPropertyTypeError

      kSecPropertyTypeError

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

      Available in OS X v10.7 and later.

  • Constants that represent allowed certificate use.

    Declaration

    Swift

    let kSecCertificateUsageSigning: CFString! let kSecCertificateUsageSigningAndEncrypting: CFString! let kSecCertificateUsageDeriveAndSign: CFString!

    Objective-C

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

    Constants

    • kSecCertificateUsageSigning

      kSecCertificateUsageSigning

      The certificate can be used for signing.

      Available in OS X v10.7 and later.

    • kSecCertificateUsageSigningAndEncrypting

      kSecCertificateUsageSigningAndEncrypting

      The certificate can be used for signing and encrypting.

      Available in OS X v10.7 and later.

    • kSecCertificateUsageDeriveAndSign

      kSecCertificateUsageDeriveAndSign

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

      Available in OS X v10.7 and later.

  • Declaration

    Swift

    var kSecPolicyOid: Unmanaged<AnyObject>! var kSecPolicyName: Unmanaged<AnyObject>! var kSecPolicyClient: Unmanaged<AnyObject>! var kSecPolicyKU_DigitalSignature: Unmanaged<AnyObject>! var kSecPolicyKU_NonRepudiation: Unmanaged<AnyObject>! var kSecPolicyKU_KeyEncipherment: Unmanaged<AnyObject>! var kSecPolicyKU_DataEncipherment: Unmanaged<AnyObject>! var kSecPolicyKU_KeyAgreement: Unmanaged<AnyObject>! var kSecPolicyKU_KeyCertSign: Unmanaged<AnyObject>! var kSecPolicyKU_CRLSign: Unmanaged<AnyObject>! var kSecPolicyKU_EncipherOnly: Unmanaged<AnyObject>! var kSecPolicyKU_DecipherOnly: Unmanaged<AnyObject>!

    Objective-C

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

    Constants

    • kSecPolicyOid

      kSecPolicyOid

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

      Available in OS X v10.7 and later.

    • kSecPolicyName

      kSecPolicyName

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

      Available in OS X v10.7 and later.

    • kSecPolicyClient

      kSecPolicyClient

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

      Available in OS X v10.7 and later.

    • kSecPolicyKU_DigitalSignature

      kSecPolicyKU_DigitalSignature

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

      Available in OS X v10.7 and later.

    • kSecPolicyKU_NonRepudiation

      kSecPolicyKU_NonRepudiation

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

      Available in OS X v10.7 and later.

    • kSecPolicyKU_KeyEncipherment

      kSecPolicyKU_KeyEncipherment

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

      Available in OS X v10.7 and later.

    • kSecPolicyKU_DataEncipherment

      kSecPolicyKU_DataEncipherment

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

      Available in OS X v10.7 and later.

    • kSecPolicyKU_KeyAgreement

      kSecPolicyKU_KeyAgreement

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

      Available in OS X v10.7 and later.

    • kSecPolicyKU_KeyCertSign

      kSecPolicyKU_KeyCertSign

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

      Available in OS X v10.7 and later.

    • kSecPolicyKU_CRLSign

      kSecPolicyKU_CRLSign

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

      Available in OS X v10.7 and later.

    • kSecPolicyKU_EncipherOnly

      kSecPolicyKU_EncipherOnly

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

      Available in OS X v10.7 and later.

    • kSecPolicyKU_DecipherOnly

      kSecPolicyKU_DecipherOnly

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

      Available in OS X v10.7 and later.

  • Trust option flags used for SecTrustSetOptions.

    Declaration

    Swift

    typealias SecTrustOptionFlags = UInt32

    Objective-C

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

    Constants

    • kSecTrustOptionAllowExpired

      kSecTrustOptionAllowExpired

      Allow expired certificates (except for the root certificate).

      Available in OS X v10.7 and later.

    • kSecTrustOptionLeafIsCA

      kSecTrustOptionLeafIsCA

      Allow CA certificates as leaf certificates.

      Available in OS X v10.7 and later.

    • kSecTrustOptionFetchIssuerFromNet

      kSecTrustOptionFetchIssuerFromNet

      Allow network downloads of CA certificates.

      Available in OS X v10.7 and later.

    • kSecTrustOptionAllowExpiredRoot

      kSecTrustOptionAllowExpiredRoot

      Allow expired root certificates.

      Available in OS X v10.7 and later.

    • kSecTrustOptionRequireRevPerCert

      kSecTrustOptionRequireRevPerCert

      Require a positive revocation check for each certificate.

      Available in OS X v10.7 and later.

    • kSecTrustOptionImplicitAnchors

      kSecTrustOptionImplicitAnchors

      Treat properly self-signed certificates as anchors implicitly.

      Available in OS X v10.7 and later.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

  • Supported sizes for keys of various common types.

    Declaration

    Swift

    typealias SecKeySizes = UInt32

    Objective-C

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

    Constants

    • kSecDefaultKeySize

      kSecDefaultKeySize

      The default key size for the specified type.

      Available in OS X v10.7 and later.

    • kSec3DES192

      kSec3DES192

      192-bit DES.

      Available in OS X v10.7 and later.

    • kSecAES128

      kSecAES128

      128-bit AES.

      Available in OS X v10.7 and later.

    • kSecAES192

      kSecAES192

      192-bit AES.

      Available in OS X v10.7 and later.

    • kSecAES256

      kSecAES256

      256-bit AES.

      Available in OS X v10.7 and later.

    • kSecp192r1

      kSecp192r1

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

      Available in OS X v10.7 and later.

    • kSecp256r1

      kSecp256r1

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

      Available in OS X v10.7 and later.

    • kSecp384r1

      kSecp384r1

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

      Available in OS X v10.7 and later.

    • kSecp521r1

      kSecp521r1

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

      Available in OS X v10.7 and later.

    • kSecRSAMin

      kSecRSAMin

      1024 bits is the minimum size for an RSA key.

      Available in OS X v10.7 and later.

    • kSecRSAMax

      kSecRSAMax

      4096 bits is the maximum size for an RSA key.

      Available in OS X v10.7 and later.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.7 and later.

  • Special OIDs that cause a certificate to be evaluated based on security policies specific to a given type of certificate.

    Declaration

    Swift

    var kSecPolicyAppleX509Basic: Unmanaged<AnyObject>! var kSecPolicyAppleSSL: Unmanaged<AnyObject>! var kSecPolicyAppleSMIME: Unmanaged<AnyObject>! var kSecPolicyAppleEAP: Unmanaged<AnyObject>! var kSecPolicyAppleIPsec: Unmanaged<AnyObject>! var kSecPolicyApplePKINITClient: Unmanaged<AnyObject>! var kSecPolicyApplePKINITServer: Unmanaged<AnyObject>! var kSecPolicyAppleCodeSigning: Unmanaged<AnyObject>! var kSecPolicyMacAppStoreReceipt: Unmanaged<AnyObject>! var kSecPolicyAppleIDValidation: Unmanaged<AnyObject>! var kSecPolicyAppleTimeStamping: Unmanaged<AnyObject>!

    Objective-C

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

    Constants

    • kSecPolicyAppleX509Basic

      kSecPolicyAppleX509Basic

      Basic X509-style certificate evaluation.

      Available in OS X v10.7 and later.

    • kSecPolicyAppleSSL

      kSecPolicyAppleSSL

      Basic X509 plus host name verification per RFC 2818.

      Available in OS X v10.7 and later.

    • kSecPolicyAppleSMIME

      kSecPolicyAppleSMIME

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

      Available in OS X v10.7 and later.

    • kSecPolicyAppleEAP

      kSecPolicyAppleEAP

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

      Available in OS X v10.7 and later.

    • kSecPolicyAppleIPsec

      kSecPolicyAppleIPsec

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

      Available in OS X v10.7 and later.

    • kSecPolicyAppleiChat

      kSecPolicyAppleiChat

      Policy for use in iChat.

      Available in OS X v10.7 and later.

      Deprecated in OS X v10.9.

    • kSecPolicyApplePKINITClient

      kSecPolicyApplePKINITClient

      Kerberos Pkinit client certificate validation.

      Available in OS X v10.7 and later.

    • kSecPolicyApplePKINITServer

      kSecPolicyApplePKINITServer

      Kerberos Pkinit server certificate validation.

      Available in OS X v10.7 and later.

    • kSecPolicyAppleCodeSigning

      kSecPolicyAppleCodeSigning

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

      Available in OS X v10.7 and later.

    • kSecPolicyMacAppStoreReceipt

      kSecPolicyMacAppStoreReceipt

      Policy for use in evaluating Mac App Store receipts.

      Available in OS X v10.7 and later.

    • kSecPolicyAppleIDValidation

      kSecPolicyAppleIDValidation

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

      Available in OS X v10.7 and later.

    • kSecPolicyAppleTimeStamping

      kSecPolicyAppleTimeStamping

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

      Available in OS X v10.8 and later.

Result Codes

The most common result codes returned by Certificate, Key, and Trust Services are listed in the table below. The assigned error space is discontinuous: –25240..–25279 and –25290..–25329.

  • No error.

    Value

    0

    Description

    No error.

    Available in OS X v10.6 and later.

  • The function or operation is not implemented.

    Value

    -4

    Description

    The function or operation is not implemented.

    Available in OS X v10.6 and later.

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

    Value

    -50

    Description

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

    Available in OS X v10.6 and later.

  • Failed to allocate memory.

    Value

    -108

    Description

    Failed to allocate memory.

    Available in OS X v10.6 and later.

  • No keychain is available.

    Value

    –25291

    Description

    No keychain is available.

    Available in OS X v10.2 and later.

  • A read-only error occurred.

    Value

    –25292

    Description

    A read-only error occurred.

    Available in OS X v10.2 and later.

  • Authorization or authentication failed.

    Value

    –25293

    Description

    Authorization or authentication failed.

    Available in OS X v10.2 and later.

  • The keychain does not exist.

    Value

    –25294

    Description

    The keychain does not exist.

    Available in OS X v10.2 and later.

  • The keychain is not valid.

    Value

    –25295

    Description

    The keychain is not valid.

    Available in OS X v10.2 and later.

  • A keychain with the same name already exists.

    Value

    –25296

    Description

    A keychain with the same name already exists.

    Available in OS X v10.2 and later.

  • An item with the same primary key attributes already exists.

    Value

    –25299

    Description

    An item with the same primary key attributes already exists.

    Available in OS X v10.2 and later.

  • The item cannot be found.

    Value

    –25300

    Description

    The item cannot be found.

    Available in OS X v10.2 and later.

  • The buffer is too small.

    Value

    –25301

    Description

    The buffer is too small.

    Available in OS X v10.2 and later.

  • The data is too large for the particular data type.

    Value

    –25302

    Description

    The data is too large for the particular data type.

    Available in OS X v10.2 and later.

  • The attribute does not exist.

    Value

    –25303

    Description

    The attribute does not exist.

    Available in OS X v10.2 and later.

  • The item object is invalid.

    Value

    –25304

    Description

    The item object is invalid.

    Available in OS X v10.2 and later.

  • The search object is invalid.

    Value

    –25305

    Description

    The search object is invalid.

    Available in OS X v10.2 and later.

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

    Value

    –25306

    Description

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

    Available in OS X v10.2 and later.

  • A default keychain does not exist.

    Value

    –25307

    Description

    A default keychain does not exist.

    Available in OS X v10.2 and later.

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

    Value

    –25308

    Description

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

    Available in OS X v10.2 and later.

  • The attribute is read-only.

    Value

    –25309

    Description

    The attribute is read-only.

    Available in OS X v10.2 and later.

  • The version is incorrect.

    Value

    –25310

    Description

    The version is incorrect.

    Available in OS X v10.2 and later.

  • The key size is not allowed.

    Value

    –25311

    Description

    The key size is not allowed.

    Available in OS X v10.2 and later.

  • No storage module is available.

    Value

    –25312

    Description

    No storage module is available.

    Available in OS X v10.2 and later.

  • No certificate module is available.

    Value

    –25313

    Description

    No certificate module is available.

    Available in OS X v10.2 and later.

  • No policy module is available.

    Value

    –25314

    Description

    No policy module is available.

    Available in OS X v10.2 and later.

  • Value

    –25315

    Description

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

    Available in OS X v10.2 and later.

  • The data is not available.

    Value

    –25316

    Description

    The data is not available.

    Available in OS X v10.2 and later.

  • The data is not modifiable.

    Value

    –25317

    Description

    The data is not modifiable.

    Available in OS X v10.2 and later.

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

    Value

    –25318

    Description

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

    Available in OS X v10.2 and later.

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

    Value

    –25319

    Description

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

    Available in OS X v10.3 and later.

  • The access control list is not in standard simple form.

    Value

    –25240

    Description

    The access control list is not in standard simple form.

    Available in OS X v10.2 and later.

  • The policy specified cannot be found.

    Value

    –25241

    Description

    The policy specified cannot be found.

    Available in OS X v10.2 and later.

  • The trust setting is invalid.

    Value

    –25242

    Description

    The trust setting is invalid.

    Available in OS X v10.2 and later.

  • The specified item has no access control.

    Value

    –25243

    Description

    The specified item has no access control.

    Available in OS X v10.2 and later.

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

    Value

    –25244

    Description

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

    Available in OS X v10.2 and later.

  • No trust results are available.

    Value

    –25245

    Description

    No trust results are available.

    Available in OS X v10.3 and later.

  • Unable to decode the provided data.

    Value

    -26275

    Description

    Unable to decode the provided data.

    Available in OS X v10.6 and later.