X-Git-Url: https://git.saurik.com/apple/security.git/blobdiff_plain/72a12576750f52947eb043106ba5c12c0d07decf..b1ab9ed8d0e0f1c3b66d7daa8fd5564444c56195:/libsecurity_keychain/lib/SecTrust.h diff --git a/libsecurity_keychain/lib/SecTrust.h b/libsecurity_keychain/lib/SecTrust.h new file mode 100644 index 00000000..82243de0 --- /dev/null +++ b/libsecurity_keychain/lib/SecTrust.h @@ -0,0 +1,489 @@ +/* + * Copyright (c) 2002-2010 Apple Inc. All Rights Reserved. + * + * @APPLE_LICENSE_HEADER_START@ + * + * This file contains Original Code and/or Modifications of Original Code + * as defined in and that are subject to the Apple Public Source License + * Version 2.0 (the 'License'). You may not use this file except in + * compliance with the License. Please obtain a copy of the License at + * http://www.opensource.apple.com/apsl/ and read it before using this + * file. + * + * The Original Code and all software distributed under the License are + * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER + * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, + * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. + * Please see the License for the specific language governing rights and + * limitations under the License. + * + * @APPLE_LICENSE_HEADER_END@ + */ + +/*! + @header SecTrust + The functions and data types in SecTrust implement trust computation + and allow the caller to apply trust decisions to the evaluation. +*/ + +#ifndef _SECURITY_SECTRUST_H_ +#define _SECURITY_SECTRUST_H_ + +#include +#include +#include +#include +#include + + +#if defined(__cplusplus) +extern "C" { +#endif + +/*! + @typedef SecTrustResultType + @abstract Specifies the trust result type. + @constant kSecTrustResultInvalid Indicates an invalid setting or result. + @constant kSecTrustResultProceed Indicates you may proceed. This value + may be returned by the SecTrustEvaluate function or stored as part of + the user trust settings. + @constant kSecTrustResultConfirm Indicates confirmation with the user + is required before proceeding. This value may be returned by the + SecTrustEvaluate function or stored as part of the user trust settings. + @constant kSecTrustResultDeny Indicates a user-configured deny; do not + proceed. This value may be returned by the SecTrustEvaluate function + or stored as part of the user trust settings. + @constant kSecTrustResultUnspecified Indicates user intent is unknown. + This value may be returned by the SecTrustEvaluate function or stored + as part of the user trust settings. + @constant kSecTrustResultRecoverableTrustFailure Indicates a trust + framework failure; retry after fixing inputs. This value may be returned + by the SecTrustEvaluate function but not stored as part of the user + trust settings. + @constant kSecTrustResultFatalTrustFailure Indicates a trust framework + failure; no "easy" fix. This value may be returned by the + SecTrustEvaluate function but not stored as part of the user trust + settings. + @constant kSecTrustResultOtherError Indicates a failure other than that + of trust evaluation. This value may be returned by the SecTrustEvaluate + function but not stored as part of the user trust settings. + */ +typedef uint32_t SecTrustResultType; +enum { + kSecTrustResultInvalid, + kSecTrustResultProceed, + kSecTrustResultConfirm, + kSecTrustResultDeny, + kSecTrustResultUnspecified, + kSecTrustResultRecoverableTrustFailure, + kSecTrustResultFatalTrustFailure, + kSecTrustResultOtherError +}; + +/*! + @typedef SecTrustUserSetting + @abstract Specifies user-specified trust settings. +*/ +typedef SecTrustResultType SecTrustUserSetting; + +/*! + @typedef SecTrustOptionFlags + @abstract Options for customizing trust evaluation. + @constant kSecTrustOptionAllowExpired Allow expired certs. + @constant kSecTrustOptionLeafIsCA Allow CA as leaf certificate. + @constant kSecTrustOptionFetchIssuerFromNet Allow network fetch of CA cert. + @constant kSecTrustOptionAllowExpiredRoot Allow expired roots. + @constant kSecTrustOptionRequireRevPerCert Require positive revocation + check per certificate. + @constant kSecTrustOptionUseTrustSettings Use TrustSettings instead of + anchors. + @constant kSecTrustOptionImplicitAnchors Properly self-signed certs are + treated as anchors implicitly. + */ +typedef uint32_t SecTrustOptionFlags; +enum { + kSecTrustOptionAllowExpired = 0x00000001, + kSecTrustOptionLeafIsCA = 0x00000002, + kSecTrustOptionFetchIssuerFromNet = 0x00000004, + kSecTrustOptionAllowExpiredRoot = 0x00000008, + kSecTrustOptionRequireRevPerCert = 0x00000010, + kSecTrustOptionUseTrustSettings = 0x00000020, + kSecTrustOptionImplicitAnchors = 0x00000040 +}; + +/*! + @enum Trust Property Constants + @discussion Predefined property key constants used to obtain values in + a dictionary of trust evaluation results. + @constant kSecPropertyTypeTitle Specifies a key whose value is a + CFStringRef containing the title (display name) of this certificate. + @constant kSecPropertyTypeError Specifies a key whose value is a + CFStringRef containing the reason for a trust evaluation failure. +*/ +extern CFTypeRef kSecPropertyTypeTitle + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); +extern CFTypeRef kSecPropertyTypeError + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); + + +/*! + @typedef SecTrustRef + @abstract A pointer to an opaque trust management structure. +*/ +typedef struct OpaqueSecTrustRef *SecTrustRef; + +#ifdef __BLOCKS__ +/*! + @typedef SecTrustCallback + @abstract Delivers the result from an asynchronous trust evaluation. + @param trustRef A reference to the trust object which has been evaluated. + @param trustResult The trust result of the evaluation. Additional status + information can be obtained by calling SecTrustCopyProperties(). +*/ +typedef void (^SecTrustCallback)(SecTrustRef trustRef, SecTrustResultType trustResult); +#endif + +/*! + @function SecTrustGetTypeID + @abstract Returns the type identifier of SecTrust instances. + @result The CFTypeID of SecTrust instances. +*/ +CFTypeID SecTrustGetTypeID(void) + __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0); + +/*! + @function SecTrustCreateWithCertificates + @abstract Creates a trust object based on the given certificates and + policies. + @param certificates The group of certificates to verify. + @param policies An array of one or more policies. You may pass a + SecPolicyRef to represent a single policy. + @param trustRef On return, a pointer to the trust management reference. + @result A result code. See "Security Error Codes" (SecBase.h). + @discussion If multiple policies are passed in, all policies must verify + for the chain to be considered valid. +*/ +OSStatus SecTrustCreateWithCertificates(CFArrayRef certificates, + CFTypeRef policies, SecTrustRef *trustRef) + __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0); + + +/*! + @function SecTrustSetPolicies + @abstract Set (replace) the set of policies to evaluate. + @param trust The reference to the trust to change. + @param policies An array of one or more policies. You may pass a + SecPolicyRef to represent a single policy. + @result A result code. See "Security Error Codes" (SecBase.h). +*/ +OSStatus SecTrustSetPolicies(SecTrustRef trust, CFTypeRef policies) + __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_NA); + +/*! + @function SecTrustSetOptions + @abstract Sets optional flags and data for customizing a trust evaluation. + @param trustRef The reference to the trust to change. + @param options Flags to change evaluation behavior for this trust. + @result A result code. See "Security Error Codes" (SecBase.h). + */ +OSStatus SecTrustSetOptions(SecTrustRef trustRef, SecTrustOptionFlags options) + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); + +/*! + @function SecTrustSetParameters + @abstract Sets the action and action data for a trust object. + @param trustRef The reference to the trust to change. + @param action A trust action. + @param actionData A reference to data associated with this action. + @result A result code. See "Security Error Codes" (SecBase.h). + @discussion This function is deprecated in Mac OS X 10.7 and later; + use SecTrustSetOptions instead. + */ +OSStatus SecTrustSetParameters(SecTrustRef trustRef, + CSSM_TP_ACTION action, CFDataRef actionData) + DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER; + +/*! + @function SecTrustSetAnchorCertificates + @abstract Sets the anchor certificates for a given trust. + @param trust A reference to a trust object. + @param anchorCertificates An array of anchor certificates. + @result A result code. See "Security Error Codes" (SecBase.h). + @discussion Calling this function without also calling + SecTrustSetAnchorCertificatesOnly() will disable trusting any + anchors other than the ones in anchorCertificates. +*/ +OSStatus SecTrustSetAnchorCertificates(SecTrustRef trust, + CFArrayRef anchorCertificates) + __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0); + +/*! + @function SecTrustSetAnchorCertificatesOnly + @abstract Reenables trusting anchor certificates in addition to those + passed in via the SecTrustSetAnchorCertificates API. + @param trust A reference to a trust object. + @param anchorCertificatesOnly If true, disables trusting any anchors other + than the ones passed in via SecTrustSetAnchorCertificates(). If false, + the built in anchor certificates are also trusted. + @result A result code. See "Security Error Codes" (SecBase.h). +*/ +OSStatus SecTrustSetAnchorCertificatesOnly(SecTrustRef trust, + Boolean anchorCertificatesOnly) + __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0); + +/*! + @function SecTrustSetKeychains + @abstract Sets the keychains for a given trust object. + @param trust A reference to a trust object. + @param keychainOrArray A reference to an array of keychains to search, a + single keychain, or NULL to use the default keychain search list. + @result A result code. See "Security Error Codes" (SecBase.h). + @discussion By default, the user's keychain search list and the system + anchors keychain are searched for certificates to complete the chain. You + can specify a zero-element array if you do not want any keychains searched. +*/ +OSStatus SecTrustSetKeychains(SecTrustRef trust, CFTypeRef keychainOrArray) + __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_NA); + +/*! + @function SecTrustSetVerifyDate + @abstract Set the date for which the trust should be verified. + @param trust A reference to a trust object. + @param verifyDate The date for which to verify trust. + @result A result code. See "Security Error Codes" (SecBase.h). + @discussion This function lets you evaluate certificate validity for a + given date (for example, to determine if a signature was valid on the date + it was signed, even if the certificate has since expired.) If this function + is not called, the time at which SecTrustEvaluate() is called is used + implicitly as the verification time. +*/ +OSStatus SecTrustSetVerifyDate(SecTrustRef trust, CFDateRef verifyDate) + __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0); + +/*! + @function SecTrustGetVerifyTime + @abstract Returns the verify time. + @param trust A reference to the trust object being verified. + @result A CFAbsoluteTime value representing the time at which certificates + should be checked for validity. + @discussion This function retrieves the verification time for the given + trust reference, as set by a prior call to SecTrustSetVerifyDate(). If the + verification time has not been set, this function returns a value of 0, + indicating that the current date/time is implicitly used for verification. +*/ +CFAbsoluteTime SecTrustGetVerifyTime(SecTrustRef trust) + __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0); + +/*! + @function SecTrustEvaluate + @abstract Evaluates a trust reference synchronously. + @param trust A reference to the trust object to evaluate. + @param result A pointer to a result type. + @result A result code. See "Security Error Codes" (SecBase.h). + @discussion This function will completely evaluate trust before returning, + possibly including network access to fetch intermediate certificates or to + perform revocation checking. Since this function can block during those + operations, you should call it from within a function that is placed on a + dispatch queue, or in a separate thread from your application's main + run loop. Alternatively, you can use the SecTrustEvaluateAsync() function + in Mac OS X 10.7 and later. +*/ +OSStatus SecTrustEvaluate(SecTrustRef trust, SecTrustResultType *result) + __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0); + +#ifdef __BLOCKS__ +/*! + @function SecTrustEvaluateAsync + @abstract Evaluates a trust reference asynchronously. + @param trust A reference to the trust object to evaluate. + @param queue A dispatch queue on which the result callback should be + executed. Pass NULL to use the current dispatch queue. + @param result A SecTrustCallback block which will be executed when the + trust evaluation is complete. + @result A result code. See "Security Error Codes" (SecBase.h). +*/ +OSStatus SecTrustEvaluateAsync(SecTrustRef trust, + dispatch_queue_t queue, SecTrustCallback result) + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); +#endif + +/*! + @function SecTrustGetResult + @abstract Returns detailed information on the outcome of an evaluation. + @param trustRef A reference to a trust object. + @param result A pointer to the result from the call to SecTrustEvaluate. + @param certChain On return, a pointer to the certificate chain used to + validate the input certificate. Call the CFRelease function to release + this pointer. + @param statusChain On return, a pointer to the status of the certificate + chain. Do not attempt to free this pointer; it remains valid until the + trust is destroyed or the next call to SecTrustEvaluate. + @result A result code. See "Security Error Codes" (SecBase.h). + @discussion This function is deprecated in Mac OS X 10.7 and later. + To get the complete certificate chain, use SecTrustGetCertificateCount and + SecTrustGetCertificateAtIndex. To get detailed status information for each + certificate, use SecTrustCopyProperties. To get the overall trust result + for the evaluation, use SecTrustGetTrustResult. +*/ +OSStatus SecTrustGetResult(SecTrustRef trustRef, SecTrustResultType *result, + CFArrayRef *certChain, CSSM_TP_APPLE_EVIDENCE_INFO **statusChain) + DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER; + +/*! + @function SecTrustGetCssmResult + @abstract Gets the CSSM trust result. + @param trust A reference to a trust. + @param result On return, a pointer to the CSSM trust result. + @result A result code. See "Security Error Codes" (SecBase.h). + @discussion This function is deprecated in Mac OS X 10.7 and later. + To get detailed status information for each certificate, use + SecTrustCopyProperties. To get the overall trust result for the evaluation, + use SecTrustGetTrustResult. +*/ +OSStatus SecTrustGetCssmResult(SecTrustRef trust, + CSSM_TP_VERIFY_CONTEXT_RESULT_PTR *result) + DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER; + +/*! + @function SecTrustGetCssmResultCode + @abstract Gets the result code from the most recent call to SecTrustEvaluate + for the specified trust. + @param trust A reference to a trust. + @param resultCode On return, the result code produced by the most recent + evaluation of the given trust (cssmerr.h). The value of resultCode is + undefined if SecTrustEvaluate has not been called. + @result A result code. See "Security Error Codes" (SecBase.h). Returns + errSecTrustNotAvailable if SecTrustEvaluate has not been called for the + specified trust. + @discussion This function is deprecated in Mac OS X 10.7 and later. + To get detailed status information for each certificate, use + SecTrustCopyProperties. To get the overall trust result for the evaluation, + use SecTrustGetTrustResult. +*/ +OSStatus SecTrustGetCssmResultCode(SecTrustRef trust, OSStatus *resultCode) + DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER; + +/*! + @function SecTrustGetTrustResult + @param trustRef A reference to a trust object. + @param result A pointer to the result from the most recent call to + SecTrustEvaluate for this trust reference. If SecTrustEvaluate has not been + called, the result is kSecTrustResultInvalid. + @result A result code. See "Security Error Codes" (SecBase.h). + @discussion This function replaces SecTrustGetResult for the purpose of + obtaining the current evaluation result of a given trust reference. +*/ +OSStatus SecTrustGetTrustResult(SecTrustRef trustRef, + SecTrustResultType *result) + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); + +/*! + @function SecTrustGetTPHandle + @abstract Gets the CSSM trust handle + @param trust A reference to a trust. + @param handle On return, a CSSM trust handle. + @result A result code. See "Security Error Codes" (SecBase.h). + @discussion This function is deprecated in Mac OS X 10.7 and later. +*/ +OSStatus SecTrustGetTPHandle(SecTrustRef trust, CSSM_TP_HANDLE *handle) + DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER; + +/*! + @function SecTrustCopyPolicies + @abstract Returns an array of policies used by a given trust. + @param trust A reference to a trust object. + @param policies On return, an array of policies used by this trust. + Call the CFRelease function to release this reference. + @result A result code. See "Security Error Codes" (SecBase.h). +*/ +OSStatus SecTrustCopyPolicies(SecTrustRef trust, CFArrayRef *policies) + __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_NA); + +/*! + @function SecTrustCopyCustomAnchorCertificates + @abstract Returns an array of custom anchor certificates used by a given + trust, as set by a prior call to SecTrustSetAnchorCertificates, or NULL if + no custom anchors have been specified. + @param trust A reference to a trust. + @param anchors On return, an array of custom anchor certificates (roots) + used by this trust, or NULL if no custom anchors have been specified. Call + the CFRelease function to release this reference. + @result A result code. See "Security Error Codes" (SecBase.h). +*/ +OSStatus SecTrustCopyCustomAnchorCertificates(SecTrustRef trust, + CFArrayRef *anchors) + __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA); + +/*! + @function SecTrustCopyAnchorCertificates + @abstract Returns an array of default anchor (root) certificates used by + the system. + @param anchors On return, an array containing the system's default anchors + (roots). Call the CFRelease function to release this pointer. + @result A result code. See "Security Error Codes" (SecBase.h). +*/ +OSStatus SecTrustCopyAnchorCertificates(CFArrayRef *anchors) + __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_NA); + +/*! + @function SecTrustCopyPublicKey + @abstract Return the public key for the leaf certificate after trust has + been evaluated. + @param trust A reference to the trust object which has been evaluated. + @result The 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). The caller is responsible + for calling CFRelease on the returned key when it is no longer needed. +*/ +SecKeyRef SecTrustCopyPublicKey(SecTrustRef trust) + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0); + +/*! + @function SecTrustGetCertificateCount + @abstract Returns the number of certificates in an evaluated certificate + chain. + @param trust Reference to a trust object. + @result The number of certificates in the trust chain. This function will + return 1 if the trust has not been evaluated, and the number of + certificates in the chain including the anchor if it has. +*/ +CFIndex SecTrustGetCertificateCount(SecTrustRef trust) + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0); + +/*! + @function SecTrustGetCertificateAtIndex + @abstract Returns a certificate from the trust chain. + @param trust Reference to a trust object. + @param ix The index of the requested certificate. Indices run from 0 + (leaf) to the anchor (or last certificate found if no anchor was found). + The leaf cert (index 0) is always present regardless of whether the trust + reference has been evaluated or not. + @result A SecCertificateRef for the requested certificate. +*/ +SecCertificateRef SecTrustGetCertificateAtIndex(SecTrustRef trust, CFIndex ix) + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0); + +/*! + @function SecTrustCopyProperties + @abstract Return a property array for this trust evaluation. + @param trust A reference to the trust object. If the trust has not been + evaluated, the returned property array will be empty. + @result A property array. It is the caller's responsibility to CFRelease + the returned array when it is no longer needed. + @discussion This function returns an ordered array of CFDictionaryRef + instances for each certificate in the chain. Indices run from 0 (leaf) to + the anchor (or last certificate found if no anchor was found). The property + at index 0 of the array may also include general information about the + entire chain's validity in the context of this trust evaluation. See the + "Trust Property Constants" section for a list of currently defined keys. +*/ +CFArrayRef SecTrustCopyProperties(SecTrustRef trust) + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0); + + +#if defined(__cplusplus) +} +#endif + +#endif /* !_SECURITY_SECTRUST_H_ */