2 * Copyright (c) 2003-2016 Apple Inc. All Rights Reserved.
4 * @APPLE_LICENSE_HEADER_START@
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
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.
21 * @APPLE_LICENSE_HEADER_END@
26 The functions and data types in SecTrustPriv implement trust computation
27 and allow the user to apply trust decisions to the trust configuration.
30 #ifndef _SECURITY_SECTRUSTPRIV_H_
31 #define _SECURITY_SECTRUSTPRIV_H_
33 #include <Security/SecTrust.h>
34 #include <CoreFoundation/CFString.h>
35 #include <CoreFoundation/CFData.h>
36 #include <CoreFoundation/CFDictionary.h>
40 CF_ASSUME_NONNULL_BEGIN
41 CF_IMPLICIT_BRIDGING_ENABLED
43 /* Constants used as keys in property lists. See
44 SecTrustCopySummaryPropertiesAtIndex for more information. */
45 extern const CFStringRef kSecPropertyKeyType
;
46 extern const CFStringRef kSecPropertyKeyLabel
;
47 extern const CFStringRef kSecPropertyKeyLocalizedLabel
;
48 extern const CFStringRef kSecPropertyKeyValue
;
50 extern const CFStringRef kSecPropertyTypeWarning
;
51 extern const CFStringRef kSecPropertyTypeSuccess
;
52 extern const CFStringRef kSecPropertyTypeSection
;
53 extern const CFStringRef kSecPropertyTypeData
;
54 extern const CFStringRef kSecPropertyTypeString
;
55 extern const CFStringRef kSecPropertyTypeURL
;
56 extern const CFStringRef kSecPropertyTypeDate
;
58 /* Constants used as keys in the dictionary returned by SecTrustCopyInfo. */
59 extern const CFStringRef kSecTrustInfoExtendedValidationKey
;
60 extern const CFStringRef kSecTrustInfoCompanyNameKey
;
61 extern const CFStringRef kSecTrustInfoRevocationKey
;
62 extern const CFStringRef kSecTrustInfoRevocationValidUntilKey
;
63 extern const CFStringRef kSecTrustInfoCertificateTransparencyKey
;
64 extern const CFStringRef kSecTrustInfoCertificateTransparencyWhiteListKey
;
67 @enum Trust Result Constants
68 @discussion Predefined key constants used to obtain values in a
69 dictionary of trust evaluation results for a certificate chain,
70 as retrieved from a call to SecTrustCopyResult.
72 @constant kSecTrustResultDetails
73 This key will be present if a trust evaluation has been performed.
74 Its value is a CFArrayRef of CFDictionaryRef representing detailed
75 status info for each certificate in the completed chain.
76 @constant kSecTrustRevocationReason
77 This key will be present iff this chain had its revocation checked,
78 and a "revoked" response was received. The value of this key will
79 be a CFNumberRef indicating the reason for revocation. The possible
80 reason code values are described in RFC 5280, section 5.3.1.
82 extern const CFStringRef kSecTrustResultDetails
;
83 /*__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_9_0);*/
84 extern const CFStringRef kSecTrustRevocationReason
;
85 /*__OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);*/
88 @function SecTrustCopySummaryPropertiesAtIndex
89 @abstract Return a property array for the certificate.
90 @param trust A reference to the trust object to evaluate.
91 @param ix The index of the requested certificate. Indices run from 0
92 (leaf) to the anchor (or last certificate found if no anchor was found).
93 @result A property array. It is the caller's responsibility to CFRelease
94 the returned array when it is no longer needed. This function returns a
95 short summary description of the certificate in question. The property
96 at index 0 of the array might also include general information about the
97 entire chain's validity in the context of this trust evaluation.
99 @discussion Returns a property array for this trust certificate. A property
100 array is an array of CFDictionaryRefs. Each dictionary (we call it a
101 property for short) has the following keys:
103 kSecPropertyKeyType This key's value determines how this property
104 should be displayed. Its associated value is one of the
106 kSecPropertyTypeWarning
107 The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not
108 set. The kSecPropertyKeyValue is a CFStringRef which should
109 be displayed in yellow with a warning triangle.
110 kSecPropertyTypeError
111 The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not
112 set. The kSecPropertyKeyValue is a CFStringRef which should
113 be displayed in red with an error X.
114 kSecPropertyTypeSuccess
115 The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not
116 set. The kSecPropertyKeyValue is a CFStringRef which should
117 be displayed in green with a checkmark in front of it.
118 kSecPropertyTypeTitle
119 The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not
120 set. The kSecPropertyKeyValue is a CFStringRef which should
121 be displayed in a larger bold font.
122 kSecPropertyTypeSection
123 The optional kSecPropertyKeyLocalizedLabel is a CFStringRef with the name
124 of the next section to display. The value of the
125 kSecPropertyKeyValue key is a CFArrayRef which is a property
126 array as defined here.
128 The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing
129 the localized label for the value for the kSecPropertyKeyValue.
130 The type of this value is a CFDataRef. Its contents should be
131 displayed as: "bytes length_of_data : hexdump_of_data". Ideally
132 the UI will only show one line of hex dump data and have a
133 disclosure arrow to see the remainder.
134 kSecPropertyTypeString
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 CFStringRef. It's contents should be
138 displayed in the normal font.
140 The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing
141 the localized label for the value for the kSecPropertyKeyValue.
142 The type of this value is a CFURLRef. It's contents should be
143 displayed as a hyperlink.
145 The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing
146 the localized label for the value for the kSecPropertyKeyValue.
147 The type of this value is a CFDateRef. It's contents should be
148 displayed in human readable form (probably in the current
150 kSecPropertyKeyLocalizedLabel
151 Human readable localized label for a given property.
153 See description of kSecPropertyKeyType to determine what the value
156 Non localized key (label) for this value. This is only
157 present for properties with fixed label names.
158 @param certificate A reference to the certificate to evaluate.
159 @result A property array. It is the caller's responsability to CFRelease
160 the returned array when it is no longer needed.
162 __nullable CF_RETURNS_RETAINED
163 CFArrayRef
SecTrustCopySummaryPropertiesAtIndex(SecTrustRef trust
, CFIndex ix
);
166 @function SecTrustCopyDetailedPropertiesAtIndex
167 @abstract Return a property array for the certificate.
168 @param trust A reference to the trust object to evaluate.
169 @param ix The index of the requested certificate. Indices run from 0
170 (leaf) to the anchor (or last certificate found if no anchor was found).
171 @result A property array. It is the caller's responsibility to CFRelease
172 the returned array when it is no longer needed.
173 See SecTrustCopySummaryPropertiesAtIndex on how to intepret this array.
174 Unlike that function call this function returns a detailed description
175 of the certificate in question.
177 __nullable CF_RETURNS_RETAINED
178 CFArrayRef
SecTrustCopyDetailedPropertiesAtIndex(SecTrustRef trust
, CFIndex ix
);
181 @function SecTrustCopyInfo
182 @abstract Return a dictionary with additional information about the
183 evaluated certificate chain for use by clients.
184 @param trust A reference to an evaluated trust object.
185 @discussion Returns a dictionary for this trust evaluation. This
186 dictionary may have the following keys:
188 kSecTrustInfoExtendedValidationKey this key will be present and have
189 a value of kCFBooleanTrue if this chain was validated for EV.
190 kSecTrustInfoCompanyNameKey Company name field of subject of leaf
191 certificate, this field is meant to be displayed to the user
192 if the kSecTrustInfoExtendedValidationKey is present.
193 kSecTrustInfoRevocationKey this key will be present iff this chain
194 had its revocation checked. The value will be a kCFBooleanTrue
195 if revocation checking was successful and none of the
196 certificates in the chain were revoked.
197 The value will be kCFBooleanFalse if no current revocation status
198 could be obtained for one or more certificates in the chain due
199 to connection problems or timeouts etc. This is a hint to a
200 client to retry revocation checking at a later time.
201 kSecTrustInfoRevocationValidUntilKey this key will be present iff
202 kSecTrustInfoRevocationKey has a value of kCFBooleanTrue.
203 The value will be a CFDateRef representing the earliest date at
204 which the revocation info for one of the certificates in this chain
207 @result A dictionary with various fields that can be displayed to the user,
208 or NULL if no additional info is available or the trust has not yet been
209 validated. The caller is responsible for calling CFRelease on the value
210 returned when it is no longer needed.
212 __nullable CF_RETURNS_RETAINED
213 CFDictionaryRef
SecTrustCopyInfo(SecTrustRef trust
);
215 /* For debugging purposes. */
216 __nullable CF_RETURNS_RETAINED
217 CFArrayRef
SecTrustGetDetails(SecTrustRef trust
);
219 /* For debugging purposes. */
220 __nullable CF_RETURNS_RETAINED
221 CFStringRef
SecTrustCopyFailureDescription(SecTrustRef trust
);
223 OSStatus
SecTrustGetOTAPKIAssetVersionNumber(int* versionNumber
);
225 OSStatus
SecTrustOTAPKIGetUpdatedAsset(int* didUpdateAsset
);
228 @function SecTrustSignedCertificateTimestampList
229 @abstract Attach SignedCertificateTimestampList data to a trust object.
230 @param trust A reference to a trust object.
231 @param sctArray is a CFArray of CFData objects each containing a SCT (per RFC 6962).
232 @result A result code. See "Security Error Codes" (SecBase.h).
233 @discussion Allows the caller to provide SCT data (which may be
234 obtained during a TLS/SSL handshake, per RFC 6962) as input to a trust
237 OSStatus
SecTrustSetSignedCertificateTimestamps(SecTrustRef trust
, CFArrayRef sctArray
);
240 @function SecTrustSetTrustedLogs
241 @abstract Sets the trusted CT logs for a given trust.
242 @param trust A reference to a trust object.
243 @param trustedLogs An array of trusted logs.
244 @result A result code. See "Security Error Codes" (SecBase.h).
245 @discussion trustedLog is a CFArray of CFData containing the DER-encode SubjectPublicKeyInfo
246 of the trusted CT logs.
248 OSStatus
SecTrustSetTrustedLogs(SecTrustRef trust
, CFArrayRef trustedLogs
);
250 /* Keychain searches are allowed by default. Use this to turn off seaching of
251 -keychain search list (i.e. login.keychain, system.keychain)
252 -Local Items/iCloud Keychain
253 -user- and admin-trusted roots
254 -network-fetched issuers
255 User must provide all necessary certificates in the input certificates and/or anchors. */
256 OSStatus
SecTrustSetKeychainsAllowed(SecTrustRef trust
, Boolean allowed
)
257 __OSX_AVAILABLE(__MAC_10_12
) __IOS_AVAILABLE(__IPHONE_10_0
) __TVOS_AVAILABLE(__TVOS_10_0
) __WATCHOS_AVAILABLE(__WATCHOS_3_0
);
259 /* Get the keychain search policy for the trust object. */
260 OSStatus
SecTrustGetKeychainsAllowed(SecTrustRef trust
, Boolean
* __nonnull allowed
)
261 __OSX_AVAILABLE(__MAC_10_12
) __IOS_AVAILABLE(__IPHONE_10_0
) __TVOS_AVAILABLE(__TVOS_10_0
) __WATCHOS_AVAILABLE(__WATCHOS_3_0
);
264 @function SecTrustEvaluateLeafOnly
265 @abstract Evaluates the leaf of the trust reference synchronously.
266 @param trust A reference to the trust object to evaluate.
267 @param result A pointer to a result type.
268 @result A result code. See "Security Error Codes" (SecBase.h).
269 @discussion This function will only evaluate the trust of the leaf certificate.
270 No chain will be built and only those aspects of the SecPolicyRef that address
271 the expected contents of the leaf will be checked. This function does not honor
274 OSStatus
SecTrustEvaluateLeafOnly(SecTrustRef trust
, SecTrustResultType
* __nonnull result
)
275 __OSX_AVAILABLE(__MAC_10_12
) __IOS_AVAILABLE(__IPHONE_10_0
) __TVOS_AVAILABLE(__TVOS_10_0
) __WATCHOS_AVAILABLE(__WATCHOS_3_0
);
278 @function SecTrustSerialize
279 @abstract Creates a serialized version of the trust object
280 @param trust A reference to the trust object to serialize.
281 @param error A pointer to an error.
282 @result The serialized trust object.
283 @discussion This function is intended to be used to share SecTrustRefs between
284 processes. Saving the results to disk or sending them over network channels
285 may cause unexpected behavior.
287 __nullable CF_RETURNS_RETAINED
288 CFDataRef
SecTrustSerialize(SecTrustRef trust
, CFErrorRef
*error
)
289 __OSX_AVAILABLE(__MAC_10_12
) __IOS_AVAILABLE(__IPHONE_10_0
) __TVOS_AVAILABLE(__TVOS_10_0
) __WATCHOS_AVAILABLE(__WATCHOS_3_0
);
292 @function SecTrustDeserialize
293 @abstract Creates a trust object from the serialized data
294 @param serialiedTrust A reference to the serialized trust object
295 @param error A pointer to an error.
296 @result A trust object
297 @discussion This function is intended to be used to share SecTrustRefs between
298 processes. Saving the results to disk or sending them over network channels
299 may cause unexpected behavior.
301 __nullable CF_RETURNS_RETAINED
302 SecTrustRef
SecTrustDeserialize(CFDataRef serializedTrust
, CFErrorRef
*error
)
303 __OSX_AVAILABLE(__MAC_10_12
) __IOS_AVAILABLE(__IPHONE_10_0
) __TVOS_AVAILABLE(__TVOS_10_0
) __WATCHOS_AVAILABLE(__WATCHOS_3_0
);
306 @function SecTrustGetTrustExceptionsArray
307 @abstract Return the exceptions array current set in the trust object
308 @param trust A reference to the trust object
309 @result The array of exceptions.
310 @discussion This function returns an array of exceptions that was previously set
311 using SecTrustSetExceptions, unlike SecTrustCopyExceptions which returns the
312 exceptions which could be set using SecTrustSetExceptions.
314 __nullable CFArrayRef
SecTrustGetTrustExceptionsArray(SecTrustRef trust
)
315 __OSX_AVAILABLE(__MAC_10_12
) __IOS_AVAILABLE(__IPHONE_10_0
) __TVOS_AVAILABLE(__TVOS_10_0
) __WATCHOS_AVAILABLE(__WATCHOS_3_0
);
317 CF_IMPLICIT_BRIDGING_DISABLED
318 CF_ASSUME_NONNULL_END
321 * Legacy functions (OS X only)
323 #if TARGET_OS_MAC && !TARGET_OS_IPHONE
325 CF_ASSUME_NONNULL_BEGIN
326 CF_IMPLICIT_BRIDGING_ENABLED
328 #pragma clang diagnostic push
329 #pragma clang diagnostic ignored "-Wfour-char-constants"
331 unique keychain item attributes for user trust records.
334 kSecTrustCertAttr
= 'tcrt',
335 kSecTrustPolicyAttr
= 'tpol',
336 /* Leopard and later */
337 kSecTrustPubKeyAttr
= 'tpbk',
338 kSecTrustSignatureAttr
= 'tsig'
341 #pragma clang diagnostic pop
344 @function SecTrustGetUserTrust
345 @abstract Gets the user-specified trust settings of a certificate and policy.
346 @param certificate A reference to a certificate.
347 @param policy A reference to a policy.
348 @param trustSetting On return, a pointer to the user specified trust settings.
349 @result A result code. See "Security Error Codes" (SecBase.h).
350 @availability Mac OS X version 10.4. Deprecated in Mac OS X version 10.5.
352 OSStatus
SecTrustGetUserTrust(SecCertificateRef __nullable certificate
, SecPolicyRef __nullable policy
, SecTrustUserSetting
* __nullable trustSetting
)
353 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_4
, __MAC_10_5
, __IPHONE_NA
, __IPHONE_NA
);
356 @function SecTrustSetUserTrust
357 @abstract Sets the user-specified trust settings of a certificate and policy.
358 @param certificate A reference to a certificate.
359 @param policy A reference to a policy.
360 @param trustSetting The user-specified trust settings.
361 @result A result code. See "Security Error Codes" (SecBase.h).
362 @availability Mac OS X version 10.4. Deprecated in Mac OS X version 10.5.
363 @discussion as of Mac OS version 10.5, this will result in a call to
364 SecTrustSettingsSetTrustSettings().
366 OSStatus
SecTrustSetUserTrust(SecCertificateRef __nullable certificate
, SecPolicyRef __nullable policy
, SecTrustUserSetting trustSetting
)
367 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_4
, __MAC_10_5
, __IPHONE_NA
, __IPHONE_NA
);
370 @function SecTrustSetUserTrustLegacy
371 @abstract Sets the user-specified trust settings of a certificate and policy.
372 @param certificate A reference to a certificate.
373 @param policy A reference to a policy.
374 @param trustSetting The user-specified trust settings.
375 @result A result code. See "Security Error Codes" (SecBase.h).
377 @This is the private version of what used to be SecTrustSetUserTrust(); it operates
378 on UserTrust entries as that function used to. The current SecTrustSetUserTrust()
379 function operated on Trust Settings.
381 OSStatus
SecTrustSetUserTrustLegacy(SecCertificateRef __nullable certificate
, SecPolicyRef __nullable policy
, SecTrustUserSetting trustSetting
)
382 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_5
, __MAC_10_12
, __IPHONE_NA
, __IPHONE_NA
);
385 @function SecTrustGetCSSMAnchorCertificates
386 @abstract Retrieves the CSSM anchor certificates.
387 @param cssmAnchors A pointer to an array of anchor certificates.
388 @param cssmAnchorCount A pointer to the number of certificates in anchors.
389 @result A result code. See "Security Error Codes" (SecBase.h).
390 @availability Mac OS X version 10.4. Deprecated in Mac OS X version 10.5.
392 OSStatus
SecTrustGetCSSMAnchorCertificates(const CSSM_DATA
* __nullable
* __nullable cssmAnchors
, uint32
*cssmAnchorCount
)
393 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_4
, __MAC_10_5
, __IPHONE_NA
, __IPHONE_NA
);
396 @function SecTrustCopyExtendedResult
397 @abstract Gets the extended trust result after an evaluation has been performed.
398 @param trust A trust reference.
399 @param result On return, result points to a CFDictionaryRef containing extended trust results (if no error occurred).
400 The caller is responsible for releasing this dictionary with CFRelease when finished with it.
401 @result A result code. See "Security Error Codes" (SecBase.h).
402 @discussion This function may only be used after SecTrustEvaluate has been called for the trust reference, otherwise
403 errSecTrustNotAvailable is returned. If the certificate is not an extended validation certificate, there is
404 no extended result data and errSecDataNotAvailable is returned. Currently, only one dictionary key is defined
405 (kSecEVOrganizationName).
407 Note: this function will be deprecated in a future release of OS X. Your
408 code should use SecTrustCopyResult to obtain the trust results dictionary.
410 OSStatus
SecTrustCopyExtendedResult(SecTrustRef trust
, CFDictionaryRef
* __nonnull CF_RETURNS_RETAINED result
)
411 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_5
, __MAC_10_12
, __IPHONE_NA
, __IPHONE_NA
);
414 * Preference-related strings for Revocation policies.
418 * Preference domain, i.e., the name of a plist in ~/Library/Preferences or in
419 * /Library/Preferences
421 #define kSecRevocationDomain "com.apple.security.revocation"
423 /* OCSP and CRL style keys, followed by values used for both of them */
424 #define kSecRevocationOcspStyle CFSTR("OCSPStyle")
425 #define kSecRevocationCrlStyle CFSTR("CRLStyle")
426 #define kSecRevocationOff CFSTR("None")
427 #define kSecRevocationBestAttempt CFSTR("BestAttempt")
428 #define kSecRevocationRequireIfPresent CFSTR("RequireIfPresent")
429 #define kSecRevocationRequireForAll CFSTR("RequireForAll")
431 /* Which first if both enabled? */
432 #define kSecRevocationWhichFirst CFSTR("RevocationFirst")
433 #define kSecRevocationOcspFirst CFSTR("OCSP")
434 #define kSecRevocationCrlFirst CFSTR("CRL")
436 /* boolean: A "this policy is sufficient per cert" for each */
437 #define kSecRevocationOCSPSufficientPerCert CFSTR("OCSPSufficientPerCert")
438 #define kSecRevocationCRLSufficientPerCert CFSTR("CRLSufficientPerCert")
440 /* local OCSP responder URI, value arbitrary string value */
441 #define kSecOCSPLocalResponder CFSTR("OCSPLocalResponder")
443 /* Extended trust result keys (now in public API) */
444 #define kSecEVOrganizationName kSecTrustOrganizationName
445 #define kSecTrustExpirationDate kSecTrustRevocationValidUntilDate
447 CF_IMPLICIT_BRIDGING_DISABLED
448 CF_ASSUME_NONNULL_END
450 #endif /* TARGET_OS_MAC && !TARGET_OS_IPHONE */
454 #endif /* !_SECURITY_SECTRUSTPRIV_H_ */