1/* 2 * Copyright (c) 2008-2013 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/CFData.h> 35#include <CoreFoundation/CFDictionary.h> 36 37__BEGIN_DECLS 38 39typedef enum { 40 useNetworkDefault, // default policy: network fetch enabled only for SSL 41 useNetworkDisabled, // explicitly disable network use for any policy 42 useNetworkEnabled // explicitly enable network use for any policy 43} SecNetworkPolicy; 44 45/* Constants used as keys in property lists. See 46 SecTrustCopySummaryPropertiesAtIndex for more information. */ 47extern CFTypeRef kSecPropertyKeyType; 48extern CFTypeRef kSecPropertyKeyLabel; 49extern CFTypeRef kSecPropertyKeyLocalizedLabel; 50extern CFTypeRef kSecPropertyKeyValue; 51 52extern CFTypeRef kSecPropertyTypeWarning; 53extern CFTypeRef kSecPropertyTypeSuccess; 54extern CFTypeRef kSecPropertyTypeSection; 55extern CFTypeRef kSecPropertyTypeData; 56extern CFTypeRef kSecPropertyTypeString; 57extern CFTypeRef kSecPropertyTypeURL; 58extern CFTypeRef kSecPropertyTypeDate; 59 60/* Constants used as keys in the dictionary returned by SecTrustCopyInfo. */ 61extern CFTypeRef kSecTrustInfoExtendedValidationKey; 62extern CFTypeRef kSecTrustInfoCompanyNameKey; 63extern CFTypeRef kSecTrustInfoRevocationKey; 64extern CFTypeRef kSecTrustInfoRevocationValidUntilKey; 65 66/*! 67 @function SecTrustCopySummaryPropertiesAtIndex 68 @abstract Return a property array for the certificate. 69 @param trust A reference to the trust object to evaluate. 70 @param ix The index of the requested certificate. Indices run from 0 71 (leaf) to the anchor (or last certificate found if no anchor was found). 72 @result A property array. It is the caller's responsibility to CFRelease 73 the returned array when it is no longer needed. This function returns a 74 short summary description of the certificate in question. The property 75 at index 0 of the array might also include general information about the 76 entire chain's validity in the context of this trust evaluation. 77 78 @discussion Returns a property array for this trust certificate. A property 79 array is an array of CFDictionaryRefs. Each dictionary (we call it a 80 property for short) has the following keys: 81 82 kSecPropertyKeyType This key's value determines how this property 83 should be displayed. Its associated value is one of the 84 following: 85 kSecPropertyTypeWarning 86 The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not 87 set. The kSecPropertyKeyValue is a CFStringRef which should 88 be displayed in yellow with a warning triangle. 89 kSecPropertyTypeError 90 The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not 91 set. The kSecPropertyKeyValue is a CFStringRef which should 92 be displayed in red with an error X. 93 kSecPropertyTypeSuccess 94 The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not 95 set. The kSecPropertyKeyValue is a CFStringRef which should 96 be displayed in green with a checkmark in front of it. 97 kSecPropertyTypeTitle 98 The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not 99 set. The kSecPropertyKeyValue is a CFStringRef which should 100 be displayed in a larger bold font. 101 kSecPropertyTypeSection 102 The optional kSecPropertyKeyLocalizedLabel is a CFStringRef with the name 103 of the next section to display. The value of the 104 kSecPropertyKeyValue key is a CFArrayRef which is a property 105 array as defined here. 106 kSecPropertyTypeData 107 The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing 108 the localized label for the value for the kSecPropertyKeyValue. 109 The type of this value is a CFDataRef. Its contents should be 110 displayed as: "bytes length_of_data : hexdump_of_data". Ideally 111 the UI will only show one line of hex dump data and have a 112 disclosure arrow to see the remainder. 113 kSecPropertyTypeString 114 The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing 115 the localized label for the value for the kSecPropertyKeyValue. 116 The type of this value is a CFStringRef. It's contents should be 117 displayed in the normal font. 118 kSecPropertyTypeURL 119 The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing 120 the localized label for the value for the kSecPropertyKeyValue. 121 The type of this value is a CFURLRef. It's contents should be 122 displayed as a hyperlink. 123 kSecPropertyTypeDate 124 The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing 125 the localized label for the value for the kSecPropertyKeyValue. 126 The type of this value is a CFDateRef. It's contents should be 127 displayed in human readable form (probably in the current 128 timezone). 129 kSecPropertyKeyLocalizedLabel 130 Human readable localized label for a given property. 131 kSecPropertyKeyValue 132 See description of kSecPropertyKeyType to determine what the value 133 for this key is. 134 kSecPropertyKeyLabel 135 Non localized key (label) for this value. This is only 136 present for properties with fixed label names. 137 @param certificate A reference to the certificate to evaluate. 138 @result A property array. It is the caller's responsability to CFRelease 139 the returned array when it is no longer needed. 140*/ 141CFArrayRef SecTrustCopySummaryPropertiesAtIndex(SecTrustRef trust, CFIndex ix); 142 143/*! 144 @function SecTrustCopyDetailedPropertiesAtIndex 145 @abstract Return a property array for the certificate. 146 @param trust A reference to the trust object to evaluate. 147 @param ix The index of the requested certificate. Indices run from 0 148 (leaf) to the anchor (or last certificate found if no anchor was found). 149 @result A property array. It is the caller's responsibility to CFRelease 150 the returned array when it is no longer needed. 151 See SecTrustCopySummaryPropertiesAtIndex on how to intepret this array. 152 Unlike that function call this function returns a detailed description 153 of the certificate in question. 154*/ 155CFArrayRef SecTrustCopyDetailedPropertiesAtIndex(SecTrustRef trust, CFIndex ix); 156 157/*! 158 @function SecTrustCopyProperties 159 @abstract Return a property array for this trust evaluation. 160 @param trust A reference to the trust object to evaluate. 161 @result A property array. It is the caller's responsibility to CFRelease 162 the returned array when it is no longer needed. See 163 SecTrustCopySummaryPropertiesAtIndex for a detailed description of this array. 164 Unlike that function, this function returns a short text string suitable for 165 display in a sheet explaining to the user why this certificate chain is 166 not trusted for this operation. This function may return NULL if the 167 certificate chain was trusted. 168*/ 169CFArrayRef SecTrustCopyProperties(SecTrustRef trust); 170 171/*! 172 @function SecTrustCopyInfo 173 @abstract Return a dictionary with additional information about the 174 evaluated certificate chain for use by clients. 175 @param trust A reference to an evaluated trust object. 176 @discussion Returns a dictionary for this trust evaluation. This 177 dictionary may have the following keys: 178 179 kSecTrustInfoExtendedValidationKey this key will be present and have 180 a value of kCFBooleanTrue if this chain was validated for EV. 181 kSecTrustInfoCompanyNameKey Company name field of subject of leaf 182 certificate, this field is meant to be displayed to the user 183 if the kSecTrustInfoExtendedValidationKey is present. 184 kSecTrustInfoRevocationKey this key will be present iff this chain 185 had its revocation checked. The value will be a kCFBooleanTrue 186 if revocation checking was successful and none of the 187 certificates in the chain were revoked. 188 The value will be kCFBooleanFalse if no current revocation status 189 could be obtained for one or more certificates in the chain due 190 to connection problems or timeouts etc. This is a hint to a 191 client to retry revocation checking at a later time. 192 kSecTrustInfoRevocationValidUntilKey this key will be present iff 193 kSecTrustInfoRevocationKey has a value of kCFBooleanTrue. 194 The value will be a CFDateRef representing the earliest date at 195 which the revocation info for one of the certificates in this chain 196 might change. 197 198 @result A dictionary with various fields that can be displayed to the user, 199 or NULL if no additional info is available or the trust has not yet been 200 validated. The caller is responsible for calling CFRelease on the value 201 returned when it is no longer needed. 202*/ 203CFDictionaryRef SecTrustCopyInfo(SecTrustRef trust); 204 205/* For debugging purposes. */ 206CFArrayRef SecTrustGetDetails(SecTrustRef trust); 207 208/* For debugging purposes. */ 209CFStringRef SecTrustCopyFailureDescription(SecTrustRef trust); 210 211/*! 212 @function SecTrustSetPolicies 213 @abstract Set the trust policies against which the trust should be verified. 214 @param trust A reference to a trust object. 215 @param policies An array of one or more policies. You may pass a 216 SecPolicyRef to represent a single policy. 217 @result A result code. See "Security Error Codes" (SecBase.h). 218 @discussion This function does not invalidate the trust, but should do so in the future. 219*/ 220OSStatus SecTrustSetPolicies(SecTrustRef trust, CFTypeRef policies) 221 __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_6_0); 222 223OSStatus SecTrustGetOTAPKIAssetVersionNumber(int* versionNumber); 224 225OSStatus SecTrustOTAPKIGetUpdatedAsset(int* didUpdateAsset); 226 227__END_DECLS 228 229#endif /* !_SECURITY_SECTRUSTPRIV_H_ */ 230