iOS Developer Library — Pre-Release

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

    Swift

    import Security

    Availability

    Available in iOS 2.0 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 and later.

  • 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 and later.

  • 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 and later.

  • 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 and later.

  • 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 and later.

  • Encrypts a block of plaintext.

    Declaration

    Swift

    func SecKeyEncrypt(_ key: SecKey!, _ padding: SecPadding, _ plainText: UnsafePointer<UInt8>, _ plainTextLen: Int, _ cipherText: UnsafeMutablePointer<UInt8>, _ cipherTextLen: UnsafeMutablePointer<Int>) -> OSStatus

    Objective-C

    OSStatus SecKeyEncrypt ( SecKeyRef key, SecPadding padding, const uint8_t *plainText, size_t plainTextLen, uint8_t *cipherText, size_t *cipherTextLen );

    Parameters

    key

    Public key with which to encrypt the data.

    padding

    The type of padding to use. Possible values are listed in Digital Signature Padding Types. Typically, kSecPaddingPKCS1 is used, which adds PKCS1 padding before encryption. If you specify kSecPaddingNone, the data is encrypted as-is.

    plainText

    The data to encrypt.

    plainTextLen

    Length in bytes of the data in the plainText buffer. This must be less than or equal to the value returned by the SecKeyGetBlockSize function. When PKCS1 padding is performed, the maximum length of data that can be encrypted is 11 bytes less than the value returned by the SecKeyGetBlockSize function (secKeyGetBlockSize() - 11).

    cipherText

    On return, the encrypted text.

    cipherTextLen

    On entry, the size of the buffer provided in the cipherText parameter. On return, the amount of data actually placed in the buffer.

    Return Value

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

    Discussion

    The input buffer (plainText) can be the same as the output buffer (cipherText) to reduce the amount of memory used by the function.

    Import Statement

    Swift

    import Security

    Availability

    Available in iOS 2.0 and later.

  • Decrypts a block of ciphertext.

    Declaration

    Swift

    func SecKeyDecrypt(_ key: SecKey!, _ padding: SecPadding, _ cipherText: UnsafePointer<UInt8>, _ cipherTextLen: Int, _ plainText: UnsafeMutablePointer<UInt8>, _ plainTextLen: UnsafeMutablePointer<Int>) -> OSStatus

    Objective-C

    OSStatus SecKeyDecrypt ( SecKeyRef key, SecPadding padding, const uint8_t *cipherText, size_t cipherTextLen, uint8_t *plainText, size_t *plainTextLen );

    Parameters

    key

    private key with which to decrypt the data.

    padding

    The type of padding used. Possible values are listed in Digital Signature Padding Types. Typically, kSecPaddingPKCS1 is used, which removes PKCS1 padding after decryption. If you specify kSecPaddingNone, the decrypted data is returned as-is.

    cipherText

    The data to decrypt.

    cipherTextLen

    Length in bytes of the data in the cipherText buffer. This must be less than or equal to the value returned by the SecKeyGetBlockSize function.

    plainText

    On return, the decrypted text.

    plainTextLen

    On entry, the size of the buffer provided in the plainText parameter. On return, the amount of data actually placed in the buffer.

    Return Value

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

    Discussion

    The input buffer (cipherText) can be the same as the output buffer (plainText) to reduce the amount of memory used by the function.

    Import Statement

    Swift

    import Security

    Availability

    Available in iOS 2.0 and later.

  • Generates a digital signature for a block of data.

    Declaration

    Swift

    func SecKeyRawSign(_ key: SecKey!, _ padding: SecPadding, _ dataToSign: UnsafePointer<UInt8>, _ dataToSignLen: Int, _ sig: UnsafeMutablePointer<UInt8>, _ sigLen: UnsafeMutablePointer<Int>) -> OSStatus

    Objective-C

    OSStatus SecKeyRawSign ( SecKeyRef key, SecPadding padding, const uint8_t *dataToSign, size_t dataToSignLen, uint8_t *sig, size_t *sigLen );

    Parameters

    key

    Private key with which to sign the data.

    padding

    The type of padding to use. Possible values are listed in Digital Signature Padding Types. Use kSecPaddingPKCS1SHA1 if the data to be signed is a SHA1 digest of the actual data. If you specify kSecPaddingNone, the data is signed as-is.

    dataToSign

    The data to be signed. Typically, a digest of the actual data is signed.

    dataToSignLen

    Length in bytes of the data in the dataToSign buffer. When PKCS1 padding is performed, the maximum length of data that can be signed is 11 bytes less than the value returned by the SecKeyGetBlockSize function (secKeyGetBlockSize() - 11).

    sig

    On return, the digital signature.

    sigLen

    On entry, the size of the buffer provided in the sig parameter. On return, the amount of data actually placed in the buffer.

    Return Value

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

    Discussion

    The behavior this function with kSecPaddingNone is undefined if the first byte of the data to sign is 0; there is no way to verify leading zeroes, as they are discarded during the calculation.

    Import Statement

    Swift

    import Security

    Availability

    Available in iOS 2.0 and later.

  • Verifies a digital signature.

    Declaration

    Swift

    func SecKeyRawVerify(_ key: SecKey!, _ padding: SecPadding, _ signedData: UnsafePointer<UInt8>, _ signedDataLen: Int, _ sig: UnsafePointer<UInt8>, _ sigLen: Int) -> OSStatus

    Objective-C

    OSStatus SecKeyRawVerify ( SecKeyRef key, SecPadding padding, const uint8_t *signedData, size_t signedDataLen, const uint8_t *sig, size_t sigLen );

    Parameters

    key

    Public key with which to verify the data.

    padding

    The type of padding used. Possible values are listed in Digital Signature Padding Types. Use kSecPaddingPKCS1SHA1 if you are verifying a PKCS1-style signature with DER encoding of the digest type and the signed data is a SHA1 digest of the actual data. Specify kSecPaddingNone if no padding was used.

    signedData

    The data for which the signature is being verified. Typically, a digest of the actual data is signed.

    signedDataLen

    Length in bytes of the data in the signedData buffer.

    sig

    The digital signature to be verified.

    sigLen

    Length of the data in the sig buffer.

    Return Value

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

    Import Statement

    Swift

    import Security

    Availability

    Available in iOS 2.0 and later.

  • Gets the block length associated with a cryptographic key.

    Declaration

    Swift

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

    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

    Swift

    import Security

    Availability

    Available in iOS 2.0 and later.

  • 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

    Swift

    import Security

    Availability

    Available in iOS 7.0 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 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

    Swift

    import Security

    Availability

    Available in iOS 7.0 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

    Swift

    import Security

    Availability

    Available in iOS 4.0 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 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

    Swift

    import Security

    Availability

    Available in iOS 7.0 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 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

    Swift

    import Security

    Availability

    Available in iOS 7.0 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 and later.

  • 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

    Swift

    import Security

    Availability

    Available in iOS 7.0 and later.

  • 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 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

    Swift

    import Security

    Availability

    Available in iOS 4.0 and later.

  • 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

    Swift

    import Security

    Availability

    Available in iOS 6.0 and later.

  • 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 and later.

Data Types

  • 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 and later.

  • Contains information about a policy.

    Declaration

    Swift

    typealias SecPolicyRef = SecPolicy

    Objective-C

    typedef struct OpaqueSecPolicyRef *SecPolicyRef;

    Import Statement

    Swift

    import Security

    Availability

    Available in iOS 2.0 and later.

  • Contains information about trust management.

    Declaration

    Swift

    typealias SecTrustRef = SecTrust

    Objective-C

    typedef struct __SecTrust *SecTrustRef;

    Import Statement

    Swift

    import Security

    Availability

    Available in iOS 2.0 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

    Swift

    import Security

    Availability

    Available in iOS 7.0 and later.

Constants

  • 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 iOS 2.0 and later.

    • kSecPaddingPKCS1

      kSecPaddingPKCS1

      PKCS1 padding.

      Available in iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 and later.

    Import Statement

    Swift

    import Security

    Availability

    Available in iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 and later.

      Deprecated in iOS 7.0.

    • 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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

    Swift

    import Security

    Availability

    Available in iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 and later.

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

    Declaration

    Swift

    var kSecPropertyTypeTitle: Unmanaged<AnyObject>! var kSecPropertyTypeError: Unmanaged<AnyObject>!

    Objective-C

    extern CFTypeRef kSecPropertyTypeTitle; extern CFTypeRef kSecPropertyTypeError;

    Constants

    • kSecPropertyTypeTitle

      kSecPropertyTypeTitle

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

      Available in iOS 7.0 and later.

    • kSecPropertyTypeError

      kSecPropertyTypeError

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

      Available in iOS 7.0 and later.

  • Policy keys used by SecPolicyCopyProperties and SecPolicySetProperties.

    Declaration

    Swift

    var kSecPolicyOid: Unmanaged<AnyObject>! var kSecPolicyName: Unmanaged<AnyObject>! var kSecPolicyClient: Unmanaged<AnyObject>!

    Objective-C

    extern CFTypeRef kSecPolicyOid extern CFTypeRef kSecPolicyName extern CFTypeRef kSecPolicyClient

    Constants

    • kSecPolicyOid

      kSecPolicyOid

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

      Available in iOS 7.0 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 iOS 7.0 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 iOS 7.0 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 kSecPolicyAppleCodeSigning: 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 kSecPolicyAppleCodeSigning; extern CFTypeRef kSecPolicyAppleIDValidation; extern CFTypeRef kSecPolicyAppleTimeStamping;

    Constants

    • kSecPolicyAppleX509Basic

      kSecPolicyAppleX509Basic

      Basic X509-style certificate evaluation.

      Available in iOS 7.0 and later.

    • kSecPolicyAppleSSL

      kSecPolicyAppleSSL

      Basic X509 plus host name verification per RFC 2818.

      Available in iOS 7.0 and later.

    • kSecPolicyAppleSMIME

      kSecPolicyAppleSMIME

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

      Available in iOS 7.0 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 iOS 7.0 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 iOS 7.0 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 iOS 7.0 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 iOS 7.0 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 iOS 7.0 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 iOS 2.0 and later.

  • The function or operation is not implemented.

    Value

    -4

    Description

    The function or operation is not implemented.

    Available in iOS 2.0 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 iOS 2.0 and later.

  • Failed to allocate memory.

    Value

    -108

    Description

    Failed to allocate memory.

    Available in iOS 2.0 and later.

  • No keychain is available.

    Value

    –25291

    Description

    No keychain is available.

    Available in iOS 2.0 and later.

  • Authorization or authentication failed.

    Value

    –25293

    Description

    Authorization or authentication failed.

    Available in iOS 4.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 iOS 2.0 and later.

  • The item cannot be found.

    Value

    –25300

    Description

    The item cannot be found.

    Available in iOS 2.0 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 iOS 2.0 and later.

  • Unable to decode the provided data.

    Value

    -26275

    Description

    Unable to decode the provided data.

    Available in iOS 2.0 and later.