OSX/libsecurity_keychain/lib/SecTrust.h

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