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