trust/SecTrust.h

   1 /*
   2  * Copyright (c) 2002-2016 Apple Inc. All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 /*!
  25     @header SecTrust
  26     The functions and data types in SecTrust implement trust computation
  27     and allow the caller to apply trust decisions to the evaluation.
  28  */
  29
  30 #ifndef _SECURITY_SECTRUST_H_
  31 #define _SECURITY_SECTRUST_H_
  32
  33 #include <Security/SecBase.h>
  34 #include <CoreFoundation/CoreFoundation.h>
  35 #include <AvailabilityMacros.h>
  36
  37 __BEGIN_DECLS
  38
  39 CF_ASSUME_NONNULL_BEGIN
  40 CF_IMPLICIT_BRIDGING_ENABLED
  41
  42 /*!
  43     @typedef SecTrustResultType
  44     @abstract Specifies the trust result type.
  45     @discussion SecTrustResultType results have two dimensions.  They specify
  46     both whether evaluation suceeded and whether this is because of a user
  47     decision.  The commonly expected result is kSecTrustResultUnspecified,
  48     which indicates a positive result that wasn't decided by the user.  The
  49     common failure is kSecTrustResultRecoverableTrustFailure, which means a
  50     negative result.  kSecTrustResultProceed and kSecTrustResultDeny are the
  51     positive and negative result respectively when decided by the user.  User
  52     decisions are persisted through the use of SecTrustCopyExceptions() and
  53     SecTrustSetExceptions().  Finally, kSecTrustResultFatalTrustFailure is a
  54     negative result that must not be circumvented.
  55     @constant kSecTrustResultInvalid Indicates an invalid setting or result.
  56     This result usually means that SecTrustEvaluate has not yet been called.
  57     @constant kSecTrustResultProceed Indicates you may proceed.  This value
  58     may be returned by the SecTrustEvaluate function or stored as part of
  59     the user trust settings.
  60     @constant kSecTrustResultConfirm Indicates confirmation with the user
  61     is required before proceeding.  Important: this value is no longer returned
  62     or supported by SecTrustEvaluate or the SecTrustSettings API starting in
  63     OS X 10.5; its use is deprecated in OS X 10.9 and later, as well as in iOS.
  64     @constant kSecTrustResultDeny Indicates a user-configured deny; do not
  65     proceed. This value may be returned by the SecTrustEvaluate function
  66     or stored as part of the user trust settings.
  67     @constant kSecTrustResultUnspecified Indicates the evaluation succeeded
  68     and the certificate is implicitly trusted, but user intent was not
  69     explicitly specified.  This value may be returned by the SecTrustEvaluate
  70     function or stored as part of the user trust settings.
  71     @constant kSecTrustResultRecoverableTrustFailure Indicates a trust policy
  72     failure which can be overridden by the user.  This value may be returned
  73     by the SecTrustEvaluate function but not stored as part of the user
  74     trust settings.
  75     @constant kSecTrustResultFatalTrustFailure Indicates a trust failure
  76     which cannot be overridden by the user.  This value may be returned by the
  77     SecTrustEvaluate function but not stored as part of the user trust
  78     settings.
  79     @constant kSecTrustResultOtherError Indicates a failure other than that
  80     of trust evaluation. This value may be returned by the SecTrustEvaluate
  81     function but not stored as part of the user trust settings.
  82  */
  83 typedef CF_ENUM(uint32_t, SecTrustResultType) {
  84     kSecTrustResultInvalid  CF_ENUM_AVAILABLE(10_3, 2_0) = 0,
  85     kSecTrustResultProceed  CF_ENUM_AVAILABLE(10_3, 2_0) = 1,
  86     kSecTrustResultConfirm  CF_ENUM_DEPRECATED(10_3, 10_9, 2_0, 7_0) = 2,
  87     kSecTrustResultDeny  CF_ENUM_AVAILABLE(10_3, 2_0) = 3,
  88     kSecTrustResultUnspecified  CF_ENUM_AVAILABLE(10_3, 2_0) = 4,
  89     kSecTrustResultRecoverableTrustFailure  CF_ENUM_AVAILABLE(10_3, 2_0) = 5,
  90     kSecTrustResultFatalTrustFailure  CF_ENUM_AVAILABLE(10_3, 2_0) = 6,
  91     kSecTrustResultOtherError  CF_ENUM_AVAILABLE(10_3, 2_0) = 7
  92 };
  93
  94 /*!
  95     @typedef SecTrustRef
  96     @abstract CFType used for performing X.509 certificate trust evaluations.
  97  */
  98 typedef struct CF_BRIDGED_TYPE(id) __SecTrust *SecTrustRef;
  99
 100 /*!
 101     @enum Trust Property Constants
 102     @discussion Predefined key constants used to obtain values in a
 103         per-certificate dictionary of trust evaluation results,
 104         as retrieved from a call to SecTrustCopyProperties.
 105     @constant kSecPropertyTypeTitle Specifies a key whose value is a
 106         CFStringRef containing the title (display name) of this certificate.
 107     @constant kSecPropertyTypeError Specifies a key whose value is a
 108         CFStringRef containing the reason for a trust evaluation failure.
 109  */
 110 extern const CFStringRef kSecPropertyTypeTitle
 111     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
 112 extern const CFStringRef kSecPropertyTypeError
 113     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
 114
 115 /*!
 116     @enum Trust Result Constants
 117     @discussion Predefined key constants used to obtain values in a
 118         dictionary of trust evaluation results for a certificate chain,
 119         as retrieved from a call to SecTrustCopyResult.
 120     @constant kSecTrustEvaluationDate
 121         This key will be present if a trust evaluation has been performed
 122         and results are available. Its value is a CFDateRef representing
 123         when the evaluation for this trust object took place.
 124     @constant kSecTrustExtendedValidation
 125         This key will be present and have a value of kCFBooleanTrue
 126         if this chain was validated for EV.
 127     @constant kSecTrustOrganizationName
 128         Organization name field of subject of leaf certificate. This
 129         field is meant to be displayed to the user as the validated
 130         name of the company or entity that owns the certificate if the
 131         kSecTrustExtendedValidation key is present.
 132     @constant kSecTrustResultValue
 133         This key will be present if a trust evaluation has been performed.
 134         Its value is a CFNumberRef representing the SecTrustResultType result
 135         for the evaluation.
 136     @constant kSecTrustRevocationChecked
 137         This key will be present iff this chain had its revocation checked.
 138         The value will be a kCFBooleanTrue if revocation checking was
 139         successful and none of the certificates in the chain were revoked.
 140         The value will be kCFBooleanFalse if no current revocation status
 141         could be obtained for one or more certificates in the chain due
 142         to connection problems or timeouts.  This is a hint to a client
 143         to retry revocation checking at a later time.
 144     @constant kSecTrustRevocationValidUntilDate
 145         This key will be present iff kSecTrustRevocationChecked has a
 146         value of kCFBooleanTrue. The value will be a CFDateRef representing
 147         the earliest date at which the revocation info for one of the
 148         certificates in this chain might change.
 149     @constant kSecTrustCertificateTransparency
 150         This key will be present and have a value of kCFBooleanTrue
 151         if this chain is CT qualified.
 152     @constant kSecTrustCertificateTransparencyWhiteList
 153         This key will be present and have a value of kCFBooleanTrue
 154         if this chain is EV, not CT qualified, but included of the CT WhiteList.
 155  */
 156 extern const CFStringRef kSecTrustEvaluationDate
 157     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 158 extern const CFStringRef kSecTrustExtendedValidation
 159     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 160 extern const CFStringRef kSecTrustOrganizationName
 161     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 162 extern const CFStringRef kSecTrustResultValue
 163     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 164 extern const CFStringRef kSecTrustRevocationChecked
 165     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 166 extern const CFStringRef kSecTrustRevocationValidUntilDate
 167     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 168 extern const CFStringRef kSecTrustCertificateTransparency
 169     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);
 170 extern const CFStringRef kSecTrustCertificateTransparencyWhiteList
 171     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_12, __MAC_10_13, __IPHONE_10_0, __IPHONE_11_0);
 172
 173 #ifdef __BLOCKS__
 174 /*!
 175     @typedef SecTrustCallback
 176     @abstract Delivers the result from an asynchronous trust evaluation.
 177     @param trustRef A reference to the trust object which has been evaluated.
 178     @param trustResult The trust result of the evaluation. Additional status
 179     information can be obtained by calling SecTrustCopyProperties().
 180  */
 181 typedef void (^SecTrustCallback)(SecTrustRef trustRef, SecTrustResultType trustResult);
 182 #endif /* __BLOCKS__ */
 183
 184
 185 /*!
 186     @function SecTrustGetTypeID
 187     @abstract Returns the type identifier of SecTrust instances.
 188     @result The CFTypeID of SecTrust instances.
 189  */
 190 CFTypeID SecTrustGetTypeID(void)
 191     __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);
 192
 193 /*!
 194     @function SecTrustCreateWithCertificates
 195     @abstract Creates a trust object based on the given certificates and
 196     policies.
 197     @param certificates The group of certificates to verify.  This can either
 198     be a CFArrayRef of SecCertificateRef objects or a single SecCertificateRef
 199     @param policies An array of one or more policies. You may pass a
 200     SecPolicyRef to represent a single policy.
 201     @param trust On return, a pointer to the trust management reference.
 202     @result A result code.  See "Security Error Codes" (SecBase.h).
 203     @discussion If multiple policies are passed in, all policies must verify
 204     for the chain to be considered valid.
 205  */
 206 OSStatus SecTrustCreateWithCertificates(CFTypeRef certificates,
 207     CFTypeRef __nullable policies, SecTrustRef * __nonnull CF_RETURNS_RETAINED trust)
 208     __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);
 209
 210 /*!
 211     @function SecTrustSetPolicies
 212     @abstract Set the policies for which trust should be verified.
 213     @param trust A trust reference.
 214     @param policies An array of one or more policies. You may pass a
 215     SecPolicyRef to represent a single policy.
 216     @result A result code. See "Security Error Codes" (SecBase.h).
 217     @discussion This function will invalidate the existing trust result,
 218     requiring a fresh evaluation for the newly-set policies.
 219  */
 220 OSStatus SecTrustSetPolicies(SecTrustRef trust, CFTypeRef policies)
 221     __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_6_0);
 222
 223 /*!
 224     @function SecTrustCopyPolicies
 225     @abstract Returns an array of policies used for this evaluation.
 226     @param trust  A reference to a trust object.
 227     @param policies On return, an array of policies used by this trust.
 228     Call the CFRelease function to release this reference.
 229     @result A result code. See "Security Error Codes" (SecBase.h).
 230  */
 231 OSStatus SecTrustCopyPolicies(SecTrustRef trust, CFArrayRef * __nonnull CF_RETURNS_RETAINED policies)
 232     __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_7_0);
 233
 234 /*!
 235     @function SecTrustSetNetworkFetchAllowed
 236     @abstract Specifies whether a trust evaluation is permitted to fetch missing
 237     intermediate certificates from the network.
 238     @param trust A trust reference.
 239     @param allowFetch If true, and a certificate's issuer is not present in the
 240     trust reference but its network location is known, the evaluation is permitted
 241     to attempt to download it automatically. Pass false to disable network fetch
 242     for this trust evaluation.
 243     @result A result code. See "Security Error Codes" (SecBase.h).
 244     @discussion By default, network fetch of missing certificates is enabled if
 245     the trust evaluation includes the SSL policy, otherwise it is disabled.
 246  */
 247 OSStatus SecTrustSetNetworkFetchAllowed(SecTrustRef trust,
 248     Boolean allowFetch)
 249     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 250
 251 /*!
 252     @function SecTrustGetNetworkFetchAllowed
 253     @abstract Returns whether a trust evaluation is permitted to fetch missing
 254     intermediate certificates from the network.
 255     @param trust A trust reference.
 256     @param allowFetch On return, the boolean pointed to by this parameter is
 257     set to true if the evaluation is permitted to download missing certificates.
 258     @result A result code. See "Security Error Codes" (SecBase.h).
 259     @discussion By default, network fetch of missing certificates is enabled if
 260     the trust evaluation includes the SSL policy, otherwise it is disabled.
 261  */
 262 OSStatus SecTrustGetNetworkFetchAllowed(SecTrustRef trust,
 263     Boolean *allowFetch)
 264     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 265
 266 /*!
 267     @function SecTrustSetAnchorCertificates
 268     @abstract Sets the anchor certificates for a given trust.
 269     @param trust A reference to a trust object.
 270     @param anchorCertificates An array of anchor certificates.
 271     @result A result code.  See "Security Error Codes" (SecBase.h).
 272     @discussion Calling this function without also calling
 273     SecTrustSetAnchorCertificatesOnly() will disable trusting any
 274     anchors other than the ones in anchorCertificates.
 275  */
 276 OSStatus SecTrustSetAnchorCertificates(SecTrustRef trust,
 277     CFArrayRef anchorCertificates)
 278     __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);
 279
 280 /*!
 281     @function SecTrustSetAnchorCertificatesOnly
 282     @abstract Reenables trusting anchor certificates in addition to those
 283     passed in via the SecTrustSetAnchorCertificates API.
 284     @param trust A reference to a trust object.
 285     @param anchorCertificatesOnly If true, disables trusting any anchors other
 286     than the ones passed in via SecTrustSetAnchorCertificates().  If false,
 287     the built in anchor certificates are also trusted.
 288     @result A result code.  See "Security Error Codes" (SecBase.h).
 289  */
 290 OSStatus SecTrustSetAnchorCertificatesOnly(SecTrustRef trust,
 291     Boolean anchorCertificatesOnly)
 292     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 293
 294 /*!
 295     @function SecTrustCopyCustomAnchorCertificates
 296     @abstract Returns an array of custom anchor certificates used by a given
 297     trust, as set by a prior call to SecTrustSetAnchorCertificates, or NULL if
 298     no custom anchors have been specified.
 299     @param trust  A reference to a trust object.
 300     @param anchors On return, an array of custom anchor certificates (roots)
 301     used by this trust, or NULL if no custom anchors have been specified. Call
 302     the CFRelease function to release this reference.
 303     @result A result code. See "Security Error Codes" (SecBase.h).
 304  */
 305 OSStatus SecTrustCopyCustomAnchorCertificates(SecTrustRef trust,
 306     CFArrayRef * __nonnull CF_RETURNS_RETAINED anchors)
 307     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_7_0);
 308
 309 /*!
 310     @function SecTrustSetVerifyDate
 311     @abstract Set the date for which the trust should be verified.
 312     @param trust A reference to a trust object.
 313     @param verifyDate The date for which to verify trust.
 314     @result A result code.  See "Security Error Codes" (SecBase.h).
 315     @discussion This function lets you evaluate certificate validity for a
 316     given date (for example, to determine if a signature was valid on the date
 317     it was signed, even if the certificate has since expired.) If this function
 318     is not called, the time at which SecTrustEvaluate() is called is used
 319     implicitly as the verification time.
 320  */
 321 OSStatus SecTrustSetVerifyDate(SecTrustRef trust, CFDateRef verifyDate)
 322     __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);
 323
 324 /*!
 325     @function SecTrustGetVerifyTime
 326     @abstract Returns the verify time.
 327     @param trust A reference to the trust object being verified.
 328     @result A CFAbsoluteTime value representing the time at which certificates
 329     should be checked for validity.
 330     @discussion This function retrieves the verification time for the given
 331     trust reference, as set by a prior call to SecTrustSetVerifyDate(). If the
 332     verification time has not been set, this function returns a value of 0,
 333     indicating that the current date/time is implicitly used for verification.
 334  */
 335 CFAbsoluteTime SecTrustGetVerifyTime(SecTrustRef trust)
 336     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 337
 338 /*!
 339     @function SecTrustEvaluate
 340     @abstract Evaluates a trust reference synchronously.
 341     @param trust A reference to the trust object to evaluate.
 342     @param result A pointer to a result type.
 343     @result A result code. See "Security Error Codes" (SecBase.h).
 344     @discussion This function will completely evaluate trust before returning,
 345     possibly including network access to fetch intermediate certificates or to
 346     perform revocation checking. Since this function can block during those
 347     operations, you should call it from within a function that is placed on a
 348     dispatch queue, or in a separate thread from your application's main
 349     run loop. Alternatively, you can use the SecTrustEvaluateAsync function.
 350  */
 351 OSStatus SecTrustEvaluate(SecTrustRef trust, SecTrustResultType * __nullable result)
 352     __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);
 353
 354 #ifdef __BLOCKS__
 355 /*!
 356     @function SecTrustEvaluateAsync
 357     @abstract Evaluates a trust reference asynchronously.
 358     @param trust A reference to the trust object to evaluate.
 359     @param queue A dispatch queue on which the result callback should be
 360     executed. Pass NULL to use the current dispatch queue.
 361     @param result A SecTrustCallback block which will be executed when the
 362     trust evaluation is complete.
 363     @result A result code. See "Security Error Codes" (SecBase.h).
 364  */
 365 OSStatus SecTrustEvaluateAsync(SecTrustRef trust,
 366     dispatch_queue_t __nullable queue, SecTrustCallback result)
 367     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
 368 #endif
 369
 370 /*!
 371     @function SecTrustGetTrustResult
 372     @param trust A reference to a trust object.
 373     @param result A pointer to the result from the most recent call to
 374     SecTrustEvaluate for this trust reference. If SecTrustEvaluate has not been
 375     called or trust parameters have changed, the result is kSecTrustResultInvalid.
 376     @result A result code. See "Security Error Codes" (SecBase.h).
 377     @discussion This function replaces SecTrustGetResult for the purpose of
 378     obtaining the current evaluation result of a given trust reference.
 379  */
 380 OSStatus SecTrustGetTrustResult(SecTrustRef trust,
 381     SecTrustResultType *result)
 382     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
 383
 384 /*!
 385     @function SecTrustCopyPublicKey
 386     @abstract Return the public key for a leaf certificate after it has
 387     been evaluated.
 388     @param trust A reference to the trust object which has been evaluated.
 389     @result The certificate's public key, or NULL if it the public key could
 390     not be extracted (this can happen if the public key algorithm is not
 391     supported).  The caller is responsible for calling CFRelease on the
 392     returned key when it is no longer needed.
 393  */
 394 __nullable
 395 SecKeyRef SecTrustCopyPublicKey(SecTrustRef trust)
 396     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
 397
 398 /*!
 399     @function SecTrustGetCertificateCount
 400     @abstract Returns the number of certificates in an evaluated certificate
 401     chain.
 402     @param trust A reference to a trust object.
 403     @result The number of certificates in the trust chain, including the anchor.
 404     @discussion Important: if the trust reference has not yet been evaluated,
 405     this function will evaluate it first before returning. If speed is critical,
 406     you may want to call SecTrustGetTrustResult first to make sure that a
 407     result other than kSecTrustResultInvalid is present for the trust object.
 408  */
 409 CFIndex SecTrustGetCertificateCount(SecTrustRef trust)
 410     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
 411
 412 /*!
 413     @function SecTrustGetCertificateAtIndex
 414     @abstract Returns a certificate from the trust chain.
 415     @param trust Reference to a trust object.
 416     @param ix The index of the requested certificate.  Indices run from 0
 417     (leaf) to the anchor (or last certificate found if no anchor was found).
 418     The leaf cert (index 0) is always present regardless of whether the trust
 419     reference has been evaluated or not.
 420     @result A SecCertificateRef for the requested certificate.
 421  */
 422 __nullable
 423 SecCertificateRef SecTrustGetCertificateAtIndex(SecTrustRef trust, CFIndex ix)
 424     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
 425
 426 /*!
 427     @function SecTrustCopyExceptions
 428     @abstract Returns an opaque cookie which will allow future evaluations
 429     of the current certificate to succeed.
 430     @param trust A reference to an evaluated trust object.
 431     @result An opaque cookie which when passed to SecTrustSetExceptions() will
 432     cause a call to SecTrustEvaluate() return kSecTrustResultProceed.  This
 433     will happen upon subsequent evaluation of the current certificate unless
 434     some new error starts happening that wasn't being reported when the cookie
 435     was returned from this function (for example, if the certificate expires
 436     then evaluation will start failing again until a new cookie is obtained.)
 437     @discussion Normally this API should only be called once the errors have
 438     been presented to the user and the user decided to trust the current
 439     certificate chain regardless of the errors being presented, for the
 440     current application/server/protocol combination.
 441  */
 442 CFDataRef SecTrustCopyExceptions(SecTrustRef trust)
 443     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_4_0);
 444
 445 /*!
 446     @function SecTrustSetExceptions
 447     @abstract Set a trust cookie to be used for evaluating this certificate chain.
 448     @param trust A reference to a trust object.
 449     @param exceptions An exceptions cookie as returned by a call to
 450     SecTrustCopyExceptions() in the past.  You may pass NULL to clear any
 451     exceptions which have been previously set on this trust reference.
 452     @result Upon calling SecTrustEvaluate(), any failures that were present at the
 453     time the exceptions object was created are ignored, and instead of returning
 454     kSecTrustResultRecoverableTrustFailure, kSecTrustResultProceed will be returned
 455     (if the certificate for which exceptions was created matches the current leaf
 456     certificate).
 457     @result Returns true if the exceptions cookies was valid and matches the current
 458     leaf certificate, false otherwise.  This function will invalidate the existing
 459     trust result, requiring a subsequent evaluation for the newly-set exceptions.
 460     Note that this function returning true doesn't mean the caller can skip calling
 461     SecTrustEvaluate, as there may be new errors since the exceptions cookie was
 462     created (for example, a certificate may have subsequently expired.)
 463     @discussion Clients of this interface will need to establish the context of this
 464     exception to later decide when this exception cookie is to be used.
 465     Examples of this context would be the server we are connecting to, the ssid
 466     of the wireless network for which this cert is needed, the account for which
 467     this cert should be considered valid, and so on.
 468  */
 469 bool SecTrustSetExceptions(SecTrustRef trust, CFDataRef __nullable exceptions)
 470     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_4_0);
 471
 472 /*!
 473     @function SecTrustCopyProperties
 474     @abstract Return a property array for this trust evaluation.
 475     @param trust A reference to a trust object. If the trust has not been
 476     evaluated, the returned property array will be empty.
 477     @result A property array. It is the caller's responsibility to CFRelease
 478     the returned array when it is no longer needed.
 479     @discussion This function returns an ordered array of CFDictionaryRef
 480     instances for each certificate in the chain. Indices run from 0 (leaf) to
 481     the anchor (or last certificate found if no anchor was found.) See the
 482     "Trust Property Constants" section for a list of currently defined keys.
 483  */
 484 __nullable
 485 CFArrayRef SecTrustCopyProperties(SecTrustRef trust)
 486     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
 487
 488 /*!
 489     @function SecTrustCopyResult
 490     @abstract Returns a dictionary containing information about the
 491     evaluated certificate chain for use by clients.
 492     @param trust A reference to a trust object.
 493     @result A dictionary with various fields that can be displayed to the user,
 494     or NULL if no additional info is available or the trust has not yet been
 495     validated.  The caller is responsible for calling CFRelease on the value
 496     returned when it is no longer needed.
 497     @discussion Returns a dictionary for the overall trust evaluation. See the
 498     "Trust Result Constants" section for a list of currently defined keys.
 499  */
 500 __nullable
 501 CFDictionaryRef SecTrustCopyResult(SecTrustRef trust)
 502     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 503
 504 /*!
 505     @function SecTrustSetOCSPResponse
 506     @abstract Attach OCSPResponse data to a trust object.
 507     @param trust A reference to a trust object.
 508     @param responseData This may be either a CFData object containing a single
 509     DER-encoded OCSPResponse (per RFC 2560), or a CFArray of these.
 510     @result A result code. See "Security Error Codes" (SecBase.h).
 511     @discussion Allows the caller to provide OCSPResponse data (which may be
 512     obtained during a TLS/SSL handshake, per RFC 3546) as input to a trust
 513     evaluation. If this data is available, it can obviate the need to contact
 514     an OCSP server for current revocation information.
 515  */
 516 OSStatus SecTrustSetOCSPResponse(SecTrustRef trust, CFTypeRef __nullable responseData)
 517     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 518
 519 CF_IMPLICIT_BRIDGING_DISABLED
 520 CF_ASSUME_NONNULL_END
 521
 522 /*
 523  *  Legacy functions (OS X only)
 524  */
 525 #if TARGET_OS_MAC && !TARGET_OS_IPHONE
 526 #include <Security/cssmtype.h>
 527 #include <Security/cssmapple.h>
 528
 529 CF_ASSUME_NONNULL_BEGIN
 530 CF_IMPLICIT_BRIDGING_ENABLED
 531
 532 /*!
 533     @typedef SecTrustUserSetting
 534     @abstract Specifies a user-specified trust setting value.
 535     @discussion Deprecated in OS X 10.9. User trust settings are managed by
 536     functions in SecTrustSettings.h (starting with OS X 10.5), and by the
 537     SecTrustCopyExceptions and SecTrustSetExceptions functions (starting with
 538     iOS 4 and OS X 10.9). The latter two functions are recommended for both OS X
 539     and iOS, as they avoid the need to explicitly specify these values.
 540  */
 541 typedef SecTrustResultType SecTrustUserSetting
 542     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_9, __IPHONE_NA, __IPHONE_NA);
 543
 544 /*!
 545     @typedef SecTrustOptionFlags
 546     @abstract Options for customizing trust evaluation.
 547     @constant kSecTrustOptionAllowExpired Allow expired certificates.
 548     @constant kSecTrustOptionLeafIsCA Allow CA as leaf certificate.
 549     @constant kSecTrustOptionFetchIssuerFromNet Allow network fetch of CA cert.
 550     @constant kSecTrustOptionAllowExpiredRoot Allow expired roots.
 551     @constant kSecTrustOptionRequireRevPerCert Require positive revocation
 552     check per certificate.
 553     @constant kSecTrustOptionUseTrustSettings Use TrustSettings instead of
 554     anchors.
 555     @constant kSecTrustOptionImplicitAnchors Properly self-signed certs are
 556     treated as anchors implicitly.
 557  */
 558 typedef CF_OPTIONS(uint32_t, SecTrustOptionFlags) {
 559     kSecTrustOptionAllowExpired       = 0x00000001,
 560     kSecTrustOptionLeafIsCA           = 0x00000002,
 561     kSecTrustOptionFetchIssuerFromNet = 0x00000004,
 562     kSecTrustOptionAllowExpiredRoot   = 0x00000008,
 563     kSecTrustOptionRequireRevPerCert  = 0x00000010,
 564     kSecTrustOptionUseTrustSettings   = 0x00000020,
 565     kSecTrustOptionImplicitAnchors    = 0x00000040
 566 };
 567
 568 /*!
 569     @function SecTrustSetOptions
 570     @abstract Sets optional flags for customizing a trust evaluation.
 571     @param trustRef A trust reference.
 572     @param options Flags to change evaluation behavior for this trust.
 573     @result A result code. See "Security Error Codes" (SecBase.h).
 574     @discussion This function is not available on iOS. Use SecTrustSetExceptions
 575     and SecTrustCopyExceptions to modify default trust results, and
 576     SecTrustSetNetworkFetchAllowed to specify whether missing CA certificates
 577     can be fetched from the network.
 578  */
 579 OSStatus SecTrustSetOptions(SecTrustRef trustRef, SecTrustOptionFlags options)
 580     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 581
 582 /*!
 583     @function SecTrustSetParameters
 584     @abstract Sets the action and action data for a trust object.
 585     @param trustRef The reference to the trust to change.
 586     @param action A trust action.
 587     @param actionData A reference to data associated with this action.
 588     @result A result code. See "Security Error Codes" (SecBase.h).
 589     @discussion This function is deprecated in OS X 10.7 and later, where it
 590     was replaced by SecTrustSetOptions, and is not available on iOS. Your code
 591     should use SecTrustSetExceptions and SecTrustCopyExceptions to modify default
 592     trust results, and SecTrustSetNetworkFetchAllowed to specify whether missing
 593     CA certificates can be fetched from the network.
 594  */
 595 OSStatus SecTrustSetParameters(SecTrustRef trustRef,
 596     CSSM_TP_ACTION action, CFDataRef actionData)
 597     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_7, __IPHONE_NA, __IPHONE_NA);
 598
 599 /*!
 600     @function SecTrustSetKeychains
 601     @abstract Sets the keychains for a given trust object.
 602     @param trust A reference to a trust object.
 603     @param keychainOrArray A reference to an array of keychains to search, a
 604     single keychain, or NULL to use the default keychain search list.
 605     @result A result code. See "Security Error Codes" (SecBase.h).
 606     @discussion This function is deprecated in macOS 10.13 and later. Beginning in
 607     macOS 10.12, this function no longer affected the behavior of the trust
 608     evaluation: the user's keychain search list and the system
 609     anchors keychain are searched for certificates to complete the chain. To change
 610     the keychains that are searched, callers must use SecKeychainSetSearchList to
 611     change the user's keychain search list.
 612     Note: this function was never applicable to iOS.
 613  */
 614 OSStatus SecTrustSetKeychains(SecTrustRef trust, CFTypeRef __nullable keychainOrArray)
 615     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_3, __MAC_10_13, __IPHONE_NA, __IPHONE_NA);
 616
 617 /*!
 618     @function SecTrustGetResult
 619     @abstract Returns detailed information on the outcome of an evaluation.
 620     @param trustRef A reference to a trust object.
 621     @param result A pointer to the result from the call to SecTrustEvaluate.
 622     @param certChain On return, a pointer to the certificate chain used to
 623     validate the input certificate. Call the CFRelease function to release
 624     this pointer.
 625     @param statusChain On return, a pointer to the status of the certificate
 626     chain. Do not attempt to free this pointer; it remains valid until the
 627     trust is destroyed or the next call to SecTrustEvaluate.
 628     @result A result code. See "Security Error Codes" (SecBase.h).
 629     @discussion This function is deprecated in OS X 10.7 and later,
 630     and is not available on iOS.
 631     To get the complete certificate chain, use SecTrustGetCertificateCount and
 632     SecTrustGetCertificateAtIndex. To get detailed status information for each
 633     certificate, use SecTrustCopyProperties. To get the overall trust result
 634     for the evaluation, use SecTrustGetTrustResult.
 635  */
 636 OSStatus SecTrustGetResult(SecTrustRef trustRef, SecTrustResultType * __nullable result,
 637     CFArrayRef * __nullable CF_RETURNS_RETAINED certChain, CSSM_TP_APPLE_EVIDENCE_INFO * __nullable * __nullable statusChain)
 638     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_7, __IPHONE_NA, __IPHONE_NA);
 639
 640 /*!
 641     @function SecTrustGetCssmResult
 642     @abstract Gets the CSSM trust result.
 643     @param trust A reference to a trust.
 644     @param result On return, a pointer to the CSSM trust result.
 645     @result A result code. See "Security Error Codes" (SecBase.h).
 646     @discussion This function is deprecated in OS X 10.7 and later,
 647     and is not available on iOS.
 648     To get detailed status information for each certificate, use
 649     SecTrustCopyProperties. To get the overall trust result for the evaluation,
 650     use SecTrustGetTrustResult.
 651  */
 652 OSStatus SecTrustGetCssmResult(SecTrustRef trust,
 653     CSSM_TP_VERIFY_CONTEXT_RESULT_PTR __nullable * __nonnull result)
 654     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_7, __IPHONE_NA, __IPHONE_NA);
 655
 656 /*!
 657     @function SecTrustGetCssmResultCode
 658     @abstract Gets the result code from the most recent call to SecTrustEvaluate
 659     for the specified trust.
 660     @param trust A reference to a trust.
 661     @param resultCode On return, the result code produced by the most recent
 662     evaluation of the given trust (cssmerr.h). The value of resultCode is
 663     undefined if SecTrustEvaluate has not been called.
 664     @result A result code. See "Security Error Codes" (SecBase.h). Returns
 665     errSecTrustNotAvailable if SecTrustEvaluate has not been called for the
 666     specified trust.
 667     @discussion This function is deprecated in OS X 10.7 and later,
 668     and is not available on iOS.
 669     To get detailed status information for each certificate, use
 670     SecTrustCopyProperties. To get the overall trust result for the evaluation,
 671     use SecTrustGetTrustResult.
 672  */
 673 OSStatus SecTrustGetCssmResultCode(SecTrustRef trust, OSStatus *resultCode)
 674     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_7, __IPHONE_NA, __IPHONE_NA);
 675
 676 /*!
 677     @function SecTrustGetTPHandle
 678     @abstract Gets the CSSM trust handle
 679     @param trust A reference to a trust.
 680     @param handle On return, a CSSM trust handle.
 681     @result A result code. See "Security Error Codes" (SecBase.h).
 682     @discussion This function is deprecated in OS X 10.7 and later.
 683  */
 684 OSStatus SecTrustGetTPHandle(SecTrustRef trust, CSSM_TP_HANDLE *handle)
 685     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_7, __IPHONE_NA, __IPHONE_NA);
 686
 687 /*!
 688     @function SecTrustCopyAnchorCertificates
 689     @abstract Returns an array of default anchor (root) certificates used by
 690     the system.
 691     @param anchors On return, an array containing the system's default anchors
 692     (roots). Call the CFRelease function to release this pointer.
 693     @result A result code. See "Security Error Codes" (SecBase.h).
 694     @discussion This function is not available on iOS, as certificate data
 695     for system-trusted roots is currently unavailable on that platform.
 696  */
 697 OSStatus SecTrustCopyAnchorCertificates(CFArrayRef * __nonnull CF_RETURNS_RETAINED anchors)
 698     __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_NA);
 699
 700 CF_IMPLICIT_BRIDGING_DISABLED
 701 CF_ASSUME_NONNULL_END
 702
 703 #endif /* TARGET_OS_MAC && !TARGET_OS_IPHONE */
 704
 705 __END_DECLS
 706
 707 #endif /* !_SECURITY_SECTRUST_H_ */