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