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) 38extern "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 83typedef uint32_t SecTrustResultType; 84enum { 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 */ 99typedef 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 */ 111extern CFTypeRef kSecPropertyTypeTitle 112 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0); 113extern 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 */ 151extern CFTypeRef kSecTrustEvaluationDate 152 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 153extern CFTypeRef kSecTrustExtendedValidation 154 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 155extern CFTypeRef kSecTrustOrganizationName 156 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 157extern CFTypeRef kSecTrustResultValue 158 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 159extern CFTypeRef kSecTrustRevocationChecked 160 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 161extern 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 */ 172typedef 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 */ 181CFTypeID 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 */ 197OSStatus 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 */ 211OSStatus 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 */ 222OSStatus 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 */ 238OSStatus 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 */ 253OSStatus 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 */ 267OSStatus 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 */ 281OSStatus 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 */ 296OSStatus 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 */ 312OSStatus 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 */ 326CFAbsoluteTime 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 */ 342OSStatus 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 */ 356OSStatus 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 */ 371OSStatus 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 */ 385SecKeyRef 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 */ 399CFIndex 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 */ 412SecCertificateRef 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 */ 431CFDataRef 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 */ 457bool 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 */ 472CFArrayRef 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 */ 487CFDictionaryRef 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 */ 502OSStatus 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 */ 522typedef 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 */ 539typedef uint32_t SecTrustOptionFlags; 540enum { 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 */ 561OSStatus 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 */ 577OSStatus 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 */ 593OSStatus 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 */ 615OSStatus 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 */ 631OSStatus 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 */ 652OSStatus 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 */ 663OSStatus 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 */ 676OSStatus 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_ */ 687