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 SecTrustOTAPKIGetUpdatedAsset
 259  @abstract Trigger trustd to fetch a new trust supplementals asset right now.
 260  @param error A returned error if trustd failed to update the asset.
 261  @result The current version of the update, regardless of the success of the update.
 262  @discussion This function blocks up to 1 minute until trustd has finished with the
 263  asset download and update. You should use the error parameter to determine whether
 264  the update was was successful. The current asset version is always returned.
 265  */
 266 uint64_t SecTrustOTAPKIGetUpdatedAsset(CFErrorRef _Nullable * _Nullable CF_RETURNS_RETAINED error);
 267
 268 /*!
 269  @function SecTrustFlushResponseCache
 270  @abstract Removes all OCSP responses from the per-user response cache.
 271  @param error An optional pointer to an error object
 272  @result A boolean value indicating whether the operation was successful.
 273  @discussion If the error parameter is supplied, and the function returns false,
 274  the caller is subsequently responsible for releasing the returned CFErrorRef.
 275  */
 276 Boolean SecTrustFlushResponseCache(CFErrorRef _Nullable * _Nullable CF_RETURNS_RETAINED error)
 277     __OSX_AVAILABLE(10.13.4) __IOS_AVAILABLE(11.3) __TVOS_AVAILABLE(11.3) __WATCHOS_AVAILABLE(4.3);
 278
 279 /*!
 280  @function SecTrustSignedCertificateTimestampList
 281  @abstract Attach SignedCertificateTimestampList data to a trust object.
 282  @param trust A reference to a trust object.
 283  @param sctArray is a CFArray of CFData objects each containing a SCT (per RFC 6962).
 284  @result A result code. See "Security Error Codes" (SecBase.h).
 285  @discussion Allows the caller to provide SCT data (which may be
 286  obtained during a TLS/SSL handshake, per RFC 6962) as input to a trust
 287  evaluation.
 288  */
 289 OSStatus SecTrustSetSignedCertificateTimestamps(SecTrustRef trust, CFArrayRef sctArray);
 290
 291 /*!
 292  @function SecTrustSetTrustedLogs
 293  @abstract Sets the trusted CT logs for a given trust.
 294  @param trust A reference to a trust object.
 295  @param trustedLogs An array of trusted logs.
 296  @result A result code.  See "Security Error Codes" (SecBase.h).
 297  @discussion trustedLog is a CFArray of CFData containing the DER-encode SubjectPublicKeyInfo
 298  of the trusted CT logs.
 299  */
 300 OSStatus SecTrustSetTrustedLogs(SecTrustRef trust, CFArrayRef trustedLogs);
 301
 302 /* Keychain searches are allowed by default. Use this to turn off seaching of
 303     -keychain search list (i.e. login.keychain, system.keychain)
 304     -Local Items/iCloud Keychain
 305     -user- and admin-trusted roots
 306     -network-fetched issuers
 307  User must provide all necessary certificates in the input certificates and/or anchors. */
 308 OSStatus SecTrustSetKeychainsAllowed(SecTrustRef trust, Boolean allowed)
 309     __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 310
 311 /* Get the keychain search policy for the trust object. */
 312 OSStatus SecTrustGetKeychainsAllowed(SecTrustRef trust, Boolean * __nonnull allowed)
 313     __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 314
 315 /*!
 316  @function SecTrustEvaluateLeafOnly
 317  @abstract Evaluates the leaf of the trust reference synchronously.
 318  @param trust A reference to the trust object to evaluate.
 319  @param result A pointer to a result type.
 320  @result A result code. See "Security Error Codes" (SecBase.h).
 321  @discussion This function will only evaluate the trust of the leaf certificate.
 322  No chain will be built and only those aspects of the SecPolicyRef that address
 323  the expected contents of the leaf will be checked. This function does not honor
 324  any set exceptions or usage constraints.
 325  */
 326 OSStatus SecTrustEvaluateLeafOnly(SecTrustRef trust, SecTrustResultType * __nonnull result)
 327     __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 328
 329 /*!
 330  @function SecTrustSerialize
 331  @abstract Creates a serialized version of the trust object
 332  @param trust A reference to the trust object to serialize.
 333  @param error A pointer to an error.
 334  @result The serialized trust object.
 335  @discussion This function is intended to be used to share SecTrustRefs between
 336  processes. Saving the results to disk or sending them over network channels
 337  may cause unexpected behavior.
 338  */
 339 __nullable CF_RETURNS_RETAINED
 340 CFDataRef SecTrustSerialize(SecTrustRef trust, CFErrorRef *error)
 341     __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 342
 343 /*!
 344  @function SecTrustDeserialize
 345  @abstract Creates a trust object from the serialized data
 346  @param serializedTrust A reference to the serialized trust object
 347  @param error A pointer to an error.
 348  @result A trust object
 349  @discussion This function is intended to be used to share SecTrustRefs between
 350  processes. Saving the results to disk or sending them over network channels
 351  may cause unexpected behavior.
 352  */
 353 __nullable CF_RETURNS_RETAINED
 354 SecTrustRef SecTrustDeserialize(CFDataRef serializedTrust, CFErrorRef *error)
 355     __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 356
 357 /*!
 358  @function SecTrustGetTrustExceptionsArray
 359  @abstract Return the exceptions array currently set in the trust object
 360  @param trust A reference to the trust object
 361  @result The array of exceptions.
 362  @discussion This function returns an array of exceptions that was previously set
 363  using SecTrustSetExceptions, unlike SecTrustCopyExceptions which returns the
 364  exceptions which could be set using SecTrustSetExceptions.
 365  */
 366 __nullable CFArrayRef SecTrustGetTrustExceptionsArray(SecTrustRef trust)
 367     __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0);
 368
 369 /*!
 370  @function SecTrustCopyInputCertificates
 371  @abstract Return the array of certificates currently set in the trust object
 372  @param trust A reference to the trust object
 373  @param certificates On return, an array of the certificates used by this trust.
 374  Call the CFRelease function to release this reference.
 375  @result A result code. See "Security Error Codes" (SecBase.h)
 376 */
 377 OSStatus SecTrustCopyInputCertificates(SecTrustRef trust, CFArrayRef * _Nonnull CF_RETURNS_RETAINED certificates)
 378 __OSX_AVAILABLE(10.12.4) __IOS_AVAILABLE(10.3) __TVOS_AVAILABLE(10.2) __WATCHOS_AVAILABLE(3.2);
 379
 380 /*!
 381  @function SecTrustAddToInputCertificates
 382  @abstract Add certificate(s) to the currently set certificates in the trust object
 383  @param trust A reference to the trust object
 384  @param certificates The group of certificates to add. This can either be a CFArrayRef
 385  of SecCertificateRef objects or a single SecCertificateRef.
 386  @result A result code. See "Security Error Codes" (SecBase.h)
 387  */
 388 OSStatus SecTrustAddToInputCertificates(SecTrustRef trust, CFTypeRef _Nonnull certificates)
 389     __OSX_AVAILABLE(10.12.4) __IOS_AVAILABLE(10.3) __TVOS_AVAILABLE(10.2) __WATCHOS_AVAILABLE(3.2);
 390
 391 /*!
 392  @function SecTrustSetPinningPolicyName
 393  @abstract Set the policy name to be used during the trust evaluation.
 394  @param trust A reference to the trust object
 395  @param policyName A string representing the name of the pinning policy to be used.
 396  @result A result code. See "Security Error Codes" (SecBase.h)
 397  @discussion This function permits the caller to enable the dynamic lookup of the
 398  pinning policy using a built-in database as an alternative to using a SecPolicyCreate function
 399  with the pinning rules and calling SecTrustCreateWithCertificates or SecTrustSetPolicies.
 400  */
 401 OSStatus SecTrustSetPinningPolicyName(SecTrustRef trust, CFStringRef policyName)
 402     __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 403
 404 /*!
 405  @function SecTrustSetPinningException
 406  @abstract Remove pinning requirement from this trust evaluation
 407  @param trust A reference to the trust object
 408  @result A result code. See "Security Error Codes" (SecBase.h)
 409  @discussion This function provides an exception for this particular trust for a bundle that
 410  otherwise requires pinning for all connections. Bundles use the SecTrustPinningRequired key
 411  with boolean value of true in their info plist to indicate that all SSL connections from the
 412  bundle must be pinned.
 413  */
 414 OSStatus SecTrustSetPinningException(SecTrustRef trust)
 415     __OSX_AVAILABLE(10.13) __IOS_AVAILABLE(11.0) __TVOS_AVAILABLE(11.0) __WATCHOS_AVAILABLE(4.0);
 416
 417 /*!
 418  @function SecTrustEvaluateWithError
 419  @abstract Evaluates a trust reference synchronously.
 420  @param trust A reference to the trust object to evaluate.
 421  @param error A pointer to an error object
 422  @result A boolean value indicating whether the certificate is trusted
 423  @discussion This function will completely evaluate trust before returning,
 424  possibly including network access to fetch intermediate certificates or to
 425  perform revocation checking. Since this function can block during those
 426  operations, you should call it from within a function that is placed on a
 427  dispatch queue, or in a separate thread from your application's main
 428  run loop.
 429  If the certificate is trusted and the result is true, the error will be set to NULL.
 430  If the certificate is not trusted or the evaluation was unable to complete, the result
 431  will be false and the error will be set with a description of the failure.
 432  The error contains a code for the most serious error encountered (if multiple trust
 433  failures occurred). The localized description indicates the certificate with the most
 434  serious problem and the type of error. The underlying error contains a localized
 435  description of each certificate in the chain that had an error and all errors found
 436  with that certificate.
 437  */
 438 __attribute__((warn_unused_result)) bool
 439 SecTrustEvaluateWithError(SecTrustRef trust, CFErrorRef _Nullable * _Nullable CF_RETURNS_RETAINED error)
 440     __OSX_AVAILABLE(10.13.4) __IOS_AVAILABLE(11.3) __TVOS_AVAILABLE(11.3) __WATCHOS_AVAILABLE(4.3);
 441
 442 /*!
 443  @function SecTrustReportTLSAnalytics
 444  @discussion This function MUST NOT be called outside of the TLS stack.
 445 */
 446 bool SecTrustReportTLSAnalytics(CFStringRef eventName, xpc_object_t eventAttributes, CFErrorRef _Nullable * _Nullable CF_RETURNS_RETAINED error)
 447     __API_AVAILABLE(macos(10.13.4), ios(11.3), tvos(11.3), watchos(4.3));
 448
 449 CF_IMPLICIT_BRIDGING_DISABLED
 450 CF_ASSUME_NONNULL_END
 451
 452 /*
 453  *  Legacy functions (OS X only)
 454  */
 455 #if TARGET_OS_MAC && !TARGET_OS_IPHONE
 456
 457 CF_ASSUME_NONNULL_BEGIN
 458 CF_IMPLICIT_BRIDGING_ENABLED
 459
 460 #if SEC_OS_IPHONE
 461 #pragma clang diagnostic push
 462 #pragma clang diagnostic ignored "-Wfour-char-constants"
 463 #endif /* SEC_OS_IPHONE */
 464 /*
 465      unique keychain item attributes for user trust records.
 466  */
 467 enum {
 468     kSecTrustCertAttr                    = 'tcrt',
 469     kSecTrustPolicyAttr                  = 'tpol',
 470     /* Leopard and later */
 471     kSecTrustPubKeyAttr                  = 'tpbk',
 472     kSecTrustSignatureAttr               = 'tsig'
 473 };
 474
 475 #if SEC_OS_IPHONE
 476 #pragma clang diagnostic pop
 477 #endif /* SEC_OS_IPHONE */
 478
 479 /*!
 480      @function SecTrustGetUserTrust
 481      @abstract Gets the user-specified trust settings of a certificate and policy.
 482      @param certificate A reference to a certificate.
 483      @param policy A reference to a policy.
 484      @param trustSetting On return, a pointer to the user specified trust settings.
 485      @result A result code. See "Security Error Codes" (SecBase.h).
 486      @availability Mac OS X version 10.4. Deprecated in Mac OS X version 10.5.
 487  */
 488 OSStatus SecTrustGetUserTrust(SecCertificateRef __nullable certificate, SecPolicyRef __nullable policy, SecTrustUserSetting * __nullable trustSetting)
 489     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_4, __MAC_10_5, __IPHONE_NA, __IPHONE_NA);
 490
 491 /*!
 492      @function SecTrustSetUserTrust
 493      @abstract Sets the user-specified trust settings of a certificate and policy.
 494      @param certificate A reference to a certificate.
 495      @param policy A reference to a policy.
 496      @param trustSetting The user-specified trust settings.
 497      @result A result code. See "Security Error Codes" (SecBase.h).
 498      @availability Mac OS X version 10.4. Deprecated in Mac OS X version 10.5.
 499      @discussion as of Mac OS version 10.5, this will result in a call to
 500      SecTrustSettingsSetTrustSettings().
 501  */
 502 OSStatus SecTrustSetUserTrust(SecCertificateRef __nullable certificate, SecPolicyRef __nullable policy, SecTrustUserSetting trustSetting)
 503     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_4, __MAC_10_5, __IPHONE_NA, __IPHONE_NA);
 504
 505 /*!
 506      @function SecTrustSetUserTrustLegacy
 507      @abstract Sets the user-specified trust settings of a certificate and policy.
 508      @param certificate A reference to a certificate.
 509      @param policy A reference to a policy.
 510      @param trustSetting The user-specified trust settings.
 511      @result A result code.  See "Security Error Codes" (SecBase.h).
 512
 513      @This is the private version of what used to be SecTrustSetUserTrust(); it operates
 514      on UserTrust entries as that function used to. The current SecTrustSetUserTrust()
 515      function operated on Trust Settings.
 516  */
 517 OSStatus SecTrustSetUserTrustLegacy(SecCertificateRef __nullable certificate, SecPolicyRef __nullable policy, SecTrustUserSetting trustSetting)
 518     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_5, __MAC_10_12, __IPHONE_NA, __IPHONE_NA);
 519
 520 /*!
 521      @function SecTrustGetCSSMAnchorCertificates
 522      @abstract Retrieves the CSSM anchor certificates.
 523      @param cssmAnchors A pointer to an array of anchor certificates.
 524      @param cssmAnchorCount A pointer to the number of certificates in anchors.
 525      @result A result code. See "Security Error Codes" (SecBase.h).
 526      @availability Mac OS X version 10.4. Deprecated in Mac OS X version 10.5.
 527  */
 528 OSStatus SecTrustGetCSSMAnchorCertificates(const CSSM_DATA * __nullable * __nullable cssmAnchors, uint32 *cssmAnchorCount)
 529     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_4, __MAC_10_5, __IPHONE_NA, __IPHONE_NA);
 530
 531 /*!
 532      @function SecTrustCopyExtendedResult
 533      @abstract Gets the extended trust result after an evaluation has been performed.
 534      @param trust A trust reference.
 535      @param result On return, result points to a CFDictionaryRef containing extended trust results (if no error occurred).
 536      The caller is responsible for releasing this dictionary with CFRelease when finished with it.
 537      @result A result code. See "Security Error Codes" (SecBase.h).
 538      @discussion This function may only be used after SecTrustEvaluate has been called for the trust reference, otherwise
 539      errSecTrustNotAvailable is returned. If the certificate is not an extended validation certificate, there is
 540      no extended result data and errSecDataNotAvailable is returned. Currently, only one dictionary key is defined
 541      (kSecEVOrganizationName).
 542
 543      Note: this function will be deprecated in a future release of OS X. Your
 544      code should use SecTrustCopyResult to obtain the trust results dictionary.
 545  */
 546 OSStatus SecTrustCopyExtendedResult(SecTrustRef trust, CFDictionaryRef * __nonnull CF_RETURNS_RETAINED result)
 547     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_5, __MAC_10_12, __IPHONE_NA, __IPHONE_NA);
 548
 549 /*
 550  * Preference-related strings for Revocation policies.
 551  */
 552
 553 /*
 554  * Preference domain, i.e., the name of a plist in ~/Library/Preferences or in
 555  * /Library/Preferences
 556  */
 557 #define kSecRevocationDomain                "com.apple.security.revocation"
 558
 559 /* OCSP and CRL style keys, followed by values used for both of them */
 560 #define kSecRevocationOcspStyle             CFSTR("OCSPStyle")
 561 #define kSecRevocationCrlStyle              CFSTR("CRLStyle")
 562 #define kSecRevocationOff                   CFSTR("None")
 563 #define kSecRevocationBestAttempt           CFSTR("BestAttempt")
 564 #define kSecRevocationRequireIfPresent      CFSTR("RequireIfPresent")
 565 #define kSecRevocationRequireForAll         CFSTR("RequireForAll")
 566
 567 /* Which first if both enabled? */
 568 #define kSecRevocationWhichFirst            CFSTR("RevocationFirst")
 569 #define kSecRevocationOcspFirst             CFSTR("OCSP")
 570 #define kSecRevocationCrlFirst              CFSTR("CRL")
 571
 572 /* boolean: A "this policy is sufficient per cert" for each */
 573 #define kSecRevocationOCSPSufficientPerCert CFSTR("OCSPSufficientPerCert")
 574 #define kSecRevocationCRLSufficientPerCert  CFSTR("CRLSufficientPerCert")
 575
 576 /* local OCSP responder URI, value arbitrary string value */
 577 #define kSecOCSPLocalResponder              CFSTR("OCSPLocalResponder")
 578
 579 /* Extended trust result keys (now in public API) */
 580 #define kSecEVOrganizationName              kSecTrustOrganizationName
 581 #define kSecTrustExpirationDate             kSecTrustRevocationValidUntilDate
 582
 583 CF_IMPLICIT_BRIDGING_DISABLED
 584 CF_ASSUME_NONNULL_END
 585
 586 #endif /* TARGET_OS_MAC && !TARGET_OS_IPHONE */
 587
 588 __END_DECLS
 589
 590 #endif /* !_SECURITY_SECTRUSTPRIV_H_ */