trust/headers/SecTrustPriv.h

   1 /*
   2  * Copyright (c) 2003-2018 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 SecTrustPriv
  26      The functions and data types in SecTrustPriv implement trust computation
  27      and allow the user to apply trust decisions to the trust configuration.
  28  */
  29
  30 #ifndef _SECURITY_SECTRUSTPRIV_H_
  31 #define _SECURITY_SECTRUSTPRIV_H_
  32
  33 #include <Security/SecTrust.h>
  34 #include <CoreFoundation/CFString.h>
  35 #include <CoreFoundation/CFData.h>
  36 #include <CoreFoundation/CFDictionary.h>
  37 #include <xpc/xpc.h>
  38
  39 __BEGIN_DECLS
  40
  41 CF_ASSUME_NONNULL_BEGIN
  42 CF_IMPLICIT_BRIDGING_ENABLED
  43
  44 /* Constants used as keys in property lists.  See
  45  SecTrustCopySummaryPropertiesAtIndex for more information. */
  46 extern const CFStringRef kSecPropertyKeyType;
  47 extern const CFStringRef kSecPropertyKeyLabel;
  48 extern const CFStringRef kSecPropertyKeyLocalizedLabel;
  49 extern const CFStringRef kSecPropertyKeyValue;
  50
  51 extern const CFStringRef kSecPropertyTypeWarning;
  52 extern const CFStringRef kSecPropertyTypeSuccess;
  53 extern const CFStringRef kSecPropertyTypeSection;
  54 extern const CFStringRef kSecPropertyTypeData;
  55 extern const CFStringRef kSecPropertyTypeString;
  56 extern const CFStringRef kSecPropertyTypeURL;
  57 extern const CFStringRef kSecPropertyTypeDate;
  58 extern const CFStringRef kSecPropertyTypeArray;
  59 extern const CFStringRef kSecPropertyTypeNumber;
  60
  61 /* Constants used as keys in the dictionary returned by SecTrustCopyInfo. */
  62 extern const CFStringRef kSecTrustInfoExtendedValidationKey;
  63 extern const CFStringRef kSecTrustInfoCompanyNameKey;
  64 extern const CFStringRef kSecTrustInfoRevocationKey;
  65 extern const CFStringRef kSecTrustInfoRevocationValidUntilKey;
  66 extern const CFStringRef kSecTrustInfoCertificateTransparencyKey;
  67
  68 /* Constants used as keys in the certificate details dictionary.
  69  An array of per-certificate details is returned by SecTrustCopyResult
  70  as the value of the kSecTrustResultDetails key.
  71 */
  72 extern const CFStringRef kSecCertificateDetailStatusCodes;
  73     /*__OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_11_0);*/
  74
  75 /*!
  76  @enum Trust Result Constants
  77  @discussion Predefined key constants used to obtain values in a
  78  dictionary of trust evaluation results for a certificate chain,
  79  as retrieved from a call to SecTrustCopyResult.
  80
  81  @constant kSecTrustResultDetails
  82  This key will be present if a trust evaluation has been performed.
  83  Its value is a CFArrayRef of CFDictionaryRef representing detailed
  84  status info for each certificate in the completed chain.
  85  @constant kSecTrustRevocationReason
  86  This key will be present iff this chain had its revocation checked,
  87  and a "revoked" response was received. The value of this key will
  88  be a CFNumberRef indicating the reason for revocation. The possible
  89  reason code values are described in RFC 5280, section 5.3.1.
  90  */
  91 extern const CFStringRef kSecTrustResultDetails;
  92     /*__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_9_0);*/
  93 extern const CFStringRef kSecTrustRevocationReason;
  94     /*__OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);*/
  95
  96 /*!
  97      @function SecTrustCopySummaryPropertiesAtIndex
  98      @abstract Return a property array for the certificate.
  99      @param trust A reference to the trust object to evaluate.
 100      @param ix The index of the requested certificate.  Indices run from 0
 101      (leaf) to the anchor (or last certificate found if no anchor was found).
 102      @result A property array. It is the caller's responsibility to CFRelease
 103      the returned array when it is no longer needed. This function returns a
 104      short summary description of the certificate in question.  The property
 105      at index 0 of the array might also include general information about the
 106      entire chain's validity in the context of this trust evaluation.
 107
 108      @discussion Returns a property array for this trust certificate. A property
 109      array is an array of CFDictionaryRefs.  Each dictionary (we call it a
 110      property for short) has the following keys:
 111
 112         kSecPropertyKeyType This key's value determines how this property
 113             should be displayed. Its associated value is one of the
 114             following:
 115             kSecPropertyTypeWarning
 116                 The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not
 117                 set.  The kSecPropertyKeyValue is a CFStringRef which should
 118                 be displayed in yellow with a warning triangle.
 119             kSecPropertyTypeError
 120                 The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not
 121                 set.  The kSecPropertyKeyValue is a CFStringRef which should
 122                 be displayed in red with an error X.
 123             kSecPropertyTypeSuccess
 124                 The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not
 125                 set.  The kSecPropertyKeyValue is a CFStringRef which should
 126                 be displayed in green with a checkmark in front of it.
 127             kSecPropertyTypeTitle
 128                 The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not
 129                 set.  The kSecPropertyKeyValue is a CFStringRef which should
 130                 be displayed in a larger bold font.
 131             kSecPropertyTypeSection
 132                 The optional kSecPropertyKeyLocalizedLabel is a CFStringRef with the name
 133                 of the next section to display.  The value of the
 134                 kSecPropertyKeyValue key is a CFArrayRef which is a property
 135                 array as defined here.
 136             kSecPropertyTypeData
 137                 The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing
 138                 the localized label for the value for the kSecPropertyKeyValue.
 139                 The type of this value is a CFDataRef.  Its contents should be
 140                 displayed as: "bytes length_of_data : hexdump_of_data". Ideally
 141                 the UI will only show one line of hex dump data and have a
 142                 disclosure arrow to see the remainder.
 143             kSecPropertyTypeString
 144                 The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing
 145                 the localized label for the value for the kSecPropertyKeyValue.
 146                 The type of this value is a CFStringRef.  It's contents should be
 147                 displayed in the normal font.
 148             kSecPropertyTypeURL
 149                 The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing
 150                 the localized label for the value for the kSecPropertyKeyValue.
 151                 The type of this value is a CFURLRef.  It's contents should be
 152                 displayed as a hyperlink.
 153             kSecPropertyTypeDate
 154                 The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing
 155                 the localized label for the value for the kSecPropertyKeyValue.
 156                 The type of this value is a CFDateRef.  It's contents should be
 157                 displayed in human readable form (probably in the current
 158                 timezone).
 159         kSecPropertyKeyLocalizedLabel
 160             Human readable localized label for a given property.
 161         kSecPropertyKeyValue
 162             See description of kSecPropertyKeyType to determine what the value
 163             for this key is.
 164         kSecPropertyKeyLabel
 165             Non localized key (label) for this value.  This is only
 166             present for properties with fixed label names.
 167      @result A property array. It is the caller's responsability to CFRelease
 168      the returned array when it is no longer needed.
 169  */
 170 __nullable CF_RETURNS_RETAINED
 171 CFArrayRef SecTrustCopySummaryPropertiesAtIndex(SecTrustRef trust, CFIndex ix);
 172
 173 /*!
 174      @function SecTrustCopyDetailedPropertiesAtIndex
 175      @abstract Return a property array for the certificate.
 176      @param trust A reference to the trust object to evaluate.
 177      @param ix The index of the requested certificate.  Indices run from 0
 178      (leaf) to the anchor (or last certificate found if no anchor was found).
 179      @result A property array. It is the caller's responsibility to CFRelease
 180      the returned array when it is no longer needed.
 181      See SecTrustCopySummaryPropertiesAtIndex on how to intepret this array.
 182      Unlike that function call this function returns a detailed description
 183     of the certificate in question.
 184  */
 185 __nullable CF_RETURNS_RETAINED
 186 CFArrayRef SecTrustCopyDetailedPropertiesAtIndex(SecTrustRef trust, CFIndex ix);
 187
 188 /*!
 189      @function SecTrustCopyInfo
 190      @abstract Return a dictionary with additional information about the
 191      evaluated certificate chain for use by clients.
 192      @param trust A reference to an evaluated trust object.
 193      @discussion Returns a dictionary for this trust evaluation. This
 194      dictionary may have the following keys:
 195
 196         kSecTrustInfoExtendedValidationKey this key will be present and have
 197             a value of kCFBooleanTrue if this chain was validated for EV.
 198         kSecTrustInfoCompanyNameKey Company name field of subject of leaf
 199             certificate, this field is meant to be displayed to the user
 200             if the kSecTrustInfoExtendedValidationKey is present.
 201         kSecTrustInfoRevocationKey this key will be present iff this chain
 202             had its revocation checked. The value will be a kCFBooleanTrue
 203             if revocation checking was successful and none of the
 204             certificates in the chain were revoked.
 205             The value will be kCFBooleanFalse if no current revocation status
 206             could be obtained for one or more certificates in the chain due
 207             to connection problems or timeouts etc.  This is a hint to a
 208             client to retry revocation checking at a later time.
 209         kSecTrustInfoRevocationValidUntilKey this key will be present iff
 210         kSecTrustInfoRevocationKey has a value of kCFBooleanTrue.
 211             The value will be a CFDateRef representing the earliest date at
 212             which the revocation info for one of the certificates in this chain
 213             might change.
 214
 215      @result A dictionary with various fields that can be displayed to the user,
 216      or NULL if no additional info is available or the trust has not yet been
 217      validated.  The caller is responsible for calling CFRelease on the value
 218      returned when it is no longer needed.
 219  */
 220 __nullable CF_RETURNS_RETAINED
 221 CFDictionaryRef SecTrustCopyInfo(SecTrustRef trust);
 222
 223 /* For debugging purposes. */
 224 __nullable
 225 CFArrayRef SecTrustGetDetails(SecTrustRef trust);
 226
 227 __nullable CF_RETURNS_RETAINED
 228 CFArrayRef SecTrustCopyFilteredDetails(SecTrustRef trust);
 229
 230 /*!
 231  @function SecTrustIsExpiredOnly
 232  @abstract Determine whether expiration is the only problem with a certificate chain.
 233  @param trust A reference to a trust object.
 234  @result A boolean value indicating whether expiration is the only problem found
 235  with the certificate chain in the given trust reference.
 236  @discussion Returns true if one or more certificates in the chain have expired,
 237  expiration is an error (i.e. it is not being ignored by existing trust settings),
 238  and it is the only error encountered. Returns false if the certificate(s) have not
 239  expired, or are expired but have trust settings to override their expiration,
 240  or if the trust chain has other errors beside expiration. Your code should call
 241  this function after SecTrustEvaluate has returned a recoverable trust failure,
 242  so you can distinguish this case from other possible errors.
 243  */
 244 Boolean SecTrustIsExpiredOnly(SecTrustRef trust)
 245     __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 246
 247 /* For debugging purposes. */
 248 __nullable CF_RETURNS_RETAINED
 249 CFStringRef SecTrustCopyFailureDescription(SecTrustRef trust);
 250
 251 /*
 252  @function SecTrustGetTrustStoreVersionNumber
 253  @abstract Ask trustd what trust store version it is using.
 254  @param error A returned error if trustd failed to answer.
 255  @result The current version of the trust store. 0 upon failure.
 256  */
 257 uint64_t SecTrustGetTrustStoreVersionNumber(CFErrorRef _Nullable * _Nullable CF_RETURNS_RETAINED error);
 258
 259 /*
 260  @function SecTrustGetAssetVersionNumber
 261  @abstract Ask trustd what asset version it is using.
 262  @param error A returned error if trustd failed to answer.
 263  @result The current version of the asset. 0 upon failure.
 264  */
 265 uint64_t SecTrustGetAssetVersionNumber(CFErrorRef _Nullable * _Nullable CF_RETURNS_RETAINED error);
 266
 267 /*
 268  @function SecTrustOTAPKIGetUpdatedAsset
 269  @abstract Trigger trustd to fetch a new trust supplementals asset right now.
 270  @param error A returned error if trustd failed to update the asset.
 271  @result The current version of the update, regardless of the success of the update.
 272  @discussion This function blocks up to 1 minute until trustd has finished with the
 273  asset download and update. You should use the error parameter to determine whether
 274  the update was was successful. The current asset version is always returned.
 275  */
 276 uint64_t SecTrustOTAPKIGetUpdatedAsset(CFErrorRef _Nullable * _Nullable CF_RETURNS_RETAINED error);
 277
 278 /*
 279  @function SecTrustOTASecExperimentGetUpdatedAsset
 280  @abstract Trigger trustd to fetch a new SecExperiment asset right now.
 281  @param error A returned error if trustd failed to update the asset.
 282  @result The current version of the update, regardless of the success of the update.
 283  @discussion This function blocks up to 1 minute until trustd has finished with the
 284  asset download and update. You should use the error parameter to determine whether
 285  the update was was successful. The current asset version is always returned.
 286  */
 287 uint64_t SecTrustOTASecExperimentGetUpdatedAsset(CFErrorRef _Nullable * _Nullable CF_RETURNS_RETAINED error);
 288
 289 /*
 290  @function SecTrustOTASecExperimentCopyAsset
 291  @abstract Get current asset from trustd
 292  @param error A returned error if trustd fails to return asset
 293  @result Dictionary of asset
 294  @discussion If the error parameter is supplied, and the function returns false,
 295  the caller is subsequently responsible for releasing the returned CFErrorRef.
 296  */
 297 CFDictionaryRef SecTrustOTASecExperimentCopyAsset(CFErrorRef _Nullable * _Nullable CF_RETURNS_RETAINED error);
 298
 299 /*!
 300  @function SecTrustFlushResponseCache
 301  @abstract Removes all OCSP responses from the per-user response cache.
 302  @param error An optional pointer to an error object
 303  @result A boolean value indicating whether the operation was successful.
 304  @discussion If the error parameter is supplied, and the function returns false,
 305  the caller is subsequently responsible for releasing the returned CFErrorRef.
 306  */
 307 Boolean SecTrustFlushResponseCache(CFErrorRef _Nullable * _Nullable CF_RETURNS_RETAINED error)
 308     __OSX_AVAILABLE(10.13.4) __IOS_AVAILABLE(11.3) __TVOS_AVAILABLE(11.3) __WATCHOS_AVAILABLE(4.3);
 309
 310 /*!
 311  @function SecTrustSetTrustedLogs
 312  @abstract Sets the trusted CT logs for a given trust.
 313  @param trust A reference to a trust object.
 314  @param trustedLogs An array of trusted logs.
 315  @result A result code.  See "Security Error Codes" (SecBase.h).
 316  @discussion trustedLog is a CFArray of CFData containing the DER-encode SubjectPublicKeyInfo
 317  of the trusted CT logs.
 318  */
 319 OSStatus SecTrustSetTrustedLogs(SecTrustRef trust, CFArrayRef trustedLogs);
 320
 321 /* Keychain searches are allowed by default. Use this to turn off seaching of
 322     -keychain search list (i.e. login.keychain, system.keychain)
 323     -Local Items/iCloud Keychain
 324     -user- and admin-trusted roots
 325     -network-fetched issuers
 326  User must provide all necessary certificates in the input certificates and/or anchors. */
 327 OSStatus SecTrustSetKeychainsAllowed(SecTrustRef trust, Boolean allowed)
 328     __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 329
 330 /* Get the keychain search policy for the trust object. */
 331 OSStatus SecTrustGetKeychainsAllowed(SecTrustRef trust, Boolean * __nonnull allowed)
 332     __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 333
 334 /*!
 335  @function SecTrustEvaluateLeafOnly
 336  @abstract Evaluates the leaf of the trust reference synchronously.
 337  @param trust A reference to the trust object to evaluate.
 338  @param result A pointer to a result type.
 339  @result A result code. See "Security Error Codes" (SecBase.h).
 340  @discussion This function will only evaluate the trust of the leaf certificate.
 341  No chain will be built and only those aspects of the SecPolicyRef that address
 342  the expected contents of the leaf will be checked. This function does not honor
 343  any set exceptions or usage constraints.
 344  */
 345 OSStatus SecTrustEvaluateLeafOnly(SecTrustRef trust, SecTrustResultType * __nonnull result)
 346     __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 347
 348 /*!
 349  @function SecTrustSerialize
 350  @abstract Creates a serialized version of the trust object
 351  @param trust A reference to the trust object to serialize.
 352  @param error A pointer to an error.
 353  @result The serialized trust object.
 354  @discussion This function is intended to be used to share SecTrustRefs between
 355  processes. Saving the results to disk or sending them over network channels
 356  may cause unexpected behavior.
 357  */
 358 __nullable CF_RETURNS_RETAINED
 359 CFDataRef SecTrustSerialize(SecTrustRef trust, CFErrorRef *error)
 360     __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 361
 362 /*!
 363  @function SecTrustDeserialize
 364  @abstract Creates a trust object from the serialized data
 365  @param serializedTrust A reference to the serialized trust object
 366  @param error A pointer to an error.
 367  @result A trust object
 368  @discussion This function is intended to be used to share SecTrustRefs between
 369  processes. Saving the results to disk or sending them over network channels
 370  may cause unexpected behavior.
 371  */
 372 __nullable CF_RETURNS_RETAINED
 373 SecTrustRef SecTrustDeserialize(CFDataRef serializedTrust, CFErrorRef *error)
 374     __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 375
 376 /*!
 377  @function SecTrustGetTrustExceptionsArray
 378  @abstract Return the exceptions array currently set in the trust object
 379  @param trust A reference to the trust object
 380  @result The array of exceptions.
 381  @discussion This function returns an array of exceptions that was previously set
 382  using SecTrustSetExceptions, unlike SecTrustCopyExceptions which returns the
 383  exceptions which could be set using SecTrustSetExceptions.
 384  */
 385 __nullable CFArrayRef SecTrustGetTrustExceptionsArray(SecTrustRef trust)
 386     __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 387
 388 /*!
 389  @function SecTrustCopyInputCertificates
 390  @abstract Return the array of certificates currently set in the trust object
 391  @param trust A reference to the trust object
 392  @param certificates On return, an array of the certificates used by this trust.
 393  Call the CFRelease function to release this reference.
 394  @result A result code. See "Security Error Codes" (SecBase.h)
 395 */
 396 OSStatus SecTrustCopyInputCertificates(SecTrustRef trust, CFArrayRef * _Nonnull CF_RETURNS_RETAINED certificates)
 397 __OSX_AVAILABLE(10.12.4) __IOS_AVAILABLE(10.3) __TVOS_AVAILABLE(10.2) __WATCHOS_AVAILABLE(3.2);
 398
 399 /*!
 400  @function SecTrustAddToInputCertificates
 401  @abstract Add certificate(s) to the currently set certificates in the trust object
 402  @param trust A reference to the trust object
 403  @param certificates The group of certificates to add. This can either be a CFArrayRef
 404  of SecCertificateRef objects or a single SecCertificateRef.
 405  @result A result code. See "Security Error Codes" (SecBase.h)
 406  */
 407 OSStatus SecTrustAddToInputCertificates(SecTrustRef trust, CFTypeRef _Nonnull certificates)
 408     __OSX_AVAILABLE(10.12.4) __IOS_AVAILABLE(10.3) __TVOS_AVAILABLE(10.2) __WATCHOS_AVAILABLE(3.2);
 409
 410 /*!
 411  @function SecTrustSetPinningPolicyName
 412  @abstract Set the policy name to be used during the trust evaluation.
 413  @param trust A reference to the trust object
 414  @param policyName A string representing the name of the pinning policy to be used.
 415  @result A result code. See "Security Error Codes" (SecBase.h)
 416  @discussion This function permits the caller to enable the dynamic lookup of the
 417  pinning policy using a built-in database as an alternative to using a SecPolicyCreate function
 418  with the pinning rules and calling SecTrustCreateWithCertificates or SecTrustSetPolicies.
 419  */
 420 OSStatus SecTrustSetPinningPolicyName(SecTrustRef trust, CFStringRef policyName)
 421     __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 422
 423 /*!
 424  @function SecTrustSetPinningException
 425  @abstract Remove pinning requirement from this trust evaluation
 426  @param trust A reference to the trust object
 427  @result A result code. See "Security Error Codes" (SecBase.h)
 428  @discussion This function provides an exception for this particular trust for a bundle that
 429  otherwise requires pinning for all connections. Bundles use the SecTrustPinningRequired key
 430  with boolean value of true in their info plist to indicate that all SSL connections from the
 431  bundle must be pinned.
 432  */
 433 OSStatus SecTrustSetPinningException(SecTrustRef trust)
 434     __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 435
 436 #if TARGET_OS_IPHONE
 437 /*!
 438   @function SecTrustGetExceptionResetCount
 439   @abstract Returns the current epoch of trusted exceptions.
 440   @param error A pointer to an error.
 441   @result An unsigned 64-bit integer representing the current epoch.
 442   @discussion Exceptions tagged with an older epoch are not trusted.
 443   */
 444 uint64_t SecTrustGetExceptionResetCount(CFErrorRef *error)
 445     API_UNAVAILABLE(macos, iosmac) API_AVAILABLE(ios(12.0), tvos(12.0), watchos(5.0));
 446
 447 /*!
 448   @function SecTrustIncrementExceptionResetCount
 449   @abstract Increases the current epoch of trusted exceptions by 1.
 450   @param error A pointer to an error.
 451   @result A result code. See "Security Error Codes" (SecBase.h)
 452   @discussion By increasing the current epoch any existing exceptions, tagged with the old epoch, become distrusted.
 453   */
 454 OSStatus SecTrustIncrementExceptionResetCount(CFErrorRef *error)
 455     __API_UNAVAILABLE(macos, iosmac) __API_AVAILABLE(ios(12.0), tvos(12.0), watchos(5.0));
 456 #endif
 457
 458 #ifdef __BLOCKS__
 459 /*!
 460  @function SecTrustEvaluateFastAsync
 461  @abstract Evaluates a trust reference asynchronously.
 462  @param trust A reference to the trust object to evaluate.
 463  @param queue A dispatch queue on which the result callback will be
 464  executed. Note that this function MUST be called from that queue.
 465  @param result A SecTrustCallback block which will be executed when the
 466  trust evaluation is complete. The block is guaranteed to be called exactly once
 467  when the result code is errSecSuccess, and not called otherwise. Note that this
 468  block may be called synchronously inline if no asynchronous operations are required.
 469  @result A result code. See "Security Error Codes" (SecBase.h).
 470  */
 471 OSStatus SecTrustEvaluateFastAsync(SecTrustRef trust, dispatch_queue_t queue, SecTrustCallback result)
 472     __API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0));
 473 #endif
 474
 475 /*!
 476  @function SecTrustReportTLSAnalytics
 477  @discussion This function MUST NOT be called outside of the TLS stack.
 478 */
 479 bool SecTrustReportTLSAnalytics(CFStringRef eventName, xpc_object_t eventAttributes, CFErrorRef _Nullable * _Nullable CF_RETURNS_RETAINED error)
 480     __API_AVAILABLE(macos(10.13.4), ios(11.3), tvos(11.3), watchos(4.3));
 481
 482 /*!
 483  @function SecTrustReportNetworkingAnalytics
 484  @discussion This function MUST NOT be called outside of the networking stack.
 485 */
 486 bool SecTrustReportNetworkingAnalytics(const char *eventName, xpc_object_t eventAttributes)
 487     __API_AVAILABLE(macos(10.15), ios(13), tvos(13), watchos(5));
 488
 489 /*!
 490  @function SecTrustSetNeedsEvaluation
 491  @abstract Reset the evaluation state of the trust object
 492  @param trust Trust object to reset
 493  @discussion Calling this will reset the trust object so that the next time SecTrustEvaluate*
 494  is called, a new trust evaluation is performed. SecTrustSet* interfaces implicitly call this,
 495  so this function is only necessary if you've made system configuration changes (like trust
 496  settings) that don't impact the trust object itself.
 497  */
 498 void SecTrustSetNeedsEvaluation(SecTrustRef trust);
 499
 500 CF_IMPLICIT_BRIDGING_DISABLED
 501 CF_ASSUME_NONNULL_END
 502
 503 /*
 504  *  Legacy functions (OS X only)
 505  */
 506 #if TARGET_OS_OSX
 507
 508 CF_ASSUME_NONNULL_BEGIN
 509 CF_IMPLICIT_BRIDGING_ENABLED
 510
 511 #if SEC_OS_IPHONE
 512 #pragma clang diagnostic push
 513 #pragma clang diagnostic ignored "-Wfour-char-constants"
 514 #endif /* SEC_OS_IPHONE */
 515 /*
 516      unique keychain item attributes for user trust records.
 517  */
 518 enum {
 519     kSecTrustCertAttr                    = 'tcrt',
 520     kSecTrustPolicyAttr                  = 'tpol',
 521     /* Leopard and later */
 522     kSecTrustPubKeyAttr                  = 'tpbk',
 523     kSecTrustSignatureAttr               = 'tsig'
 524 };
 525
 526 #if SEC_OS_IPHONE
 527 #pragma clang diagnostic pop
 528 #endif /* SEC_OS_IPHONE */
 529
 530 /*!
 531      @function SecTrustGetUserTrust
 532      @abstract Gets the user-specified trust settings of a certificate and policy.
 533      @param certificate A reference to a certificate.
 534      @param policy A reference to a policy.
 535      @param trustSetting On return, a pointer to the user specified trust settings.
 536      @result A result code. See "Security Error Codes" (SecBase.h).
 537      @availability Mac OS X version 10.4. Deprecated in Mac OS X version 10.5.
 538  */
 539 OSStatus SecTrustGetUserTrust(SecCertificateRef __nullable certificate, SecPolicyRef __nullable policy, SecTrustUserSetting * __nullable trustSetting)
 540     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_4, __MAC_10_5, __IPHONE_NA, __IPHONE_NA);
 541
 542 /*!
 543      @function SecTrustSetUserTrust
 544      @abstract Sets the user-specified trust settings of a certificate and policy.
 545      @param certificate A reference to a certificate.
 546      @param policy A reference to a policy.
 547      @param trustSetting The user-specified trust settings.
 548      @result A result code. See "Security Error Codes" (SecBase.h).
 549      @availability Mac OS X version 10.4. Deprecated in Mac OS X version 10.5.
 550      @discussion as of Mac OS version 10.5, this will result in a call to
 551      SecTrustSettingsSetTrustSettings().
 552  */
 553 OSStatus SecTrustSetUserTrust(SecCertificateRef __nullable certificate, SecPolicyRef __nullable policy, SecTrustUserSetting trustSetting)
 554     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_4, __MAC_10_5, __IPHONE_NA, __IPHONE_NA);
 555
 556 /*!
 557      @function SecTrustSetUserTrustLegacy
 558      @abstract Sets the user-specified trust settings of a certificate and policy.
 559      @param certificate A reference to a certificate.
 560      @param policy A reference to a policy.
 561      @param trustSetting The user-specified trust settings.
 562      @result A result code.  See "Security Error Codes" (SecBase.h).
 563
 564      @This is the private version of what used to be SecTrustSetUserTrust(); it operates
 565      on UserTrust entries as that function used to. The current SecTrustSetUserTrust()
 566      function operated on Trust Settings.
 567  */
 568 OSStatus SecTrustSetUserTrustLegacy(SecCertificateRef __nullable certificate, SecPolicyRef __nullable policy, SecTrustUserSetting trustSetting)
 569     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_5, __MAC_10_12, __IPHONE_NA, __IPHONE_NA);
 570
 571 /*!
 572      @function SecTrustGetCSSMAnchorCertificates
 573      @abstract Retrieves the CSSM anchor certificates.
 574      @param cssmAnchors A pointer to an array of anchor certificates.
 575      @param cssmAnchorCount A pointer to the number of certificates in anchors.
 576      @result A result code. See "Security Error Codes" (SecBase.h).
 577      @availability Mac OS X version 10.4. Deprecated in Mac OS X version 10.5.
 578  */
 579 OSStatus SecTrustGetCSSMAnchorCertificates(const CSSM_DATA * __nullable * __nullable cssmAnchors, uint32 *cssmAnchorCount)
 580     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_4, __MAC_10_5, __IPHONE_NA, __IPHONE_NA);
 581
 582 /*!
 583      @function SecTrustCopyExtendedResult
 584      @abstract Gets the extended trust result after an evaluation has been performed.
 585      @param trust A trust reference.
 586      @param result On return, result points to a CFDictionaryRef containing extended trust results (if no error occurred).
 587      The caller is responsible for releasing this dictionary with CFRelease when finished with it.
 588      @result A result code. See "Security Error Codes" (SecBase.h).
 589      @discussion This function may only be used after SecTrustEvaluate has been called for the trust reference, otherwise
 590      errSecTrustNotAvailable is returned. If the certificate is not an extended validation certificate, there is
 591      no extended result data and errSecDataNotAvailable is returned. Currently, only one dictionary key is defined
 592      (kSecEVOrganizationName).
 593
 594      Note: this function will be deprecated in a future release of OS X. Your
 595      code should use SecTrustCopyResult to obtain the trust results dictionary.
 596  */
 597 OSStatus SecTrustCopyExtendedResult(SecTrustRef trust, CFDictionaryRef * __nonnull CF_RETURNS_RETAINED result)
 598     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_5, __MAC_10_12, __IPHONE_NA, __IPHONE_NA);
 599
 600 /*
 601  * Preference-related strings for Revocation policies.
 602  */
 603
 604 /*
 605  * Preference domain, i.e., the name of a plist in ~/Library/Preferences or in
 606  * /Library/Preferences
 607  */
 608 #define kSecRevocationDomain                "com.apple.security.revocation"
 609
 610 /* OCSP and CRL style keys, followed by values used for both of them */
 611 #define kSecRevocationOcspStyle             CFSTR("OCSPStyle")
 612 #define kSecRevocationCrlStyle              CFSTR("CRLStyle")
 613 #define kSecRevocationOff                   CFSTR("None")
 614 #define kSecRevocationBestAttempt           CFSTR("BestAttempt")
 615 #define kSecRevocationRequireIfPresent      CFSTR("RequireIfPresent")
 616 #define kSecRevocationRequireForAll         CFSTR("RequireForAll")
 617
 618 /* Which first if both enabled? */
 619 #define kSecRevocationWhichFirst            CFSTR("RevocationFirst")
 620 #define kSecRevocationOcspFirst             CFSTR("OCSP")
 621 #define kSecRevocationCrlFirst              CFSTR("CRL")
 622
 623 /* boolean: A "this policy is sufficient per cert" for each */
 624 #define kSecRevocationOCSPSufficientPerCert CFSTR("OCSPSufficientPerCert")
 625 #define kSecRevocationCRLSufficientPerCert  CFSTR("CRLSufficientPerCert")
 626
 627 /* local OCSP responder URI, value arbitrary string value */
 628 #define kSecOCSPLocalResponder              CFSTR("OCSPLocalResponder")
 629
 630 /* Extended trust result keys (now in public API) */
 631 #define kSecEVOrganizationName              kSecTrustOrganizationName
 632 #define kSecTrustExpirationDate             kSecTrustRevocationValidUntilDate
 633
 634 CF_IMPLICIT_BRIDGING_DISABLED
 635 CF_ASSUME_NONNULL_END
 636
 637 #endif /* TARGET_OS_MAC && !TARGET_OS_IPHONE */
 638
 639 __END_DECLS
 640
 641 #endif /* !_SECURITY_SECTRUSTPRIV_H_ */