X-Git-Url: https://git.saurik.com/apple/security.git/blobdiff_plain/5dd5f9ec28f304ca377c42fd7f711d6cf12b90e1..5c19dc3ae3bd8e40a9c028b0deddd50ff337692c:/OSX/sec/Security/SecTrustPriv.h diff --git a/OSX/sec/Security/SecTrustPriv.h b/OSX/sec/Security/SecTrustPriv.h new file mode 100644 index 00000000..4ace97aa --- /dev/null +++ b/OSX/sec/Security/SecTrustPriv.h @@ -0,0 +1,274 @@ +/* + * Copyright (c) 2008-2015 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 + +__BEGIN_DECLS + +typedef enum { + useNetworkDefault, // default policy: network fetch enabled only for SSL + useNetworkDisabled, // explicitly disable network use for any policy + useNetworkEnabled // explicitly enable network use for any policy +} SecNetworkPolicy; + +/* 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; + +/*! + @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. +*/ +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. +*/ +CFArrayRef SecTrustCopyDetailedPropertiesAtIndex(SecTrustRef trust, CFIndex ix); + +/*! + @function SecTrustCopyProperties + @abstract Return a property array for this trust evaluation. + @param trust A reference to the trust object to evaluate. + @result A property array. It is the caller's responsibility to CFRelease + the returned array when it is no longer needed. See + SecTrustCopySummaryPropertiesAtIndex for a detailed description of this array. + Unlike that function, this function returns a short text string suitable for + display in a sheet explaining to the user why this certificate chain is + not trusted for this operation. This function may return NULL if the + certificate chain was trusted. +*/ +CFArrayRef SecTrustCopyProperties(SecTrustRef trust); + +/*! + @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. +*/ +CFDictionaryRef SecTrustCopyInfo(SecTrustRef trust); + +/* For debugging purposes. */ +CFArrayRef SecTrustGetDetails(SecTrustRef trust); + +/* For debugging purposes. */ +CFStringRef SecTrustCopyFailureDescription(SecTrustRef trust); + +/*! + @function SecTrustSetPolicies + @abstract Set the trust policies against which the trust should be verified. + @param trust A reference to a trust object. + @param policies An array of one or more policies. You may pass a + SecPolicyRef to represent a single policy. + @result A result code. See "Security Error Codes" (SecBase.h). + @discussion This function does not invalidate the trust, but should do so in the future. +*/ +OSStatus SecTrustSetPolicies(SecTrustRef trust, CFTypeRef policies) + __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_6_0); + +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); + +__END_DECLS + +#endif /* !_SECURITY_SECTRUSTPRIV_H_ */