X-Git-Url: https://git.saurik.com/apple/security.git/blobdiff_plain/b04fe171f0375ecd5d8a24747ca1dff85720a0ca..6b200bc335dc93c5516ccb52f14bd896d8c7fad7:/OSX/sec/Security/SecTrustPriv.h diff --git a/OSX/sec/Security/SecTrustPriv.h b/OSX/sec/Security/SecTrustPriv.h deleted file mode 100644 index 314932e3..00000000 --- a/OSX/sec/Security/SecTrustPriv.h +++ /dev/null @@ -1,454 +0,0 @@ -/* - * Copyright (c) 2003-2016 Apple Inc. All Rights Reserved. - * - * @APPLE_LICENSE_HEADER_START@ - * - * This file contains Original Code and/or Modifications of Original Code - * as defined in and that are subject to the Apple Public Source License - * Version 2.0 (the 'License'). You may not use this file except in - * compliance with the License. Please obtain a copy of the License at - * http://www.opensource.apple.com/apsl/ and read it before using this - * file. - * - * The Original Code and all software distributed under the License are - * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER - * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, - * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. - * Please see the License for the specific language governing rights and - * limitations under the License. - * - * @APPLE_LICENSE_HEADER_END@ - */ - -/*! - @header SecTrustPriv - The functions and data types in SecTrustPriv implement trust computation - and allow the user to apply trust decisions to the trust configuration. -*/ - -#ifndef _SECURITY_SECTRUSTPRIV_H_ -#define _SECURITY_SECTRUSTPRIV_H_ - -#include -#include -#include -#include - -__BEGIN_DECLS - -CF_ASSUME_NONNULL_BEGIN -CF_IMPLICIT_BRIDGING_ENABLED - -/* Constants used as keys in property lists. See - SecTrustCopySummaryPropertiesAtIndex for more information. */ -extern const CFStringRef kSecPropertyKeyType; -extern const CFStringRef kSecPropertyKeyLabel; -extern const CFStringRef kSecPropertyKeyLocalizedLabel; -extern const CFStringRef kSecPropertyKeyValue; - -extern const CFStringRef kSecPropertyTypeWarning; -extern const CFStringRef kSecPropertyTypeSuccess; -extern const CFStringRef kSecPropertyTypeSection; -extern const CFStringRef kSecPropertyTypeData; -extern const CFStringRef kSecPropertyTypeString; -extern const CFStringRef kSecPropertyTypeURL; -extern const CFStringRef kSecPropertyTypeDate; - -/* Constants used as keys in the dictionary returned by SecTrustCopyInfo. */ -extern const CFStringRef kSecTrustInfoExtendedValidationKey; -extern const CFStringRef kSecTrustInfoCompanyNameKey; -extern const CFStringRef kSecTrustInfoRevocationKey; -extern const CFStringRef kSecTrustInfoRevocationValidUntilKey; -extern const CFStringRef kSecTrustInfoCertificateTransparencyKey; -extern const CFStringRef kSecTrustInfoCertificateTransparencyWhiteListKey; - -/*! - @enum Trust Result Constants - @discussion Predefined key constants used to obtain values in a - dictionary of trust evaluation results for a certificate chain, - as retrieved from a call to SecTrustCopyResult. - - @constant kSecTrustResultDetails - This key will be present if a trust evaluation has been performed. - Its value is a CFArrayRef of CFDictionaryRef representing detailed - status info for each certificate in the completed chain. - @constant kSecTrustRevocationReason - This key will be present iff this chain had its revocation checked, - and a "revoked" response was received. The value of this key will - be a CFNumberRef indicating the reason for revocation. The possible - reason code values are described in RFC 5280, section 5.3.1. - */ -extern const CFStringRef kSecTrustResultDetails; - /*__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_9_0);*/ -extern const CFStringRef kSecTrustRevocationReason; - /*__OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);*/ - -/*! - @function SecTrustCopySummaryPropertiesAtIndex - @abstract Return a property array for the certificate. - @param trust A reference to the trust object to evaluate. - @param ix The index of the requested certificate. Indices run from 0 - (leaf) to the anchor (or last certificate found if no anchor was found). - @result A property array. It is the caller's responsibility to CFRelease - the returned array when it is no longer needed. This function returns a - short summary description of the certificate in question. The property - at index 0 of the array might also include general information about the - entire chain's validity in the context of this trust evaluation. - - @discussion Returns a property array for this trust certificate. A property - array is an array of CFDictionaryRefs. Each dictionary (we call it a - property for short) has the following keys: - - kSecPropertyKeyType This key's value determines how this property - should be displayed. Its associated value is one of the - following: - kSecPropertyTypeWarning - The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not - set. The kSecPropertyKeyValue is a CFStringRef which should - be displayed in yellow with a warning triangle. - kSecPropertyTypeError - The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not - set. The kSecPropertyKeyValue is a CFStringRef which should - be displayed in red with an error X. - kSecPropertyTypeSuccess - The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not - set. The kSecPropertyKeyValue is a CFStringRef which should - be displayed in green with a checkmark in front of it. - kSecPropertyTypeTitle - The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not - set. The kSecPropertyKeyValue is a CFStringRef which should - be displayed in a larger bold font. - kSecPropertyTypeSection - The optional kSecPropertyKeyLocalizedLabel is a CFStringRef with the name - of the next section to display. The value of the - kSecPropertyKeyValue key is a CFArrayRef which is a property - array as defined here. - kSecPropertyTypeData - The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing - the localized label for the value for the kSecPropertyKeyValue. - The type of this value is a CFDataRef. Its contents should be - displayed as: "bytes length_of_data : hexdump_of_data". Ideally - the UI will only show one line of hex dump data and have a - disclosure arrow to see the remainder. - kSecPropertyTypeString - The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing - the localized label for the value for the kSecPropertyKeyValue. - The type of this value is a CFStringRef. It's contents should be - displayed in the normal font. - kSecPropertyTypeURL - The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing - the localized label for the value for the kSecPropertyKeyValue. - The type of this value is a CFURLRef. It's contents should be - displayed as a hyperlink. - kSecPropertyTypeDate - The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing - the localized label for the value for the kSecPropertyKeyValue. - The type of this value is a CFDateRef. It's contents should be - displayed in human readable form (probably in the current - timezone). - kSecPropertyKeyLocalizedLabel - Human readable localized label for a given property. - kSecPropertyKeyValue - See description of kSecPropertyKeyType to determine what the value - for this key is. - kSecPropertyKeyLabel - Non localized key (label) for this value. This is only - present for properties with fixed label names. - @param certificate A reference to the certificate to evaluate. - @result A property array. It is the caller's responsability to CFRelease - the returned array when it is no longer needed. -*/ -__nullable CF_RETURNS_RETAINED -CFArrayRef SecTrustCopySummaryPropertiesAtIndex(SecTrustRef trust, CFIndex ix); - -/*! - @function SecTrustCopyDetailedPropertiesAtIndex - @abstract Return a property array for the certificate. - @param trust A reference to the trust object to evaluate. - @param ix The index of the requested certificate. Indices run from 0 - (leaf) to the anchor (or last certificate found if no anchor was found). - @result A property array. It is the caller's responsibility to CFRelease - the returned array when it is no longer needed. - See SecTrustCopySummaryPropertiesAtIndex on how to intepret this array. - Unlike that function call this function returns a detailed description - of the certificate in question. -*/ -__nullable CF_RETURNS_RETAINED -CFArrayRef SecTrustCopyDetailedPropertiesAtIndex(SecTrustRef trust, CFIndex ix); - -/*! - @function SecTrustCopyInfo - @abstract Return a dictionary with additional information about the - evaluated certificate chain for use by clients. - @param trust A reference to an evaluated trust object. - @discussion Returns a dictionary for this trust evaluation. This - dictionary may have the following keys: - - kSecTrustInfoExtendedValidationKey this key will be present and have - a value of kCFBooleanTrue if this chain was validated for EV. - kSecTrustInfoCompanyNameKey Company name field of subject of leaf - certificate, this field is meant to be displayed to the user - if the kSecTrustInfoExtendedValidationKey is present. - kSecTrustInfoRevocationKey this key will be present iff this chain - had its revocation checked. The value will be a kCFBooleanTrue - if revocation checking was successful and none of the - certificates in the chain were revoked. - The value will be kCFBooleanFalse if no current revocation status - could be obtained for one or more certificates in the chain due - to connection problems or timeouts etc. This is a hint to a - client to retry revocation checking at a later time. - kSecTrustInfoRevocationValidUntilKey this key will be present iff - kSecTrustInfoRevocationKey has a value of kCFBooleanTrue. - The value will be a CFDateRef representing the earliest date at - which the revocation info for one of the certificates in this chain - might change. - - @result A dictionary with various fields that can be displayed to the user, - or NULL if no additional info is available or the trust has not yet been - validated. The caller is responsible for calling CFRelease on the value - returned when it is no longer needed. -*/ -__nullable CF_RETURNS_RETAINED -CFDictionaryRef SecTrustCopyInfo(SecTrustRef trust); - -/* For debugging purposes. */ -__nullable CF_RETURNS_RETAINED -CFArrayRef SecTrustGetDetails(SecTrustRef trust); - -/* For debugging purposes. */ -__nullable CF_RETURNS_RETAINED -CFStringRef SecTrustCopyFailureDescription(SecTrustRef trust); - -OSStatus SecTrustGetOTAPKIAssetVersionNumber(int* versionNumber); - -OSStatus SecTrustOTAPKIGetUpdatedAsset(int* didUpdateAsset); - -/*! - @function SecTrustSignedCertificateTimestampList - @abstract Attach SignedCertificateTimestampList data to a trust object. - @param trust A reference to a trust object. - @param sctArray is a CFArray of CFData objects each containing a SCT (per RFC 6962). - @result A result code. See "Security Error Codes" (SecBase.h). - @discussion Allows the caller to provide SCT data (which may be - obtained during a TLS/SSL handshake, per RFC 6962) as input to a trust - evaluation. - */ -OSStatus SecTrustSetSignedCertificateTimestamps(SecTrustRef trust, CFArrayRef sctArray); - -/*! - @function SecTrustSetTrustedLogs - @abstract Sets the trusted CT logs for a given trust. - @param trust A reference to a trust object. - @param trustedLogs An array of trusted logs. - @result A result code. See "Security Error Codes" (SecBase.h). - @discussion trustedLog is a CFArray of CFData containing the DER-encode SubjectPublicKeyInfo - of the trusted CT logs. - */ -OSStatus SecTrustSetTrustedLogs(SecTrustRef trust, CFArrayRef trustedLogs); - -/* Keychain searches are allowed by default. Use this to turn off seaching of - -keychain search list (i.e. login.keychain, system.keychain) - -Local Items/iCloud Keychain - -user- and admin-trusted roots - -network-fetched issuers - User must provide all necessary certificates in the input certificates and/or anchors. */ -OSStatus SecTrustSetKeychainsAllowed(SecTrustRef trust, Boolean allowed) - __OSX_AVAILABLE(__MAC_10_12) __IOS_AVAILABLE(__IPHONE_10_0) __TVOS_AVAILABLE(__TVOS_10_0) __WATCHOS_AVAILABLE(__WATCHOS_3_0); - -/* Get the keychain search policy for the trust object. */ -OSStatus SecTrustGetKeychainsAllowed(SecTrustRef trust, Boolean * __nonnull allowed) - __OSX_AVAILABLE(__MAC_10_12) __IOS_AVAILABLE(__IPHONE_10_0) __TVOS_AVAILABLE(__TVOS_10_0) __WATCHOS_AVAILABLE(__WATCHOS_3_0); - -/*! - @function SecTrustEvaluateLeafOnly - @abstract Evaluates the leaf of the trust reference synchronously. - @param trust A reference to the trust object to evaluate. - @param result A pointer to a result type. - @result A result code. See "Security Error Codes" (SecBase.h). - @discussion This function will only evaluate the trust of the leaf certificate. - No chain will be built and only those aspects of the SecPolicyRef that address - the expected contents of the leaf will be checked. This function does not honor - any set exceptions. - */ -OSStatus SecTrustEvaluateLeafOnly(SecTrustRef trust, SecTrustResultType * __nonnull result) - __OSX_AVAILABLE(__MAC_10_12) __IOS_AVAILABLE(__IPHONE_10_0) __TVOS_AVAILABLE(__TVOS_10_0) __WATCHOS_AVAILABLE(__WATCHOS_3_0); - -/*! - @function SecTrustSerialize - @abstract Creates a serialized version of the trust object - @param trust A reference to the trust object to serialize. - @param error A pointer to an error. - @result The serialized trust object. - @discussion This function is intended to be used to share SecTrustRefs between - processes. Saving the results to disk or sending them over network channels - may cause unexpected behavior. - */ -__nullable CF_RETURNS_RETAINED -CFDataRef SecTrustSerialize(SecTrustRef trust, CFErrorRef *error) - __OSX_AVAILABLE(__MAC_10_12) __IOS_AVAILABLE(__IPHONE_10_0) __TVOS_AVAILABLE(__TVOS_10_0) __WATCHOS_AVAILABLE(__WATCHOS_3_0); - -/*! - @function SecTrustDeserialize - @abstract Creates a trust object from the serialized data - @param serialiedTrust A reference to the serialized trust object - @param error A pointer to an error. - @result A trust object - @discussion This function is intended to be used to share SecTrustRefs between - processes. Saving the results to disk or sending them over network channels - may cause unexpected behavior. - */ -__nullable CF_RETURNS_RETAINED -SecTrustRef SecTrustDeserialize(CFDataRef serializedTrust, CFErrorRef *error) - __OSX_AVAILABLE(__MAC_10_12) __IOS_AVAILABLE(__IPHONE_10_0) __TVOS_AVAILABLE(__TVOS_10_0) __WATCHOS_AVAILABLE(__WATCHOS_3_0); - -/*! - @function SecTrustGetTrustExceptionsArray - @abstract Return the exceptions array current set in the trust object - @param trust A reference to the trust object - @result The array of exceptions. - @discussion This function returns an array of exceptions that was previously set - using SecTrustSetExceptions, unlike SecTrustCopyExceptions which returns the - exceptions which could be set using SecTrustSetExceptions. - */ -__nullable CFArrayRef SecTrustGetTrustExceptionsArray(SecTrustRef trust) - __OSX_AVAILABLE(__MAC_10_12) __IOS_AVAILABLE(__IPHONE_10_0) __TVOS_AVAILABLE(__TVOS_10_0) __WATCHOS_AVAILABLE(__WATCHOS_3_0); - -CF_IMPLICIT_BRIDGING_DISABLED -CF_ASSUME_NONNULL_END - -/* - * Legacy functions (OS X only) - */ -#if TARGET_OS_MAC && !TARGET_OS_IPHONE - -CF_ASSUME_NONNULL_BEGIN -CF_IMPLICIT_BRIDGING_ENABLED - -#pragma clang diagnostic push -#pragma clang diagnostic ignored "-Wfour-char-constants" -/* - unique keychain item attributes for user trust records. - */ -enum { - kSecTrustCertAttr = 'tcrt', - kSecTrustPolicyAttr = 'tpol', - /* Leopard and later */ - kSecTrustPubKeyAttr = 'tpbk', - kSecTrustSignatureAttr = 'tsig' -}; - -#pragma clang diagnostic pop - -/*! - @function SecTrustGetUserTrust - @abstract Gets the user-specified trust settings of a certificate and policy. - @param certificate A reference to a certificate. - @param policy A reference to a policy. - @param trustSetting On return, a pointer to the user specified trust settings. - @result A result code. See "Security Error Codes" (SecBase.h). - @availability Mac OS X version 10.4. Deprecated in Mac OS X version 10.5. - */ -OSStatus SecTrustGetUserTrust(SecCertificateRef __nullable certificate, SecPolicyRef __nullable policy, SecTrustUserSetting * __nullable trustSetting) - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_4, __MAC_10_5, __IPHONE_NA, __IPHONE_NA); - -/*! - @function SecTrustSetUserTrust - @abstract Sets the user-specified trust settings of a certificate and policy. - @param certificate A reference to a certificate. - @param policy A reference to a policy. - @param trustSetting The user-specified trust settings. - @result A result code. See "Security Error Codes" (SecBase.h). - @availability Mac OS X version 10.4. Deprecated in Mac OS X version 10.5. - @discussion as of Mac OS version 10.5, this will result in a call to - SecTrustSettingsSetTrustSettings(). - */ -OSStatus SecTrustSetUserTrust(SecCertificateRef __nullable certificate, SecPolicyRef __nullable policy, SecTrustUserSetting trustSetting) - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_4, __MAC_10_5, __IPHONE_NA, __IPHONE_NA); - -/*! - @function SecTrustSetUserTrustLegacy - @abstract Sets the user-specified trust settings of a certificate and policy. - @param certificate A reference to a certificate. - @param policy A reference to a policy. - @param trustSetting The user-specified trust settings. - @result A result code. See "Security Error Codes" (SecBase.h). - - @This is the private version of what used to be SecTrustSetUserTrust(); it operates - on UserTrust entries as that function used to. The current SecTrustSetUserTrust() - function operated on Trust Settings. - */ -OSStatus SecTrustSetUserTrustLegacy(SecCertificateRef __nullable certificate, SecPolicyRef __nullable policy, SecTrustUserSetting trustSetting) - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_5, __MAC_10_12, __IPHONE_NA, __IPHONE_NA); - -/*! - @function SecTrustGetCSSMAnchorCertificates - @abstract Retrieves the CSSM anchor certificates. - @param cssmAnchors A pointer to an array of anchor certificates. - @param cssmAnchorCount A pointer to the number of certificates in anchors. - @result A result code. See "Security Error Codes" (SecBase.h). - @availability Mac OS X version 10.4. Deprecated in Mac OS X version 10.5. - */ -OSStatus SecTrustGetCSSMAnchorCertificates(const CSSM_DATA * __nullable * __nullable cssmAnchors, uint32 *cssmAnchorCount) - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_4, __MAC_10_5, __IPHONE_NA, __IPHONE_NA); - -/*! - @function SecTrustCopyExtendedResult - @abstract Gets the extended trust result after an evaluation has been performed. - @param trust A trust reference. - @param result On return, result points to a CFDictionaryRef containing extended trust results (if no error occurred). - The caller is responsible for releasing this dictionary with CFRelease when finished with it. - @result A result code. See "Security Error Codes" (SecBase.h). - @discussion This function may only be used after SecTrustEvaluate has been called for the trust reference, otherwise - errSecTrustNotAvailable is returned. If the certificate is not an extended validation certificate, there is - no extended result data and errSecDataNotAvailable is returned. Currently, only one dictionary key is defined - (kSecEVOrganizationName). - - Note: this function will be deprecated in a future release of OS X. Your - code should use SecTrustCopyResult to obtain the trust results dictionary. - */ -OSStatus SecTrustCopyExtendedResult(SecTrustRef trust, CFDictionaryRef * __nonnull CF_RETURNS_RETAINED result) - __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_5, __MAC_10_12, __IPHONE_NA, __IPHONE_NA); - -/* - * Preference-related strings for Revocation policies. - */ - -/* - * Preference domain, i.e., the name of a plist in ~/Library/Preferences or in - * /Library/Preferences - */ -#define kSecRevocationDomain "com.apple.security.revocation" - -/* OCSP and CRL style keys, followed by values used for both of them */ -#define kSecRevocationOcspStyle CFSTR("OCSPStyle") -#define kSecRevocationCrlStyle CFSTR("CRLStyle") -#define kSecRevocationOff CFSTR("None") -#define kSecRevocationBestAttempt CFSTR("BestAttempt") -#define kSecRevocationRequireIfPresent CFSTR("RequireIfPresent") -#define kSecRevocationRequireForAll CFSTR("RequireForAll") - -/* Which first if both enabled? */ -#define kSecRevocationWhichFirst CFSTR("RevocationFirst") -#define kSecRevocationOcspFirst CFSTR("OCSP") -#define kSecRevocationCrlFirst CFSTR("CRL") - -/* boolean: A "this policy is sufficient per cert" for each */ -#define kSecRevocationOCSPSufficientPerCert CFSTR("OCSPSufficientPerCert") -#define kSecRevocationCRLSufficientPerCert CFSTR("CRLSufficientPerCert") - -/* local OCSP responder URI, value arbitrary string value */ -#define kSecOCSPLocalResponder CFSTR("OCSPLocalResponder") - -/* Extended trust result keys (now in public API) */ -#define kSecEVOrganizationName kSecTrustOrganizationName -#define kSecTrustExpirationDate kSecTrustRevocationValidUntilDate - -CF_IMPLICIT_BRIDGING_DISABLED -CF_ASSUME_NONNULL_END - -#endif /* TARGET_OS_MAC && !TARGET_OS_IPHONE */ - -__END_DECLS - -#endif /* !_SECURITY_SECTRUSTPRIV_H_ */