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