+++ /dev/null
-/*
- * Copyright (c) 2002-2014 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 <Security/SecBase.h>
-#include <CoreFoundation/CoreFoundation.h>
-#include <AvailabilityMacros.h>
-
-#if defined(__cplusplus)
-extern "C" {
-#endif
-
-/*!
- @typedef SecTrustResultType
- @abstract Specifies the trust result type.
- @discussion SecTrustResultType results have two dimensions. They specify
- both whether evaluation suceeded and whether this is because of a user
- decision. The commonly expected result is kSecTrustResultUnspecified,
- which indicates a positive result that wasn't decided by the user. The
- common failure is kSecTrustResultRecoverableTrustFailure, which means a
- negative result. kSecTrustResultProceed and kSecTrustResultDeny are the
- positive and negative result respectively when decided by the user. User
- decisions are persisted through the use of SecTrustCopyExceptions() and
- SecTrustSetExceptions(). Finally, kSecTrustResultFatalTrustFailure is a
- negative result that must not be circumvented.
- @constant kSecTrustResultInvalid Indicates an invalid setting or result.
- This result usually means that SecTrustEvaluate has not yet been called.
- @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. Important: this value is no longer returned
- or supported by SecTrustEvaluate or the SecTrustSettings API starting in
- OS X 10.5; its use is deprecated in OS X 10.9 and later, as well as in iOS.
- @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 the evaluation succeeded
- and the certificate is implicitly trusted, but user intent was not
- explicitly specified. This value may be returned by the SecTrustEvaluate
- function or stored as part of the user trust settings.
- @constant kSecTrustResultRecoverableTrustFailure Indicates a trust policy
- failure which can be overridden by the user. This value may be returned
- by the SecTrustEvaluate function but not stored as part of the user
- trust settings.
- @constant kSecTrustResultFatalTrustFailure Indicates a trust failure
- which cannot be overridden by the user. 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 = 0,
- kSecTrustResultProceed = 1,
- kSecTrustResultConfirm CF_ENUM_DEPRECATED(10_0, 10_9, NA, NA) = 2,
- kSecTrustResultDeny = 3,
- kSecTrustResultUnspecified = 4,
- kSecTrustResultRecoverableTrustFailure = 5,
- kSecTrustResultFatalTrustFailure = 6,
- kSecTrustResultOtherError = 7
-};
-
-/*!
- @typedef SecTrustRef
- @abstract CFType used for performing X.509 certificate trust evaluations.
- */
-typedef struct __SecTrust *SecTrustRef;
-
-/*!
- @enum Trust Property Constants
- @discussion Predefined key constants used to obtain values in a
- per-certificate dictionary of trust evaluation results,
- as retrieved from a call to SecTrustCopyProperties.
- @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_7_0);
-extern CFTypeRef kSecPropertyTypeError
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
-
-/*!
- @enum Trust Result Constants
- @discussion Predefined key constants used to obtain values in a
- dictionary of trust evaluation results for a certificate chain,
- as retrieved from a call to SecTrustCopyResult.
- @constant kSecTrustEvaluationDate
- This key will be present if a trust evaluation has been performed
- and results are available. Its value is a CFDateRef representing
- when the evaluation for this trust object took place.
- @constant kSecTrustExtendedValidation
- This key will be present and have a value of kCFBooleanTrue
- if this chain was validated for EV.
- @constant kSecTrustOrganizationName
- Organization name field of subject of leaf certificate. This
- field is meant to be displayed to the user as the validated
- name of the company or entity that owns the certificate if the
- kSecTrustExtendedValidation key is present.
- @constant kSecTrustResultValue
- This key will be present if a trust evaluation has been performed.
- Its value is a CFNumberRef representing the SecTrustResultType result
- for the evaluation.
- @constant kSecTrustRevocationChecked
- This key will be present iff this chain had its revocation checked.
- The value will be a kCFBooleanTrue if revocation checking was
- successful and none of the certificates in the chain were revoked.
- The value will be kCFBooleanFalse if no current revocation status
- could be obtained for one or more certificates in the chain due
- to connection problems or timeouts. This is a hint to a client
- to retry revocation checking at a later time.
- @constant kSecTrustRevocationValidUntilDate
- This key will be present iff kSecTrustRevocationChecked has a
- value of kCFBooleanTrue. The value will be a CFDateRef representing
- the earliest date at which the revocation info for one of the
- certificates in this chain might change.
- */
-extern CFTypeRef kSecTrustEvaluationDate
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
-extern CFTypeRef kSecTrustExtendedValidation
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
-extern CFTypeRef kSecTrustOrganizationName
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
-extern CFTypeRef kSecTrustResultValue
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
-extern CFTypeRef kSecTrustRevocationChecked
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
-extern CFTypeRef kSecTrustRevocationValidUntilDate
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
-
-#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 /* __BLOCKS__ */
-
-
-/*!
- @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. This can either
- be a CFArrayRef of SecCertificateRef objects or a single SecCertificateRef
- @param policies An array of one or more policies. You may pass a
- SecPolicyRef to represent a single policy.
- @param trust 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(CFTypeRef certificates,
- CFTypeRef policies, SecTrustRef *trust)
- __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);
-
-/*!
- @function SecTrustSetPolicies
- @abstract Set the policies for which trust should be verified.
- @param trust A trust reference.
- @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).
- @discussion This function will invalidate the existing trust result,
- requiring a fresh evaluation for the newly-set policies.
- */
-OSStatus SecTrustSetPolicies(SecTrustRef trust, CFTypeRef policies)
- __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_6_0);
-
-/*!
- @function SecTrustCopyPolicies
- @abstract Returns an array of policies used for this evaluation.
- @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_7_0);
-
-/*!
- @function SecTrustSetNetworkFetchAllowed
- @abstract Specifies whether a trust evaluation is permitted to fetch missing
- intermediate certificates from the network.
- @param trust A trust reference.
- @param allowFetch If true, and a certificate's issuer is not present in the
- trust reference but its network location is known, the evaluation is permitted
- to attempt to download it automatically. Pass false to disable network fetch
- for this trust evaluation.
- @result A result code. See "Security Error Codes" (SecBase.h).
- @discussion By default, network fetch of missing certificates is enabled if
- the trust evaluation includes the SSL policy, otherwise it is disabled.
- */
-OSStatus SecTrustSetNetworkFetchAllowed(SecTrustRef trust,
- Boolean allowFetch)
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
-
-/*!
- @function SecTrustGetNetworkFetchAllowed
- @abstract Returns whether a trust evaluation is permitted to fetch missing
- intermediate certificates from the network.
- @param trust A trust reference.
- @param allowFetch On return, the boolean pointed to by this parameter is
- set to true if the evaluation is permitted to download missing certificates.
- @result A result code. See "Security Error Codes" (SecBase.h).
- @discussion By default, network fetch of missing certificates is enabled if
- the trust evaluation includes the SSL policy, otherwise it is disabled.
- */
-OSStatus SecTrustGetNetworkFetchAllowed(SecTrustRef trust,
- Boolean *allowFetch)
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
-
-/*!
- @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 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 object.
- @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_7_0);
-
-/*!
- @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.
- */
-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_7_0);
-#endif
-
-/*!
- @function SecTrustGetTrustResult
- @param trust 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 or trust parameters have changed, 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 trust,
- SecTrustResultType *result)
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
-
-/*!
- @function SecTrustCopyPublicKey
- @abstract Return the public key for a leaf certificate after it 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 A reference to a trust object.
- @result The number of certificates in the trust chain, including the anchor.
- @discussion Important: if the trust reference has not yet been evaluated,
- this function will evaluate it first before returning. If speed is critical,
- you may want to call SecTrustGetTrustResult first to make sure that a
- result other than kSecTrustResultInvalid is present for the trust object.
- */
-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 SecTrustCopyExceptions
- @abstract Returns an opaque cookie which will allow future evaluations
- of the current certificate to succeed.
- @param trust A reference to an evaluated trust object.
- @result An opaque cookie which when passed to SecTrustSetExceptions() will
- cause a call to SecTrustEvaluate() return kSecTrustResultProceed. This
- will happen upon subsequent evaluation of the current certificate unless
- some new error starts happening that wasn't being reported when the cookie
- was returned from this function (for example, if the certificate expires
- then evaluation will start failing again until a new cookie is obtained.)
- @discussion Normally this API should only be called once the errors have
- been presented to the user and the user decided to trust the current
- certificate chain regardless of the errors being presented, for the
- current application/server/protocol combination.
- */
-CFDataRef SecTrustCopyExceptions(SecTrustRef trust)
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_4_0);
-
-/*!
- @function SecTrustSetExceptions
- @abstract Set a trust cookie to be used for evaluating this certificate chain.
- @param trust A reference to a trust object.
- @param exceptions An exceptions cookie as returned by a call to
- SecTrustCopyExceptions() in the past.
- @result Upon calling SecTrustEvaluate(), any failures that where present at the
- time the exceptions object was created are ignored, and instead of returning
- kSecTrustResultRecoverableTrustFailure, kSecTrustResultProceed will be returned
- (if the certificate for which exceptions was created matches the current leaf
- certificate).
- @result Returns true if the exceptions cookies was valid and matches the current
- leaf certificate, false otherwise. This function will invalidate the existing
- trust result, requiring a subsequent evaluation for the newly-set exceptions.
- Note that this function returning true doesn't mean the caller can skip calling
- SecTrustEvaluate, as there may be new errors since the exceptions cookie was
- created (for example, a certificate may have subsequently expired.)
- @discussion Clients of this interface will need to establish the context of this
- exception to later decide when this exception cookie is to be used.
- Examples of this context would be the server we are connecting to, the ssid
- of the wireless network for which this cert is needed, the account for which
- this cert should be considered valid, and so on.
- */
-bool SecTrustSetExceptions(SecTrustRef trust, CFDataRef exceptions)
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_4_0);
-
-/*!
- @function SecTrustCopyProperties
- @abstract Return a property array for this trust evaluation.
- @param trust A reference to a 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.) 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);
-
-/*!
- @function SecTrustCopyResult
- @abstract Returns a dictionary containing information about the
- evaluated certificate chain for use by clients.
- @param trust A reference to a trust object.
- @result A dictionary with various fields that can be displayed to the user,
- or NULL if no additional info is available or the trust has not yet been
- validated. The caller is responsible for calling CFRelease on the value
- returned when it is no longer needed.
- @discussion Returns a dictionary for the overall trust evaluation. See the
- "Trust Result Constants" section for a list of currently defined keys.
- */
-CFDictionaryRef SecTrustCopyResult(SecTrustRef trust)
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
-
-/*!
- @function SecTrustSetOCSPResponse
- @abstract Attach OCSPResponse data to a trust object.
- @param trust A reference to a trust object.
- @param responseData This may be either a CFData object containing a single
- DER-encoded OCSPResponse (per RFC 2560), or a CFArray of these.
- @result A result code. See "Security Error Codes" (SecBase.h).
- @discussion Allows the caller to provide OCSPResponse data (which may be
- obtained during a TLS/SSL handshake, per RFC 3546) as input to a trust
- evaluation. If this data is available, it can obviate the need to contact
- an OCSP server for current revocation information.
- */
-OSStatus SecTrustSetOCSPResponse(SecTrustRef trust, CFTypeRef responseData)
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
-
-
-/*
- * Legacy functions (OS X only)
- */
-#if TARGET_OS_MAC && !TARGET_OS_IPHONE
-#include <Security/cssmtype.h>
-#include <Security/cssmapple.h>
-
-/*!
- @typedef SecTrustUserSetting
- @abstract Specifies a user-specified trust setting value.
- @discussion Deprecated in OS X 10.9. User trust settings are managed by
- functions in SecTrustSettings.h (starting with OS X 10.5), and by the
- SecTrustCopyExceptions and SecTrustSetExceptions functions (starting with
- iOS 4 and OS X 10.9). The latter two functions are recommended for both OS X
- and iOS, as they avoid the need to explicitly specify these values.
- */
-typedef SecTrustResultType SecTrustUserSetting
- __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_9, __IPHONE_NA, __IPHONE_NA);
-
-/*!
- @typedef SecTrustOptionFlags
- @abstract Options for customizing trust evaluation.
- @constant kSecTrustOptionAllowExpired Allow expired certificates.
- @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
-};
-
-/*!
- @function SecTrustSetOptions
- @abstract Sets optional flags for customizing a trust evaluation.
- @param trustRef A trust reference.
- @param options Flags to change evaluation behavior for this trust.
- @result A result code. See "Security Error Codes" (SecBase.h).
- @discussion This function is not available on iOS. Use SecTrustSetExceptions
- and SecTrustCopyExceptions to modify default trust results, and
- SecTrustSetNetworkFetchAllowed to specify whether missing CA certificates
- can be fetched from the network.
- */
-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 OS X 10.7 and later, where it
- was replaced by SecTrustSetOptions, and is not available on iOS. Your code
- should use SecTrustSetExceptions and SecTrustCopyExceptions to modify default
- trust results, and SecTrustSetNetworkFetchAllowed to specify whether missing
- CA certificates can be fetched from the network.
- */
-OSStatus SecTrustSetParameters(SecTrustRef trustRef,
- CSSM_TP_ACTION action, CFDataRef actionData)
- __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_7, __IPHONE_NA, __IPHONE_NA);
-
-/*!
- @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.
- Note: this function is not applicable to iOS.
- */
-OSStatus SecTrustSetKeychains(SecTrustRef trust, CFTypeRef keychainOrArray)
- __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_NA);
-
-/*!
- @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 OS X 10.7 and later,
- and is not available on iOS.
- 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)
- __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_7, __IPHONE_NA, __IPHONE_NA);
-
-/*!
- @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 OS X 10.7 and later,
- and is not available on iOS.
- 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)
- __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_7, __IPHONE_NA, __IPHONE_NA);
-
-/*!
- @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 OS X 10.7 and later,
- and is not available on iOS.
- 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)
- __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_7, __IPHONE_NA, __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 OS X 10.7 and later.
- */
-OSStatus SecTrustGetTPHandle(SecTrustRef trust, CSSM_TP_HANDLE *handle)
- __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_7, __IPHONE_NA, __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).
- @discussion This function is not available on iOS, as certificate data
- for system-trusted roots is currently unavailable on that platform.
- */
-OSStatus SecTrustCopyAnchorCertificates(CFArrayRef *anchors)
- __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_NA);
-
-#endif /* TARGET_OS_MAC && !TARGET_OS_IPHONE */
-
-
-#if defined(__cplusplus)
-}
-#endif
-
-#endif /* !_SECURITY_SECTRUST_H_ */
projects / apple / security.git / blobdiff