1//
2// CoreTrust.h
3// CoreTrust
4//
5// Copyright © 2017-2020 Apple Inc. All rights reserved.
6//
7
8#ifndef _CORETRUST_EVALUATE_H_
9#define _CORETRUST_EVALUATE_H_
10
11#include "CTConfig.h"
12
13__BEGIN_DECLS
14
15__ptrcheck_abi_assume_single()
16
17typedef struct x509_octet_string {
18 const CT_uint8_t * __counted_by(length) data;
19 CT_size_t length;
20} CTAsn1Item;
21
22extern const CTAsn1Item CTOidItemAppleImg4Manifest; //1.2.840.113635.100.6.1.15
23
24extern const CTAsn1Item CTOidItemAppleDeviceAttestationNonce; // 1.2.840.113635.100.8.2
25extern const CTAsn1Item CTOidItemAppleDeviceAttestationHardwareProperties; // 1.2.840.113635.100.8.4
26extern const CTAsn1Item CTOidItemAppleDeviceAttestationKeyUsageProperties; // 1.2.840.113635.100.8.5
27extern const CTAsn1Item CTOidItemAppleDeviceAttestationDeviceOSInformation; // 1.2.840.113635.100.8.7
28
29
30/*! @function CTParseCertificateSet
31 @abstract Parses binary (DER-encoded) certificates concatenated in memory into parsed CTAsn1Items
32 @param der pointer to beginning of the encoded certificates
33 @param der_end pointer to end of the encoded certificates
34 @param certStorage an allocated array of CTAsn1Items which will be populated by the parser
35 @param certStorageLen the number of CTAsn1Item in certStorage
36 @param numParsedCerts return value, the number of certs successfully parse from the input
37 @return 0 upon success or a parsing error (see CTErrors.h) */
38CT_int CTParseCertificateSet(
39 const CT_uint8_t * __ended_by(der_end) der,
40 const CT_uint8_t *der_end,
41 CTAsn1Item * __counted_by(certStorageLen) certStorage,
42 CT_size_t certStorageLen,
43 CT_size_t *numParsedCerts);
44
45/*! @function CTParseExtensionValue
46 @abstract Parse a certificate and return the value of an extension with a specifed extnId
47 @param certData pointer to beginning of the encoded certificate
48 @param certLen the length of the certificate
49 @param extensionOidData pointer to the extnId OID to find in the certificate
50 @param extensionOidLen length of the OID
51 @param extensionValueData return value, pointer to the extension value found in the certificate with the specified OID
52 @param extensionValueLen return value, length of the extension value found
53 @return 0 upon success, a parsing error (see CTErrors.h) */
54CT_int CTParseExtensionValue(
55 const CT_uint8_t * __counted_by(certLen) certData,
56 CT_size_t certLen,
57 const CT_uint8_t *__counted_by(extensionOidLen) extensionOidData,
58 CT_size_t extensionOidLen,
59 const CT_uint8_t * __counted_by(*extensionValueLen) *extensionValueData,
60 CT_size_t *extensionValueLen);
61
62/*! @function CTParseKey
63 @abstract Parse a certificate and return the public key
64 @param certData pointer to beginning of the encoded certificate
65 @param certLen the length of the certificate
66 @param keyData return value, pointer to the key in the parsed certificate
67 @param keyLen return value, length of the key in the parsed certificate
68 @return 0 upon success, a parsing error (see CTErrors.h) */
69CT_int CTParseKey(
70 const CT_uint8_t * __counted_by(certLen) certData,
71 CT_size_t certLen,
72 const CT_uint8_t *__counted_by(*keyLen) *keyData,
73 CT_size_t *keyLen);
74
75/*! @function CTEvaluateSavageCerts
76 @abstract Verify certificates against Savage policy, with specified anchor key
77 @param certsData pointer to beginning of the binary (DER-encoded) certificates (leaf first)
78 @param certsLen the length of the certificates byte array
79 @param rootKeyData pointer to the anchor public key
80 @param rootKeyLen length of the anchor public key
81 @param leafKeyData return value, pointer to the key in the verified leaf certificate
82 @param leafKeyLen return value, length of the key in the verified leaf certificate
83 @param isProdCert return value, boolean indicating whether the leaf certificate is prod-issued
84 @return 0 upon success, a parsing or validation error (see CTErrors.h) */
85CT_int CTEvaluateSavageCerts(
86 const CT_uint8_t *__counted_by(certsLen) certsData, CT_size_t certsLen,
87 const CT_uint8_t *__counted_by(rootKeyLen) rootKeyData, CT_size_t rootKeyLen,
88 const CT_uint8_t *__counted_by(*leafKeyLen) *leafKeyData, CT_size_t *leafKeyLen,
89 CT_bool *isProdCert);
90
91/*! @function CTEvaluateSavageCertsWithUID
92 @abstract Verify certificates against Savage policy, with specified anchor key
93 @param certsData pointer to beginning of the binary (DER-encoded) certificates (leaf first)
94 @param certsLen the length of the certificates byte array
95 @param rootKeyData pointer to the anchor public key
96 @param rootKeyLen length of the anchor public key
97 @param leafKeyData return value, pointer to the key in the verified leaf certificate
98 @param leafKeyLen return value, length of the key in the verified leaf certificate
99 @param UIDData pointer to a preallocated buffer of UIDLen, which will be populated with the UID
100 @param UIDLen length of the UIDData buffer
101 @param isProdCert return value, boolean indicating whether the leaf certificate is prod-issued
102 @return 0 upon success, a parsing or validation error (see CTErrors.h) */
103CT_int CTEvaluateSavageCertsWithUID(
104 const CT_uint8_t *__counted_by(certsLen) certsData, CT_size_t certsLen,
105 const CT_uint8_t *__counted_by(rootKeyLen) rootKeyData, CT_size_t rootKeyLen,
106 const CT_uint8_t *__counted_by(*leafKeyLen) *leafKeyData, CT_size_t *leafKeyLen,
107 CT_uint8_t *__counted_by(UIDLen) UIDData, CT_size_t UIDLen,
108 CT_bool *isProdCert);
109
110/*! @function CTEvaluateYonkersCerts
111 @abstract Verify certificates against Yonkers policy, with specified anchor key
112 @param certsData pointer to beginning of the binary (DER-encoded) certificates (leaf first)
113 @param certsLen the length of the certificates byte array
114 @param rootKeyData pointer to the anchor public key
115 @param rootKeyLen length of the anchor public key
116 @param leafKeyData return value, pointer to the key in the verified leaf certificate
117 @param leafKeyLen return value, length of the key in the verified leaf certificate
118 @param UIDData pointer to a preallocated buffer of UIDLen, which will be populated with the UID
119 @param UIDLen length of the UIDData buffer
120 @param isProdCert return value, boolean indicating whether the leaf certificate is prod-issued
121 @return 0 upon success, a parsing or validation error (see CTErrors.h) */
122CT_int CTEvaluateYonkersCerts(
123 const CT_uint8_t *__counted_by(certsLen) certsData, CT_size_t certsLen,
124 const CT_uint8_t *__counted_by(rootKeyLen) rootKeyData, CT_size_t rootKeyLen,
125 const CT_uint8_t *__counted_by(*leafKeyLen) *leafKeyData, CT_size_t *leafKeyLen,
126 CT_uint8_t *__counted_by(UIDLen) UIDData, CT_size_t UIDLen,
127 CT_bool *isProdCert);
128
129/*! @function CTEvaluateSensorCerts
130 @abstract Verify certificates against Sensor(s) policy, with specified anchor key and intermediate marker value
131 @param certsData pointer to beginning of the binary (DER-encoded) certificates (leaf first)
132 @param certsLen the length of the certificates byte array
133 @param rootKeyData pointer to the anchor public key
134 @param rootKeyLen length of the anchor public key
135 @param intermediateMarker pointer to the value expected in the intermediate marker extension
136 @param intermediateMarkerLen length of the intermediate marker value
137 @param leafKeyData return value, pointer to the key in the verified leaf certificate
138 @param leafKeyLen return value, length of the key in the verified leaf certificate
139 @param UIDData pointer to a preallocated buffer of UIDLen, which will be populated with the UID
140 @param UIDLen length of the UIDData buffer
141 @param isProdCert return value, boolean indicating whether the leaf certificate is prod-issued
142 @return 0 upon success, a parsing or validation error (see CTErrors.h) */
143CT_int CTEvaluateSensorCerts(
144 const CT_uint8_t *__counted_by(certsLen) certsData, CT_size_t certsLen,
145 const CT_uint8_t *__counted_by(rootKeyLen) rootKeyData, CT_size_t rootKeyLen,
146 const CT_uint8_t *__counted_by(intermediateMarkerLen) intermediateMarker, CT_size_t intermediateMarkerLen,
147 const CT_uint8_t *__counted_by(*leafKeyLen) *leafKeyData, CT_size_t *leafKeyLen,
148 CT_uint8_t *__counted_by(UIDLen) UIDData, CT_size_t UIDLen,
149 CT_bool *isProdCert);
150
151/*! @function CTEvaluateAcrt
152 @abstract Verify certificates against acrt policy
153 @param certsData pointer to beginning of the binary (DER-encoded) certificates (leaf first)
154 @param certsLen the length of the certificates byte array
155 @param leafKeyData return value, pointer to the key in the verified leaf certificate
156 @param leafKeyLen return value, length of the key in the verified leaf certificate
157 @return 0 upon success, a parsing or validation error (see CTErrors.h) */
158CT_int CTEvaluateAcrt(
159 const CT_uint8_t *__counted_by(certsLen) certsData, CT_size_t certsLen,
160 const CT_uint8_t *__counted_by(*leafKeyLen) *leafKeyData, CT_size_t *leafKeyLen);
161
162/*! @function CTEvaluateUcrt
163 @abstract Verify certificates against ucrt policy
164 @param certsData pointer to beginning of the binary (DER-encoded) certificates (leaf first)
165 @param certsLen the length of the certificates byte array
166 @param leafKeyData return value, pointer to the key in the verified leaf certificate
167 @param leafKeyLen return value, length of the key in the verified leaf certificate
168 @return 0 upon success, a parsing or validation error (see CTErrors.h) */
169CT_int CTEvaluateUcrt(
170 const CT_uint8_t *__counted_by(certsLen) certsData, CT_size_t certsLen,
171 const CT_uint8_t *__counted_by(*leafKeyLen) *leafKeyData, CT_size_t *leafKeyLen); // Output: points to the leaf key data in the input certsData)
172
173/*! @function CTEvaluateUcrtTestRoot
174 @abstract Verify certificates against ucrt policy, with optional anchor key for test roots
175 @param certsData pointer to beginning of the binary (DER-encoded) certificates (leaf first)
176 @param certsLen the length of the certificates byte array
177 @param rootKeyData optional pointer to the test anchor public key. If unspecified the production anchor will be used
178 @param rootKeyLen length of the optional anchor public key
179 @param leafKeyData return value, pointer to the key in the verified leaf certificate
180 @param leafKeyLen return value, length of the key in the verified leaf certificate
181 @return 0 upon success, a parsing or validation error (see CTErrors.h) */
182CT_int CTEvaluateUcrtTestRoot(
183 const CT_uint8_t *__counted_by(certsLen) certsData, CT_size_t certsLen,
184 const CT_uint8_t *__counted_by(rootKeyLen) rootKeyData, CT_size_t rootKeyLen,
185 const CT_uint8_t *__counted_by(*leafKeyLen) *leafKeyData, CT_size_t *leafKeyLen);
186
187/*! @function CTEvaluateBAASystem
188 @abstract Verify certificates against BAA scrt-attested policy
189 @param certsData pointer to beginning of the binary (DER-encoded) certificates (leaf first)
190 @param certsLen the length of the certificates byte array
191 @param leafKeyData return value, pointer to the key in the verified leaf certificate
192 @param leafKeyLen return value, length of the key in the verified leaf certificate
193 @return 0 upon success, a parsing or validation error (see CTErrors.h) */
194CT_int CTEvaluateBAASystem(
195 const CT_uint8_t *__counted_by(certsLen) certsData, CT_size_t certsLen,
196 const CT_uint8_t *__counted_by(*leafKeyLen) *leafKeyData, CT_size_t *leafKeyLen);
197
198typedef struct baa_identity {
199 CT_uint32_t chipId;
200 CT_uint64_t ecid;
201 CT_bool productionStatus;
202 CT_bool securityMode;
203 CT_uint8_t securityDomain;
204 CTAsn1Item img4;
205} CTBAAIdentity;
206
207/*! @function CTEvaluateBAASystemWithId
208 @abstract Verify certificates against BAA scrt-attested policy, returning BAA identity
209 @param certsData pointer to beginning of the binary (DER-encoded) certificates (leaf first)
210 @param certsLen the length of the certificates byte array
211 @param leafKeyData return value, pointer to the key in the verified leaf certificate
212 @param leafKeyLen return value, length of the key in the verified leaf certificate
213 @param identity return value, BAA identity from leaf certificate
214 @return 0 upon success, a parsing or validation error (see CTErrors.h) */
215CT_int CTEvaluateBAASystemWithId(
216 const CT_uint8_t *__counted_by(certsLen) certsData, CT_size_t certsLen,
217 const CT_uint8_t *__counted_by(*leafKeyLen) *leafKeyData, CT_size_t *leafKeyLen,
218 CTBAAIdentity *identity);
219
220/*! @function CTEvaluateBAASystemTestRoot
221 @abstract Verify certificates against BAA scrt-attested policy, returning BAA identity with optional anchor key for test roots
222 @param certsData pointer to beginning of the binary (DER-encoded) certificates (leaf first)
223 @param certsLen the length of the certificates byte array
224 @param rootKeyData optional pointer to the test anchor public key. If unspecified the production anchor will be used
225 @param rootKeyLen length of the optional anchor public key
226 @param leafKeyData return value, pointer to the key in the verified leaf certificate
227 @param leafKeyLen return value, length of the key in the verified leaf certificate
228 @param identity return value, BAA identity from leaf certificate
229 @return 0 upon success, a parsing or validation error (see CTErrors.h) */
230CT_int CTEvaluateBAASystemTestRoot(
231 const CT_uint8_t *__counted_by(certsLen) certsData, CT_size_t certsLen,
232 const CT_uint8_t *__counted_by(rootKeyLen) rootKeyData, CT_size_t rootKeyLen,
233 const CT_uint8_t *__counted_by(*leafKeyLen) *leafKeyData, CT_size_t *leafKeyLen,
234 CTBAAIdentity *identity);
235
236/*! @function CTEvaluateBAAUser
237 @abstract Verify certificates against BAA ucrt-attested policy, returning BAA identity
238 @param certsData pointer to beginning of the binary (DER-encoded) certificates (leaf first)
239 @param certsLen the length of the certificates byte array
240 @param leafKeyData return value, pointer to the key in the verified leaf certificate
241 @param leafKeyLen return value, length of the key in the verified leaf certificate
242 @param identity return value, BAA identity from leaf certificate
243 @return 0 upon success, a parsing or validation error (see CTErrors.h) */
244CT_int CTEvaluateBAAUser(
245 const CT_uint8_t *__counted_by(certsLen) certsData, CT_size_t certsLen,
246 const CT_uint8_t *__counted_by(*leafKeyLen) *leafKeyData, CT_size_t *leafKeyLen,
247 CTBAAIdentity *identity);
248
249/*! @function CTEvaluateBAAUserTestRoot
250 @abstract Verify certificates against BAA ucrt-attested policy, returning BAA identity with optional anchor key for test roots
251 @param certsData pointer to beginning of the binary (DER-encoded) certificates (leaf first)
252 @param certsLen the length of the certificates byte array
253 @param rootKeyData optional pointer to the test anchor public key. If unspecified the production anchor will be used
254 @param rootKeyLen length of the optional anchor public key
255 @param leafKeyData return value, pointer to the key in the verified leaf certificate
256 @param leafKeyLen return value, length of the key in the verified leaf certificate
257 @param identity return value, BAA identity from leaf certificate
258 @return 0 upon success, a parsing or validation error (see CTErrors.h) */
259CT_int CTEvaluateBAAUserTestRoot(
260 const CT_uint8_t *__counted_by(certsLen) certsData, CT_size_t certsLen,
261 const CT_uint8_t *__counted_by(rootKeyLen) rootKeyData, CT_size_t rootKeyLen,
262 const CT_uint8_t *__counted_by(*leafKeyLen) *leafKeyData, CT_size_t *leafKeyLen,
263 CTBAAIdentity *identity);
264
265/*! @function CTEvaluateBAAAccessory
266 @abstract Verify certificates against BAA accessory (MFi4) policy
267 @param certsData pointer to beginning of the binary (DER-encoded) certificates (leaf first)
268 @param certsLen the length of the certificates byte array
269 @param rootKeyData optional pointer to the test anchor public key. If unspecified the production anchor will be used
270 @param rootKeyLen length of the optional anchor public key
271 @param leafKeyData return value, pointer to the key in the verified leaf certificate
272 @param leafKeyLen return value, length of the key in the verified leaf certificate
273 @param propertiesData return value, pointer to the Apple Accessories properties extension value in the verified leaf certificate
274 @param propertiesLen return value, length of the properties in the verified leaf certificate
275 @return 0 upon success, a parsing or validation error (see CTErrors.h) */
276CT_int CTEvaluateBAAAccessory(
277 const CT_uint8_t *__counted_by(certsLen) certsData, CT_size_t certsLen,
278 const CT_uint8_t *__counted_by(rootKeyLen) rootKeyData, CT_size_t rootKeyLen,
279 const CT_uint8_t *__counted_by(*leafKeyLen) *leafKeyData, CT_size_t *leafKeyLen,
280 const CT_uint8_t *__counted_by(*propertiesLen) *propertiesData, CT_size_t *propertiesLen);
281
282/*! @function CTEvaluateSatori
283 @abstract Verify certificates against Satori policy
284 @param certsData pointer to beginning of the binary (DER-encoded) certificates (leaf first)
285 @param certsLen the length of the certificates byte array
286 @param allowTestRoot allow the Test Apple roots to be used as anchors in addition to the production roots
287 @param leafKeyData return value, pointer to the key in the verified leaf certificate
288 @param leafKeyLen return value, length of the key in the verified leaf certificate
289 @return 0 upon success, a parsing or validation error (see CTErrors.h) */
290CT_int CTEvaluateSatori(
291 const CT_uint8_t *__counted_by(certsLen) certsData, CT_size_t certsLen,
292 CT_bool allowTestRoot,
293 const CT_uint8_t *__counted_by(*leafKeyLen) *leafKeyData, CT_size_t *leafKeyLen);
294
295/*! @function CTEvaluatePragueSignatureCMS
296 @abstract Verify CMS signature and certificates against Prague policy
297 @param cmsData pointer to beginning of the binary (BER-encoded) CMS object
298 @param cmsLen the length of the CMS object
299 @param detachedData pointer to data that is signed by the CMS object
300 @param detachedDataLen the length of the signed data
301 @param allowTestRoot allow the Test Apple roots to be used as anchors in addition to the production roots
302 @param leafKeyData return value, pointer to the key in the verified leaf certificate
303 @param leafKeyLen return value, length of the key in the verified leaf certificate
304 @return 0 upon success, a parsing or validation error (see CTErrors.h) */
305CT_int CTEvaluatePragueSignatureCMS(
306 const CT_uint8_t *__counted_by(cmsLen) cmsData, CT_size_t cmsLen,
307 const CT_uint8_t *__counted_by(detachedDataLen) detachedData, CT_size_t detachedDataLen,
308 CT_bool allowTestRoot,
309 const CT_uint8_t *__counted_by(*leafKeyLen) *leafKeyData, CT_size_t *leafKeyLen);
310
311/*! @function CTEvaluateKDLSignatureCMS
312 @abstract Verify CMS signature and certificates against KDL policy
313 @param cmsData pointer to beginning of the binary (BER-encoded) CMS object
314 @param cmsLen the length of the CMS object
315 @param detachedData pointer to data that is signed by the CMS object
316 @param detachedDataLen the length of the signed data
317 @param allowTestRoot allow the Test Apple roots to be used as anchors in addition to the production roots
318 @param leafKeyData return value, pointer to the key in the verified leaf certificate
319 @param leafKeyLen return value, length of the key in the verified leaf certificate
320 @return 0 upon success, a parsing or validation error (see CTErrors.h) */
321CT_int CTEvaluateKDLSignatureCMS(
322 const CT_uint8_t *__counted_by(cmsLen) cmsData, CT_size_t cmsLen, // Input: CMS signature blob
323 const CT_uint8_t *__counted_by(detachedDataLen) detachedData, CT_size_t detachedDataLen, // Input: data signed by CMS blob
324 CT_bool allowTestRoot, // Input: permit use of test hierarchy
325 const CT_uint8_t *__counted_by(*leafKeyLen) *leafKeyData, CT_size_t *leafKeyLen); // Output: points to leaf key data in input cmsData
326
327typedef CT_uint64_t CoreTrustPolicyFlags;
328enum {
329 CORETRUST_POLICY_BASIC = 0,
330 CORETRUST_POLICY_SAVAGE_DEV = 1 << 0,
331 CORETRUST_POLICY_SAVAGE_PROD = 1 << 1,
332 CORETRUST_POLICY_MFI_AUTHV3 = 1 << 2,
333 CORETRUST_POLICY_MAC_PLATFORM = 1 << 3,
334 CORETRUST_POLICY_MAC_DEVELOPER = 1 << 4,
335 CORETRUST_POLICY_DEVELOPER_ID = 1 << 5,
336 CORETRUST_POLICY_MAC_APP_STORE = 1 << 6,
337 CORETRUST_POLICY_IPHONE_DEVELOPER = 1 << 7,
338 CORETRUST_POLICY_IPHONE_APP_PROD = 1 << 8,
339 CORETRUST_POLICY_IPHONE_APP_DEV = 1 << 9,
340 CORETRUST_POLICY_IPHONE_VPN_PROD = 1 << 10,
341 CORETRUST_POLICY_IPHONE_VPN_DEV = 1 << 11,
342 CORETRUST_POLICY_TVOS_APP_PROD = 1 << 12,
343 CORETRUST_POLICY_TVOS_APP_DEV = 1 << 13,
344 CORETRUST_POLICY_TEST_FLIGHT_PROD = 1 << 14,
345 CORETRUST_POLICY_TEST_FLIGHT_DEV = 1 << 15,
346 CORETRUST_POLICY_IPHONE_DISTRIBUTION = 1 << 16,
347 CORETRUST_POLICY_MAC_SUBMISSION = 1 << 17,
348 CORETRUST_POLICY_YONKERS_DEV = 1 << 18,
349 CORETRUST_POLICY_YONKERS_PROD = 1 << 19,
350 CORETRUST_POLICY_MAC_PLATFORM_G2 = 1 << 20,
351 CORETRUST_POLICY_ACRT = 1 << 21,
352 CORETRUST_POLICY_SATORI = 1 << 22,
353 CORETRUST_POLICY_BAA = 1 << 23,
354 CORETRUST_POLICY_BAA_SYSTEM = 1 << 23, // BAA and BAA_SYSTEM are the same
355 CORETRUST_POLICY_UCRT = 1 << 24,
356 CORETRUST_POLICY_PRAGUE = 1 << 25,
357 CORETRUST_POLICY_KDL = 1 << 26,
358 CORETRUST_POLICY_MFI_AUTHV2 = 1 << 27,
359 CORETRUST_POLICY_MFI_SW_AUTH_PROD = 1 << 28,
360 CORETRUST_POLICY_MFI_SW_AUTH_DEV = 1 << 29,
361 CORETRUST_POLICY_COMPONENT = 1 << 30,
362 CORETRUST_POLICY_IMG4 = 1ULL << 31,
363 CORETRUST_POLICY_SERVER_AUTH = 1ULL << 32,
364 CORETRUST_POLICY_SERVER_AUTH_STRING = 1ULL << 33,
365 CORETRUST_POLICY_MFI_AUTHV4_ACCESSORY = 1ULL << 34,
366 CORETRUST_POLICY_MFI_AUTHV4_ATTESTATION = 1ULL << 35,
367 CORETRUST_POLICY_MFI_AUTHV4_PROVISIONING = 1ULL << 36,
368 CORETRUST_POLICY_WWDR_CLOUD_MANAGED = 1ULL << 37,
369 CORETRUST_POLICY_HAVEN = 1ULL << 38,
370 CORETRUST_POLICY_PROVISIONING_PROFILE = 1ULL << 39,
371 CORETRUST_POLICY_SENSOR_PROD = 1ULL << 40,
372 CORETRUST_POLICY_SENSOR_DEV = 1ULL << 41,
373 CORETRUST_POLICY_BAA_USER = 1ULL << 42,
374};
375
376typedef CT_uint32_t CoreTrustDigestType;
377enum {
378 CORETRUST_DIGEST_TYPE_SHA1 = 1,
379 CORETRUST_DIGEST_TYPE_SHA224 = 2,
380 CORETRUST_DIGEST_TYPE_SHA256 = 4,
381 CORETRUST_DIGEST_TYPE_SHA384 = 8,
382 CORETRUST_DIGEST_TYPE_SHA512 = 16
383};
384
385/*! @function CTParseAmfiCMS
386 @abstract Parse CMS signed data
387 @param cmsData pointer to beginning of the binary (BER-encoded) CMS object
388 @param cmsLen the length of the CMS object
389 @param maxDigestType maximum digest type supported by the client
390 @param leafCert return value, pointer to the verified leaf certificate
391 @param leafCertLen return value, length of the verified leaf certificate
392 @param contentData return value, pointer to the CMS content, if present
393 @param contentLen return value, length of the CMS content, if present
394 @param cmsDigestType return value, the digest type used to sign the CMS object
395 @param policyFlags return value, the CoreTrust policies that the chain may meet (based on leaf certificate only)
396 @return 0 upon success, a parsing error (see CTErrors.h)
397 */
398CT_int CTParseAmfiCMS(
399 const CT_uint8_t *__counted_by(cmsLen) cmsData, CT_size_t cmsLen,
400 CoreTrustDigestType maxDigestType,
401 const CT_uint8_t *__counted_by(*leafCertLen) *leafCert, CT_size_t *leafCertLen,
402 const CT_uint8_t *__counted_by(*contentLen) *contentData, CT_size_t *contentLen,
403 CoreTrustDigestType *cmsDigestType,
404 CoreTrustPolicyFlags *policyFlags);
405
406/*! @function CTVerifyAmfiCMS
407 @abstract Verify CMS signed data signature
408 @param cmsData pointer to beginning of the binary (BER-encoded) CMS object
409 @param cmsLen the length of the CMS object
410 @param digestData pointer to beginning of the content data hash
411 @param digestLen the length of the content data hash
412 @param maxDigestType maximum digest type supported by the client
413 @param hashAgilityDigestType return value, the highest strength digest type available in the hash agility attribute
414 @param hashAgilityDigestData return value, pointer to the hash agility value
415 @param hashAgilityDigestLen return value, length of the hash agility value
416 @return 0 upon success, a parsing or validation error (see CTErrors.h)
417 @discussion
418 Returns non-zero if there's a standards-based problem with the CMS or certificates.
419 Some notes about hash agility outputs:
420 - hashAgilityDigestType is only non-zero for HashAgilityV2
421 - If hashAgilityDigestType is non-zero, digestData/Len provides the digest value
422 - If hashAgilityDigestType is zero, digestData/Len provides the content of the HashAgilityV1 attribute (if present)
423 - If neither HashAgilityV1 nor HashAgilityV2 attributes are found, these outputs will all be NULL.
424 */
425CT_int CTVerifyAmfiCMS(
426 const CT_uint8_t *__counted_by(cmsLen) cmsData, CT_size_t cmsLen,
427 const CT_uint8_t *__counted_by(digestLen) digestData, CT_size_t digestLen,
428 CoreTrustDigestType maxDigestType,
429 CoreTrustDigestType *hashAgilityDigestType,
430 const CT_uint8_t *__counted_by(*hashAgilityDigestLen) *hashAgilityDigestData, CT_size_t *hashAgilityDigestLen);
431
432/*! @function CTVerifyAmfiCertificateChain
433 @abstract Verify CMS signed data certificate chain
434 @param cmsData pointer to beginning of the binary (BER-encoded) CMS object
435 @param cmsLen the length of the CMS object
436 @param allow_test_hierarchy allow the Test Apple roots to be used as anchors in addition to the production roots
437 @param maxDigestType maximum digest type supported by the client
438 @param policyFlags return value, the CoreTrust policies that the certificate chain met
439 @return 0 upon success, a parsing or validation error (see CTErrors.h)
440 @discussion
441 Returns non-zero if there's a standards-based problem with the CMS or certificates.
442 Policy matching of the certificates is only reflected in the policyFlags output. Namely, if the only problem is that
443 the certificates don't match a policy, the returned integer will be 0 (success) and the policyFlags will be 0 (no matching policies).
444 */
445CT_int CTVerifyAmfiCertificateChain(
446 const CT_uint8_t *__counted_by(cmsLen) cmsData, CT_size_t cmsLen,
447 CT_bool allow_test_hierarchy,
448 CoreTrustDigestType maxDigestType,
449 CoreTrustPolicyFlags *policyFlags);
450
451/*! @function CTEvaluateAMFICodeSignatureCMS
452 @abstract Verify CMS signature and certificates against the AMFI policies
453 @param cmsData pointer to beginning of the binary (BER-encoded) CMS object
454 @param cmsLen the length of the CMS object
455 @param detachedData pointer to data that is signed by the CMS object
456 @param detachedDataLen the length of the signed data
457 @param allow_test_hierarchy allow the Test Apple roots to be used as anchors in addition to the production roots
458 @param leafCert return value, pointer to the verified leaf certificate
459 @param leafCertLen return value, length of the verified leaf certificate
460 @param policyFlags return value, the CoreTrust policies that the certificate chain met
461 @param cmsDigestType return value, the digest type used to sign the CMS object
462 @param hashAgilityDigestType return value, the highest strength digest type available in the hash agility attribute
463 @param digestData return value, pointer to the hash agility value
464 @param digestLen return value, length of the hash agility value
465 @return 0 upon success, a parsing or validation error (see CTErrors.h)
466 @discussion
467 Returns non-zero if there's a standards-based problem with the CMS or certificates.
468 Policy matching of the certificates is only reflected in the policyFlags output. Namely, if the only problem is that
469 the certificates don't match a policy, the returned integer will be 0 (success) and the policyFlags will be 0 (no matching policies).
470 Some notes about hash agility outputs:
471 - hashAgilityDigestType is only non-zero for HashAgilityV2
472 - If hashAgilityDigestType is non-zero, digestData/Len provides the digest value
473 - If hashAgilityDigestType is zero, digestData/Len provides the content of the HashAgilityV1 attribute (if present)
474 - If neither HashAgilityV1 nor HashAgilityV2 attributes are found, these outputs will all be NULL.
475 */
476CT_int CTEvaluateAMFICodeSignatureCMS(
477 const CT_uint8_t *__counted_by(cmsLen) cmsData, CT_size_t cmsLen,
478 const CT_uint8_t *__counted_by(detachedDataLen) detachedData, CT_size_t detachedDataLen,
479 CT_bool allow_test_hierarchy,
480 const CT_uint8_t *__counted_by(*leafCertLen) *leafCert, CT_size_t *leafCertLen,
481 CoreTrustPolicyFlags *policyFlags,
482 CoreTrustDigestType *cmsDigestType,
483 CoreTrustDigestType *hashAgilityDigestType,
484 const CT_uint8_t *__counted_by(*digestLen) *digestData, CT_size_t *digestLen);
485
486/*! @function CTEvaluateAMFICodeSignatureCMS_MaxDigestType
487 @abstract Verify CMS signature and certificates against the AMFI policies
488 @param cmsData pointer to beginning of the binary (BER-encoded) CMS object
489 @param cmsLen the length of the CMS object
490 @param detachedData pointer to data that is signed by the CMS object
491 @param detachedDataLen the length of the signed data
492 @param allow_test_hierarchy allow the Test Apple roots to be used as anchors in addition to the production roots
493 @param maxDigestType maximum digest type supported by the client
494 @param leafCert return value, pointer to the verified leaf certificate
495 @param leafCertLen return value, length of the verified leaf certificate
496 @param policyFlags return value, the CoreTrust policies that the certificate chain met
497 @param cmsDigestType return value, the digest type used to sign the CMS object
498 @param hashAgilityDigestType return value, the highest strength digest type available and supported by client in the hash agility attribute
499 @param digestData return value, pointer to the hash agility value
500 @param digestLen return value, length of the hash agility value
501 @return 0 upon success, a parsing or validation error (see CTErrors.h)
502 @discussion
503 Returns non-zero if there's a standards-based problem with the CMS or certificates.
504 Policy matching of the certificates is only reflected in the policyFlags output. Namely, if the only problem is that
505 the certificates don't match a policy, the returned integer will be 0 (success) and the policyFlags will be 0 (no matching policies).
506 Some notes about hash agility outputs:
507 - hashAgilityDigestType is only non-zero for HashAgilityV2
508 - If hashAgilityDigestType is non-zero, digestData/Len provides the digest value
509 - If hashAgilityDigestType is zero, digestData/Len provides the content of the HashAgilityV1 attribute (if present)
510 - If neither HashAgilityV1 nor HashAgilityV2 attributes are found, these outputs will all be NULL.
511 */
512CT_int CTEvaluateAMFICodeSignatureCMS_MaxDigestType(
513 const CT_uint8_t *__counted_by(cmsLen) cmsData, CT_size_t cmsLen,
514 const CT_uint8_t *__counted_by(detachedDataLen) detachedData, CT_size_t detachedDataLen,
515 CT_bool allow_test_hierarchy,
516 CoreTrustDigestType maxDigestType,
517 const CT_uint8_t *__counted_by(*leafCertLen) *leafCert, CT_size_t *leafCertLen,
518 CoreTrustPolicyFlags *policyFlags,
519 CoreTrustDigestType *cmsDigestType,
520 CoreTrustDigestType *hashAgilityDigestType,
521 const CT_uint8_t *__counted_by(*digestLen) *digestData, CT_size_t *digestLen);
522
523/*! @function CTEvaluateAMFICodeSignatureCMSPubKey
524 @abstract Verify CMS signature and certificates against the AMFI policies
525 @param cmsData pointer to beginning of the binary (BER-encoded) CMS object
526 @param cmsLen the length of the CMS object
527 @param detachedData pointer to data that is signed by the CMS object
528 @param detachedDataLen the length of the signed data
529 @param anchorPublicKey anchor public key for self-signed certificate
530 @param anchorPublicKeyLen length of the anchor public key
531 @param cmsDigestType return value, the digest type used to sign the CMS object
532 @param hashAgilityDigestType return value, the highest strength digest type available and supported by client in the hash agility attribute
533 @param digestData return value, pointer to the hash agility value
534 @param digestLen return value, length of the hash agility value
535 @return 0 upon success, a parsing or validation error (see CTErrors.h)
536 @discussion
537 Returns non-zero if there's a standards-based problem with the CMS or certificates.
538 Policy matching of the certificates is only reflected in the policyFlags output. Namely, if the only problem is that
539 the certificates don't match a policy, the returned integer will be 0 (success) and the policyFlags will be 0 (no matching policies).
540 Some notes about hash agility outputs:
541 - hashAgilityDigestType is only non-zero for HashAgilityV2
542 - If hashAgilityDigestType is non-zero, digestData/Len provides the digest value
543 - If hashAgilityDigestType is zero, digestData/Len provides the content of the HashAgilityV1 attribute (if present)
544 - If neither HashAgilityV1 nor HashAgilityV2 attributes are found, these outputs will all be NULL.
545 */
546int CTEvaluateAMFICodeSignatureCMSPubKey(
547 const CT_uint8_t *__counted_by(cmsLen) cmsData, CT_size_t cmsLen,
548 const CT_uint8_t *__counted_by(detachedDataLen) detachedData, CT_size_t detachedDataLen,
549 const CT_uint8_t *__counted_by(anchorPublicKeyLen) anchorPublicKey, CT_size_t anchorPublicKeyLen,
550 CoreTrustDigestType *cmsDigestType,
551 CoreTrustDigestType *hashAgilityDigestType,
552 const CT_uint8_t *__counted_by(*digestLen) *digestData, CT_size_t *digestLen);
553
554/*! @function CTParseAccessoryCerts
555 @abstract Parse a CMS or binary encoded set of certificates and return the leaf and subCA(s)
556 @param certsData pointer to beginning of the binary (DER-encoded) certificates or binary (BER-encoded) CMS object
557 @param certsLen the length of the input certificates
558 @param leafCertData return value, pointer to the leaf certificate
559 @param leafCertLen return value, length of the leaf certificate
560 @param subCACertData return value, pointer to the subCA certificate(s), if present, null otherwise
561 @param subCACertLen return value, length of the subCA certificates
562 @param flags return value, the policy flags set by the leaf certificate (to indicate which type of accessory cert)
563 @return 0 upon success, a parsing error (see CTErrors.h) */
564CT_int CTParseAccessoryCerts(
565 const CT_uint8_t *__counted_by(certsLen) certsData, CT_size_t certsLen,
566 const CT_uint8_t *__counted_by(*leafCertLen) *leafCertData, CT_size_t *leafCertLen,
567 const CT_uint8_t *__counted_by(*subCACertLen) *subCACertData, CT_size_t *subCACertLen,
568 CoreTrustPolicyFlags *flags);
569
570/*! @function CTEvaluateAccessoryCert
571 @abstract Verify certificates against a specified accessory policy and anchor
572 @param leafCertData pointer to beginning of the binary (DER-encoded) leaf certificate
573 @param leafCertLen the length of the leaf certificate
574 @param subCACertData optional pointer to beginning of the binary (DER-encoded) subCA certificate(s)
575 @param subCACertLen the length of thesubCA certificate(s)
576 @param anchorCertData pointer to beginning of the binary (DER-encoded) anchor certificate
577 @param anchorCertLen the length of the anchor certificate
578 @param policy the policy to verify the certificates against, see discussion
579 @param leafKeyData return value, pointer to the key in the verified leaf certificate
580 @param leafKeyLen return value, length of the key in the verified leaf certificate
581 @param extensionValueData return value, pointer to the extension value in the verified leaf certificate, see discussion
582 @param extensionValueLen return value, length of the extension value in the verified leaf certificate
583 @return 0 upon success, a parsing or validation error (see CTErrors.h)
584 @discussion It is expected that callers will first use CTParseAccessoryCerts and then pass that data into CTEvaluateAccessoryCert.
585 Which extension value is returned is based on which policy the cert was verified against:
586 - For MFI AuthV3, this is the value of the extension with OID 1.2.840.113635.100.6.36
587 - For SW Auth, this is the value of the extension with OID 1.2.840.113635.100.6.59.1 (GeneralCapabilities extension)
588 - For Component certs, this si the value of the extension with OID 1.2.840.113635.100.11.1 (Component Type)
589 - For MFi AuthV4, this is the value of the extension with OID 1.2.840.113635.100.6.71.1 (Apple Accessory Properties extension)
590 The following CoreTrustPolicyFlags are accepted:
591 - CORETRUST_POLICY_BASIC
592 - CORETRUST_POLICY_MFI_AUTHV2
593 - CORETRUST_POLICY_MFI_AUTHV3
594 - CORETRUST_POLICY_MFI_SW_AUTH_DEV
595 - CORETRUST_POLICY_MFI_SW_AUTH_PROD
596 - CORETRUST_POLICY_COMPONENT
597 - CORETRUST_POLICY_MFI_AUTHV4_ACCESSORY
598 - CORETRUST_POLICY_MFI_AUTHV4_ATTESTATION
599 - CORETRUST_POLICY_MFI_AUTHV4_PROVISIONING
600 */
601CT_int CTEvaluateAccessoryCert(
602 const CT_uint8_t *__counted_by(leafCertLen) leafCertData, CT_size_t leafCertLen,
603 const CT_uint8_t *__counted_by(subCACertLen) subCACertData, CT_size_t subCACertLen,
604 const CT_uint8_t *__counted_by(anchorCertLen) anchorCertData, CT_size_t anchorCertLen,
605 CoreTrustPolicyFlags policy,
606 const CT_uint8_t *__counted_by(*leafKeyLen) *leafKeyData, CT_size_t *leafKeyLen,
607 const CT_uint8_t *__counted_by(*extensionValueLen) *extensionValueData, CT_size_t *extensionValueLen);
608
609/*! @function CTEvaluateAppleSSL
610 @abstract Verify certificates against an Apple SSL pinning policy
611 @param certsData pointer to beginning of the binary (DER-encoded) certificates (leaf first)
612 @param certsLen the length of the certificates byte array
613 @param hostnameData the hostname of the server being connected to
614 @param hostnameLen length of the hostname
615 @param leafMarker the last decimat of the leaf marker OID for this project (e.g. 32 for 1.2.840.113635.100.6.27.32)
616 @param allowTestRoots allow the Test Apple roots to be used as anchors in addition to the production roots
617 @return 0 upon success, a parsing or validation error (see CTErrors.h) */
618CT_int CTEvaluateAppleSSL(
619 const CT_uint8_t *__counted_by(certsLen) certsData, CT_size_t certsLen,
620 const CT_uint8_t *__counted_by(hostnameLen) hostnameData, CT_size_t hostnameLen,
621 CT_uint64_t leafMarker,
622 CT_bool allowTestRoots);
623
624/*! @function CTEvaluateAppleSSLWithOptionalTemporalCheck
625 @abstract Verify certificates against an Apple SSL pinning policy
626 @param certsData pointer to beginning of the binary (DER-encoded) certificates (leaf first)
627 @param certsLen the length of the certificates byte array
628 @param hostnameData the hostname of the server being connected to
629 @param hostnameLen length of the hostname
630 @param leafMarker the last decimat of the leaf marker OID for this project (e.g. 32 for 1.2.840.113635.100.6.27.32)
631 @param allowTestRoots allow the Test Apple roots to be used as anchors in addition to the production roots
632 @param checkTemporalValidity indicate whether to check the temporal validity of certificates
633 @return 0 upon success, a parsing or validation error (see CTErrors.h) */
634CT_int CTEvaluateAppleSSLWithOptionalTemporalCheck(
635 const CT_uint8_t *__counted_by(certsLen) certsData, CT_size_t certsLen,
636 const CT_uint8_t *__counted_by(hostnameLen) hostnameData, CT_size_t hostnameLen,
637 CT_uint64_t leafMarker,
638 CT_bool allowTestRoots,
639 CT_bool checkTemporalValidity);
640
641/*! @function CTEvaluateProvisioningProfile
642 @abstract Parse and verify the certificates of a signed provisioning profile
643 @param provisioningProfileData pointer to beginning of the binary (BER-encoded) provisioning profile CMS object
644 @param provisioningProfileLen the length of the provisioning profile
645 @param allowTestRoots allow the Test Apple roots to be used as anchors in addition to the production roots
646 @param contentData return value, pointer to the profile content
647 @param contentLen return value, length of the profile content
648 @return 0 upon success, a parsing or validation error (see CTErrors.h) */
649int CTEvaluateProvisioningProfile(
650 const CT_uint8_t *__counted_by(provisioningProfileLen) provisioningProfileData, CT_size_t provisioningProfileLen,
651 CT_bool allowTestRoots,
652 const CT_uint8_t *__counted_by(*contentLen) *contentData, CT_size_t *contentLen);
653
654__END_DECLS
655
656#endif /* _CORETRUST_EVALUATE_H_ */
657