libsecurity_keychain/lib/SecTrust.h

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