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 SecTrustTriggerValidUpdate
 301  @abstract Trigger trustd to fetch a valid update.
 302  @param error A returned error if trustd failed to trigger the update.
 303  @result True if the update was triggered, false if not.
 304  */
 305 bool SecTrustTriggerValidUpdate(CFErrorRef _Nullable * _Nullable CF_RETURNS_RETAINED error);
 306
 307 /*!
 308  @function SecTrustFlushResponseCache
 309  @abstract Removes all OCSP responses from the per-user response cache.
 310  @param error An optional pointer to an error object
 311  @result A boolean value indicating whether the operation was successful.
 312  @discussion If the error parameter is supplied, and the function returns false,
 313  the caller is subsequently responsible for releasing the returned CFErrorRef.
 314  */
 315 Boolean SecTrustFlushResponseCache(CFErrorRef _Nullable * _Nullable CF_RETURNS_RETAINED error)
 316     __OSX_AVAILABLE(10.13.4) __IOS_AVAILABLE(11.3) __TVOS_AVAILABLE(11.3) __WATCHOS_AVAILABLE(4.3);
 317
 318 /*!
 319  @function SecTrustSetTrustedLogs
 320  @abstract Sets the trusted CT logs for a given trust.
 321  @param trust A reference to a trust object.
 322  @param trustedLogs An array of trusted logs.
 323  @result A result code.  See "Security Error Codes" (SecBase.h).
 324  @discussion trustedLog is a CFArray of CFData containing the DER-encode SubjectPublicKeyInfo
 325  of the trusted CT logs.
 326  */
 327 OSStatus SecTrustSetTrustedLogs(SecTrustRef trust, CFArrayRef trustedLogs);
 328
 329 /* Keychain searches are allowed by default. Use this to turn off seaching of
 330     -keychain search list (i.e. login.keychain, system.keychain)
 331     -Local Items/iCloud Keychain
 332     -user- and admin-trusted roots
 333     -network-fetched issuers
 334  User must provide all necessary certificates in the input certificates and/or anchors. */
 335 OSStatus SecTrustSetKeychainsAllowed(SecTrustRef trust, Boolean allowed)
 336     __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 337
 338 /* Get the keychain search policy for the trust object. */
 339 OSStatus SecTrustGetKeychainsAllowed(SecTrustRef trust, Boolean * __nonnull allowed)
 340     __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 341
 342 /*!
 343  @function SecTrustEvaluateLeafOnly
 344  @abstract Evaluates the leaf of the trust reference synchronously.
 345  @param trust A reference to the trust object to evaluate.
 346  @param result A pointer to a result type.
 347  @result A result code. See "Security Error Codes" (SecBase.h).
 348  @discussion This function will only evaluate the trust of the leaf certificate.
 349  No chain will be built and only those aspects of the SecPolicyRef that address
 350  the expected contents of the leaf will be checked. This function does not honor
 351  any set exceptions or usage constraints.
 352  */
 353 OSStatus SecTrustEvaluateLeafOnly(SecTrustRef trust, SecTrustResultType * __nonnull result)
 354     __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 355
 356 /*!
 357  @function SecTrustSerialize
 358  @abstract Creates a serialized version of the trust object
 359  @param trust A reference to the trust object to serialize.
 360  @param error A pointer to an error.
 361  @result The serialized trust object.
 362  @discussion This function is intended to be used to share SecTrustRefs between
 363  processes. Saving the results to disk or sending them over network channels
 364  may cause unexpected behavior.
 365  */
 366 __nullable CF_RETURNS_RETAINED
 367 CFDataRef SecTrustSerialize(SecTrustRef trust, CFErrorRef *error)
 368     __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 369
 370 /*!
 371  @function SecTrustDeserialize
 372  @abstract Creates a trust object from the serialized data
 373  @param serializedTrust A reference to the serialized trust object
 374  @param error A pointer to an error.
 375  @result A trust object
 376  @discussion This function is intended to be used to share SecTrustRefs between
 377  processes. Saving the results to disk or sending them over network channels
 378  may cause unexpected behavior.
 379  */
 380 __nullable CF_RETURNS_RETAINED
 381 SecTrustRef SecTrustDeserialize(CFDataRef serializedTrust, CFErrorRef *error)
 382     __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 383
 384 /*!
 385  @function SecTrustGetTrustExceptionsArray
 386  @abstract Return the exceptions array currently set in the trust object
 387  @param trust A reference to the trust object
 388  @result The array of exceptions.
 389  @discussion This function returns an array of exceptions that was previously set
 390  using SecTrustSetExceptions, unlike SecTrustCopyExceptions which returns the
 391  exceptions which could be set using SecTrustSetExceptions.
 392  */
 393 __nullable CFArrayRef SecTrustGetTrustExceptionsArray(SecTrustRef trust)
 394     __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 395
 396 /*!
 397  @function SecTrustCopyInputCertificates
 398  @abstract Return the array of certificates currently set in the trust object
 399  @param trust A reference to the trust object
 400  @param certificates On return, an array of the certificates used by this trust.
 401  Call the CFRelease function to release this reference.
 402  @result A result code. See "Security Error Codes" (SecBase.h)
 403 */
 404 OSStatus SecTrustCopyInputCertificates(SecTrustRef trust, CFArrayRef * _Nonnull CF_RETURNS_RETAINED certificates)
 405 __OSX_AVAILABLE(10.12.4) __IOS_AVAILABLE(10.3) __TVOS_AVAILABLE(10.2) __WATCHOS_AVAILABLE(3.2);
 406
 407 /*!
 408  @function SecTrustAddToInputCertificates
 409  @abstract Add certificate(s) to the currently set certificates in the trust object
 410  @param trust A reference to the trust object
 411  @param certificates The group of certificates to add. This can either be a CFArrayRef
 412  of SecCertificateRef objects or a single SecCertificateRef.
 413  @result A result code. See "Security Error Codes" (SecBase.h)
 414  */
 415 OSStatus SecTrustAddToInputCertificates(SecTrustRef trust, CFTypeRef _Nonnull certificates)
 416     __OSX_AVAILABLE(10.12.4) __IOS_AVAILABLE(10.3) __TVOS_AVAILABLE(10.2) __WATCHOS_AVAILABLE(3.2);
 417
 418 /*!
 419  @function SecTrustSetPinningPolicyName
 420  @abstract Set the policy name to be used during the trust evaluation.
 421  @param trust A reference to the trust object
 422  @param policyName A string representing the name of the pinning policy to be used.
 423  @result A result code. See "Security Error Codes" (SecBase.h)
 424  @discussion This function permits the caller to enable the dynamic lookup of the
 425  pinning policy using a built-in database as an alternative to using a SecPolicyCreate function
 426  with the pinning rules and calling SecTrustCreateWithCertificates or SecTrustSetPolicies.
 427  */
 428 OSStatus SecTrustSetPinningPolicyName(SecTrustRef trust, CFStringRef policyName)
 429     __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 430
 431 /*!
 432  @function SecTrustSetPinningException
 433  @abstract Remove pinning requirement from this trust evaluation
 434  @param trust A reference to the trust object
 435  @result A result code. See "Security Error Codes" (SecBase.h)
 436  @discussion This function provides an exception for this particular trust for a bundle that
 437  otherwise requires pinning for all connections. Bundles use the SecTrustPinningRequired key
 438  with boolean value of true in their info plist to indicate that all SSL connections from the
 439  bundle must be pinned.
 440  */
 441 OSStatus SecTrustSetPinningException(SecTrustRef trust)
 442     __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 443
 444 #if TARGET_OS_IPHONE
 445 /*!
 446   @function SecTrustGetExceptionResetCount
 447   @abstract Returns the current epoch of trusted exceptions.
 448   @param error A pointer to an error.
 449   @result An unsigned 64-bit integer representing the current epoch.
 450   @discussion Exceptions tagged with an older epoch are not trusted.
 451   */
 452 uint64_t SecTrustGetExceptionResetCount(CFErrorRef *error)
 453     API_UNAVAILABLE(macos, macCatalyst) API_AVAILABLE(ios(12.0), tvos(12.0), watchos(5.0));
 454
 455 /*!
 456   @function SecTrustIncrementExceptionResetCount
 457   @abstract Increases the current epoch of trusted exceptions by 1.
 458   @param error A pointer to an error.
 459   @result A result code. See "Security Error Codes" (SecBase.h)
 460   @discussion By increasing the current epoch any existing exceptions, tagged with the old epoch, become distrusted.
 461   */
 462 OSStatus SecTrustIncrementExceptionResetCount(CFErrorRef *error)
 463     __API_UNAVAILABLE(macos, macCatalyst) __API_AVAILABLE(ios(12.0), tvos(12.0), watchos(5.0));
 464 #endif
 465
 466 #ifdef __BLOCKS__
 467 /*!
 468  @function SecTrustEvaluateFastAsync
 469  @abstract Evaluates a trust reference asynchronously.
 470  @param trust A reference to the trust object to evaluate.
 471  @param queue A dispatch queue on which the result callback will be
 472  executed. Note that this function MUST be called from that queue.
 473  @param result A SecTrustCallback block which will be executed when the
 474  trust evaluation is complete. The block is guaranteed to be called exactly once
 475  when the result code is errSecSuccess, and not called otherwise. Note that this
 476  block may be called synchronously inline if no asynchronous operations are required.
 477  @result A result code. See "Security Error Codes" (SecBase.h).
 478  */
 479 OSStatus SecTrustEvaluateFastAsync(SecTrustRef trust, dispatch_queue_t queue, SecTrustCallback result)
 480     __API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0));
 481 #endif
 482
 483 /*!
 484  @function SecTrustReportTLSAnalytics
 485  @discussion This function MUST NOT be called outside of the TLS stack.
 486 */
 487 bool SecTrustReportTLSAnalytics(CFStringRef eventName, xpc_object_t eventAttributes, CFErrorRef _Nullable * _Nullable CF_RETURNS_RETAINED error)
 488     __API_AVAILABLE(macos(10.13.4), ios(11.3), tvos(11.3), watchos(4.3));
 489
 490 /*!
 491  @function SecTrustReportNetworkingAnalytics
 492  @discussion This function MUST NOT be called outside of the networking stack.
 493 */
 494 bool SecTrustReportNetworkingAnalytics(const char *eventName, xpc_object_t eventAttributes)
 495     __API_AVAILABLE(macos(10.15), ios(13), tvos(13), watchos(5));
 496
 497 /*!
 498  @function SecTrustSetNeedsEvaluation
 499  @abstract Reset the evaluation state of the trust object
 500  @param trust Trust object to reset
 501  @discussion Calling this will reset the trust object so that the next time SecTrustEvaluate*
 502  is called, a new trust evaluation is performed. SecTrustSet* interfaces implicitly call this,
 503  so this function is only necessary if you've made system configuration changes (like trust
 504  settings) that don't impact the trust object itself.
 505  */
 506 void SecTrustSetNeedsEvaluation(SecTrustRef trust);
 507
 508 CF_IMPLICIT_BRIDGING_DISABLED
 509 CF_ASSUME_NONNULL_END
 510
 511 /*
 512  *  Legacy functions (OS X only)
 513  */
 514 #if TARGET_OS_OSX
 515
 516 CF_ASSUME_NONNULL_BEGIN
 517 CF_IMPLICIT_BRIDGING_ENABLED
 518
 519 #if SEC_OS_IPHONE
 520 #pragma clang diagnostic push
 521 #pragma clang diagnostic ignored "-Wfour-char-constants"
 522 #endif /* SEC_OS_IPHONE */
 523 /*
 524      unique keychain item attributes for user trust records.
 525  */
 526 enum {
 527     kSecTrustCertAttr                    = 'tcrt',
 528     kSecTrustPolicyAttr                  = 'tpol',
 529     /* Leopard and later */
 530     kSecTrustPubKeyAttr                  = 'tpbk',
 531     kSecTrustSignatureAttr               = 'tsig'
 532 };
 533
 534 #if SEC_OS_IPHONE
 535 #pragma clang diagnostic pop
 536 #endif /* SEC_OS_IPHONE */
 537
 538 /*!
 539      @function SecTrustGetUserTrust
 540      @abstract Gets the user-specified trust settings of a certificate and policy.
 541      @param certificate A reference to a certificate.
 542      @param policy A reference to a policy.
 543      @param trustSetting On return, a pointer to the user specified trust settings.
 544      @result A result code. See "Security Error Codes" (SecBase.h).
 545      @availability Mac OS X version 10.4. Deprecated in Mac OS X version 10.5.
 546  */
 547 OSStatus SecTrustGetUserTrust(SecCertificateRef __nullable certificate, SecPolicyRef __nullable policy, SecTrustUserSetting * __nullable trustSetting)
 548     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_4, __MAC_10_5, __IPHONE_NA, __IPHONE_NA);
 549
 550 /*!
 551      @function SecTrustSetUserTrust
 552      @abstract Sets the user-specified trust settings of a certificate and policy.
 553      @param certificate A reference to a certificate.
 554      @param policy A reference to a policy.
 555      @param trustSetting The user-specified trust settings.
 556      @result A result code. See "Security Error Codes" (SecBase.h).
 557      @availability Mac OS X version 10.4. Deprecated in Mac OS X version 10.5.
 558      @discussion as of Mac OS version 10.5, this will result in a call to
 559      SecTrustSettingsSetTrustSettings().
 560  */
 561 OSStatus SecTrustSetUserTrust(SecCertificateRef __nullable certificate, SecPolicyRef __nullable policy, SecTrustUserSetting trustSetting)
 562     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_4, __MAC_10_5, __IPHONE_NA, __IPHONE_NA);
 563
 564 /*!
 565      @function SecTrustSetUserTrustLegacy
 566      @abstract Sets the user-specified trust settings of a certificate and policy.
 567      @param certificate A reference to a certificate.
 568      @param policy A reference to a policy.
 569      @param trustSetting The user-specified trust settings.
 570      @result A result code.  See "Security Error Codes" (SecBase.h).
 571
 572      @This is the private version of what used to be SecTrustSetUserTrust(); it operates
 573      on UserTrust entries as that function used to. The current SecTrustSetUserTrust()
 574      function operated on Trust Settings.
 575  */
 576 OSStatus SecTrustSetUserTrustLegacy(SecCertificateRef __nullable certificate, SecPolicyRef __nullable policy, SecTrustUserSetting trustSetting)
 577     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_5, __MAC_10_12, __IPHONE_NA, __IPHONE_NA);
 578
 579 /*!
 580      @function SecTrustGetCSSMAnchorCertificates
 581      @abstract Retrieves the CSSM anchor certificates.
 582      @param cssmAnchors A pointer to an array of anchor certificates.
 583      @param cssmAnchorCount A pointer to the number of certificates in anchors.
 584      @result A result code. See "Security Error Codes" (SecBase.h).
 585      @availability Mac OS X version 10.4. Deprecated in Mac OS X version 10.5.
 586  */
 587 OSStatus SecTrustGetCSSMAnchorCertificates(const CSSM_DATA * __nullable * __nullable cssmAnchors, uint32 *cssmAnchorCount)
 588     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_4, __MAC_10_5, __IPHONE_NA, __IPHONE_NA);
 589
 590 /*!
 591      @function SecTrustCopyExtendedResult
 592      @abstract Gets the extended trust result after an evaluation has been performed.
 593      @param trust A trust reference.
 594      @param result On return, result points to a CFDictionaryRef containing extended trust results (if no error occurred).
 595      The caller is responsible for releasing this dictionary with CFRelease when finished with it.
 596      @result A result code. See "Security Error Codes" (SecBase.h).
 597      @discussion This function may only be used after SecTrustEvaluate has been called for the trust reference, otherwise
 598      errSecTrustNotAvailable is returned. If the certificate is not an extended validation certificate, there is
 599      no extended result data and errSecDataNotAvailable is returned. Currently, only one dictionary key is defined
 600      (kSecEVOrganizationName).
 601
 602      Note: this function will be deprecated in a future release of OS X. Your
 603      code should use SecTrustCopyResult to obtain the trust results dictionary.
 604  */
 605 OSStatus SecTrustCopyExtendedResult(SecTrustRef trust, CFDictionaryRef * __nonnull CF_RETURNS_RETAINED result)
 606     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_5, __MAC_10_12, __IPHONE_NA, __IPHONE_NA);
 607
 608 /*
 609  * Preference-related strings for Revocation policies.
 610  */
 611
 612 /*
 613  * Preference domain, i.e., the name of a plist in ~/Library/Preferences or in
 614  * /Library/Preferences
 615  */
 616 #define kSecRevocationDomain                "com.apple.security.revocation"
 617
 618 /* OCSP and CRL style keys, followed by values used for both of them */
 619 #define kSecRevocationOcspStyle             CFSTR("OCSPStyle")
 620 #define kSecRevocationCrlStyle              CFSTR("CRLStyle")
 621 #define kSecRevocationOff                   CFSTR("None")
 622 #define kSecRevocationBestAttempt           CFSTR("BestAttempt")
 623 #define kSecRevocationRequireIfPresent      CFSTR("RequireIfPresent")
 624 #define kSecRevocationRequireForAll         CFSTR("RequireForAll")
 625
 626 /* Which first if both enabled? */
 627 #define kSecRevocationWhichFirst            CFSTR("RevocationFirst")
 628 #define kSecRevocationOcspFirst             CFSTR("OCSP")
 629 #define kSecRevocationCrlFirst              CFSTR("CRL")
 630
 631 /* boolean: A "this policy is sufficient per cert" for each */
 632 #define kSecRevocationOCSPSufficientPerCert CFSTR("OCSPSufficientPerCert")
 633 #define kSecRevocationCRLSufficientPerCert  CFSTR("CRLSufficientPerCert")
 634
 635 /* local OCSP responder URI, value arbitrary string value */
 636 #define kSecOCSPLocalResponder              CFSTR("OCSPLocalResponder")
 637
 638 /* Extended trust result keys (now in public API) */
 639 #define kSecEVOrganizationName              kSecTrustOrganizationName
 640 #define kSecTrustExpirationDate             kSecTrustRevocationValidUntilDate
 641
 642 CF_IMPLICIT_BRIDGING_DISABLED
 643 CF_ASSUME_NONNULL_END
 644
 645 #endif /* TARGET_OS_MAC && !TARGET_OS_IPHONE */
 646
 647 __END_DECLS
 648
 649 #endif /* !_SECURITY_SECTRUSTPRIV_H_ */