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 17 typedef struct x509_octet_string { 18 const CT_uint8_t * __counted_by(length) data; 19 CT_size_t length; 20 } CTAsn1Item; 21 22 extern const CTAsn1Item CTOidItemAppleImg4Manifest; //1.2.840.113635.100.6.1.15 23 24 extern const CTAsn1Item CTOidItemAppleDeviceAttestationNonce; // 1.2.840.113635.100.8.2 25 extern const CTAsn1Item CTOidItemAppleDeviceAttestationHardwareProperties; // 1.2.840.113635.100.8.4 26 extern const CTAsn1Item CTOidItemAppleDeviceAttestationKeyUsageProperties; // 1.2.840.113635.100.8.5 27 extern 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) */ 38 CT_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) */ 54 CT_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) */ 69 CT_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) */ 85 CT_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) */ 103 CT_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) */ 122 CT_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) */ 143 CT_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) */ 158 CT_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) */ 169 CT_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) */ 182 CT_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) */ 194 CT_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 198 typedef 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) */ 215 CT_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) */ 230 CT_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) */ 244 CT_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) */ 259 CT_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) */ 276 CT_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) */ 290 CT_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) */ 305 CT_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) */ 321 CT_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 327 typedef CT_uint64_t CoreTrustPolicyFlags; 328 enum { 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 CORETRUST_POLICY_XROS_APP_PROD = 1ULL << 43, 375 CORETRUST_POLICY_XROS_APP_DEV = 1ULL << 44, 376 CORETRUST_POLICY_BAA_SEP_APP = 1ULL << 45, 377 CORETRUST_POLICY_MAC_APP_STORE_DEV = 1ULL << 46, 378 CORETRUST_POLICY_MAC_PLATFORM_QA = 1ULL << 47, 379 }; 380 381 typedef CT_uint32_t CoreTrustDigestType; 382 enum { 383 CORETRUST_DIGEST_TYPE_SHA1 = 1, 384 CORETRUST_DIGEST_TYPE_SHA224 = 2, 385 CORETRUST_DIGEST_TYPE_SHA256 = 4, 386 CORETRUST_DIGEST_TYPE_SHA384 = 8, 387 CORETRUST_DIGEST_TYPE_SHA512 = 16 388 }; 389 390 /*! @function CTParseAmfiCMS 391 @abstract Parse CMS signed data 392 @param cmsData pointer to beginning of the binary (BER-encoded) CMS object 393 @param cmsLen the length of the CMS object 394 @param maxDigestType maximum digest type supported by the client 395 @param leafCert return value, pointer to the verified leaf certificate 396 @param leafCertLen return value, length of the verified leaf certificate 397 @param contentData return value, pointer to the CMS content, if present 398 @param contentLen return value, length of the CMS content, if present 399 @param cmsDigestType return value, the digest type used to sign the CMS object 400 @param policyFlags return value, the CoreTrust policies that the chain may meet (based on leaf certificate only) 401 @return 0 upon success, a parsing error (see CTErrors.h) 402 */ 403 CT_int CTParseAmfiCMS( 404 const CT_uint8_t *__counted_by(cmsLen) cmsData, CT_size_t cmsLen, 405 CoreTrustDigestType maxDigestType, 406 const CT_uint8_t *__counted_by(*leafCertLen) *leafCert, CT_size_t *leafCertLen, 407 const CT_uint8_t *__counted_by(*contentLen) *contentData, CT_size_t *contentLen, 408 CoreTrustDigestType *cmsDigestType, 409 CoreTrustPolicyFlags *policyFlags); 410 411 /*! @function CTVerifyAmfiCMS 412 @abstract Verify CMS signed data signature 413 @param cmsData pointer to beginning of the binary (BER-encoded) CMS object 414 @param cmsLen the length of the CMS object 415 @param digestData pointer to beginning of the content data hash 416 @param digestLen the length of the content data hash 417 @param maxDigestType maximum digest type supported by the client 418 @param hashAgilityDigestType return value, the highest strength digest type available in the hash agility attribute 419 @param hashAgilityDigestData return value, pointer to the hash agility value 420 @param hashAgilityDigestLen return value, length of the hash agility value 421 @return 0 upon success, a parsing or validation error (see CTErrors.h) 422 @discussion 423 Returns non-zero if there's a standards-based problem with the CMS or certificates. 424 Some notes about hash agility outputs: 425 - hashAgilityDigestType is only non-zero for HashAgilityV2 426 - If hashAgilityDigestType is non-zero, digestData/Len provides the digest value 427 - If hashAgilityDigestType is zero, digestData/Len provides the content of the HashAgilityV1 attribute (if present) 428 - If neither HashAgilityV1 nor HashAgilityV2 attributes are found, these outputs will all be NULL. 429 */ 430 CT_int CTVerifyAmfiCMS( 431 const CT_uint8_t *__counted_by(cmsLen) cmsData, CT_size_t cmsLen, 432 const CT_uint8_t *__counted_by(digestLen) digestData, CT_size_t digestLen, 433 CoreTrustDigestType maxDigestType, 434 CoreTrustDigestType *hashAgilityDigestType, 435 const CT_uint8_t *__counted_by(*hashAgilityDigestLen) *hashAgilityDigestData, CT_size_t *hashAgilityDigestLen); 436 437 /*! @function CTVerifyAmfiCertificateChain 438 @abstract Verify CMS signed data certificate chain 439 @param cmsData pointer to beginning of the binary (BER-encoded) CMS object 440 @param cmsLen the length of the CMS object 441 @param allow_test_hierarchy allow the Test Apple roots to be used as anchors in addition to the production roots 442 @param maxDigestType maximum digest type supported by the client 443 @param policyFlags return value, the CoreTrust policies that the certificate chain met 444 @return 0 upon success, a parsing or validation error (see CTErrors.h) 445 @discussion 446 Returns non-zero if there's a standards-based problem with the CMS or certificates. 447 Policy matching of the certificates is only reflected in the policyFlags output. Namely, if the only problem is that 448 the certificates don't match a policy, the returned integer will be 0 (success) and the policyFlags will be 0 (no matching policies). 449 */ 450 CT_int CTVerifyAmfiCertificateChain( 451 const CT_uint8_t *__counted_by(cmsLen) cmsData, CT_size_t cmsLen, 452 CT_bool allow_test_hierarchy, 453 CoreTrustDigestType maxDigestType, 454 CoreTrustPolicyFlags *policyFlags); 455 456 /*! @function CTEvaluateAMFICodeSignatureCMS 457 @abstract Verify CMS signature and certificates against the AMFI policies 458 @param cmsData pointer to beginning of the binary (BER-encoded) CMS object 459 @param cmsLen the length of the CMS object 460 @param detachedData pointer to data that is signed by the CMS object 461 @param detachedDataLen the length of the signed data 462 @param allow_test_hierarchy allow the Test Apple roots to be used as anchors in addition to the production roots 463 @param leafCert return value, pointer to the verified leaf certificate 464 @param leafCertLen return value, length of the verified leaf certificate 465 @param policyFlags return value, the CoreTrust policies that the certificate chain met 466 @param cmsDigestType return value, the digest type used to sign the CMS object 467 @param hashAgilityDigestType return value, the highest strength digest type available in the hash agility attribute 468 @param digestData return value, pointer to the hash agility value 469 @param digestLen return value, length of the hash agility value 470 @return 0 upon success, a parsing or validation error (see CTErrors.h) 471 @discussion 472 Returns non-zero if there's a standards-based problem with the CMS or certificates. 473 Policy matching of the certificates is only reflected in the policyFlags output. Namely, if the only problem is that 474 the certificates don't match a policy, the returned integer will be 0 (success) and the policyFlags will be 0 (no matching policies). 475 Some notes about hash agility outputs: 476 - hashAgilityDigestType is only non-zero for HashAgilityV2 477 - If hashAgilityDigestType is non-zero, digestData/Len provides the digest value 478 - If hashAgilityDigestType is zero, digestData/Len provides the content of the HashAgilityV1 attribute (if present) 479 - If neither HashAgilityV1 nor HashAgilityV2 attributes are found, these outputs will all be NULL. 480 */ 481 CT_int CTEvaluateAMFICodeSignatureCMS( 482 const CT_uint8_t *__counted_by(cmsLen) cmsData, CT_size_t cmsLen, 483 const CT_uint8_t *__counted_by(detachedDataLen) detachedData, CT_size_t detachedDataLen, 484 CT_bool allow_test_hierarchy, 485 const CT_uint8_t *__counted_by(*leafCertLen) *leafCert, CT_size_t *leafCertLen, 486 CoreTrustPolicyFlags *policyFlags, 487 CoreTrustDigestType *cmsDigestType, 488 CoreTrustDigestType *hashAgilityDigestType, 489 const CT_uint8_t *__counted_by(*digestLen) *digestData, CT_size_t *digestLen); 490 491 /*! @function CTEvaluateAMFICodeSignatureCMS_MaxDigestType 492 @abstract Verify CMS signature and certificates against the AMFI policies 493 @param cmsData pointer to beginning of the binary (BER-encoded) CMS object 494 @param cmsLen the length of the CMS object 495 @param detachedData pointer to data that is signed by the CMS object 496 @param detachedDataLen the length of the signed data 497 @param allow_test_hierarchy allow the Test Apple roots to be used as anchors in addition to the production roots 498 @param maxDigestType maximum digest type supported by the client 499 @param leafCert return value, pointer to the verified leaf certificate 500 @param leafCertLen return value, length of the verified leaf certificate 501 @param policyFlags return value, the CoreTrust policies that the certificate chain met 502 @param cmsDigestType return value, the digest type used to sign the CMS object 503 @param hashAgilityDigestType return value, the highest strength digest type available and supported by client in the hash agility attribute 504 @param digestData return value, pointer to the hash agility value 505 @param digestLen return value, length of the hash agility value 506 @return 0 upon success, a parsing or validation error (see CTErrors.h) 507 @discussion 508 Returns non-zero if there's a standards-based problem with the CMS or certificates. 509 Policy matching of the certificates is only reflected in the policyFlags output. Namely, if the only problem is that 510 the certificates don't match a policy, the returned integer will be 0 (success) and the policyFlags will be 0 (no matching policies). 511 Some notes about hash agility outputs: 512 - hashAgilityDigestType is only non-zero for HashAgilityV2 513 - If hashAgilityDigestType is non-zero, digestData/Len provides the digest value 514 - If hashAgilityDigestType is zero, digestData/Len provides the content of the HashAgilityV1 attribute (if present) 515 - If neither HashAgilityV1 nor HashAgilityV2 attributes are found, these outputs will all be NULL. 516 */ 517 CT_int CTEvaluateAMFICodeSignatureCMS_MaxDigestType( 518 const CT_uint8_t *__counted_by(cmsLen) cmsData, CT_size_t cmsLen, 519 const CT_uint8_t *__counted_by(detachedDataLen) detachedData, CT_size_t detachedDataLen, 520 CT_bool allow_test_hierarchy, 521 CoreTrustDigestType maxDigestType, 522 const CT_uint8_t *__counted_by(*leafCertLen) *leafCert, CT_size_t *leafCertLen, 523 CoreTrustPolicyFlags *policyFlags, 524 CoreTrustDigestType *cmsDigestType, 525 CoreTrustDigestType *hashAgilityDigestType, 526 const CT_uint8_t *__counted_by(*digestLen) *digestData, CT_size_t *digestLen); 527 528 /*! @function CTEvaluateAMFICodeSignatureCMSPubKey 529 @abstract Verify CMS signature and certificates against the AMFI policies 530 @param cmsData pointer to beginning of the binary (BER-encoded) CMS object 531 @param cmsLen the length of the CMS object 532 @param detachedData pointer to data that is signed by the CMS object 533 @param detachedDataLen the length of the signed data 534 @param anchorPublicKey anchor public key for self-signed certificate 535 @param anchorPublicKeyLen length of the anchor public key 536 @param cmsDigestType return value, the digest type used to sign the CMS object 537 @param hashAgilityDigestType return value, the highest strength digest type available and supported by client in the hash agility attribute 538 @param digestData return value, pointer to the hash agility value 539 @param digestLen return value, length of the hash agility value 540 @return 0 upon success, a parsing or validation error (see CTErrors.h) 541 @discussion 542 Returns non-zero if there's a standards-based problem with the CMS or certificates. 543 Policy matching of the certificates is only reflected in the policyFlags output. Namely, if the only problem is that 544 the certificates don't match a policy, the returned integer will be 0 (success) and the policyFlags will be 0 (no matching policies). 545 Some notes about hash agility outputs: 546 - hashAgilityDigestType is only non-zero for HashAgilityV2 547 - If hashAgilityDigestType is non-zero, digestData/Len provides the digest value 548 - If hashAgilityDigestType is zero, digestData/Len provides the content of the HashAgilityV1 attribute (if present) 549 - If neither HashAgilityV1 nor HashAgilityV2 attributes are found, these outputs will all be NULL. 550 */ 551 int CTEvaluateAMFICodeSignatureCMSPubKey( 552 const CT_uint8_t *__counted_by(cmsLen) cmsData, CT_size_t cmsLen, 553 const CT_uint8_t *__counted_by(detachedDataLen) detachedData, CT_size_t detachedDataLen, 554 const CT_uint8_t *__counted_by(anchorPublicKeyLen) anchorPublicKey, CT_size_t anchorPublicKeyLen, 555 CoreTrustDigestType *cmsDigestType, 556 CoreTrustDigestType *hashAgilityDigestType, 557 const CT_uint8_t *__counted_by(*digestLen) *digestData, CT_size_t *digestLen); 558 559 /*! @function CTParseAccessoryCerts 560 @abstract Parse a CMS or binary encoded set of certificates and return the leaf and subCA(s) 561 @param certsData pointer to beginning of the binary (DER-encoded) certificates or binary (BER-encoded) CMS object 562 @param certsLen the length of the input certificates 563 @param leafCertData return value, pointer to the leaf certificate 564 @param leafCertLen return value, length of the leaf certificate 565 @param subCACertData return value, pointer to the subCA certificate(s), if present, null otherwise 566 @param subCACertLen return value, length of the subCA certificates 567 @param flags return value, the policy flags set by the leaf certificate (to indicate which type of accessory cert) 568 @return 0 upon success, a parsing error (see CTErrors.h) */ 569 CT_int CTParseAccessoryCerts( 570 const CT_uint8_t *__counted_by(certsLen) certsData, CT_size_t certsLen, 571 const CT_uint8_t *__counted_by(*leafCertLen) *leafCertData, CT_size_t *leafCertLen, 572 const CT_uint8_t *__counted_by(*subCACertLen) *subCACertData, CT_size_t *subCACertLen, 573 CoreTrustPolicyFlags *flags); 574 575 /*! @function CTEvaluateAccessoryCert 576 @abstract Verify certificates against a specified accessory policy and anchor 577 @param leafCertData pointer to beginning of the binary (DER-encoded) leaf certificate 578 @param leafCertLen the length of the leaf certificate 579 @param subCACertData optional pointer to beginning of the binary (DER-encoded) subCA certificate(s) 580 @param subCACertLen the length of thesubCA certificate(s) 581 @param anchorCertData pointer to beginning of the binary (DER-encoded) anchor certificate 582 @param anchorCertLen the length of the anchor certificate 583 @param policy the policy to verify the certificates against, see discussion 584 @param leafKeyData return value, pointer to the key in the verified leaf certificate 585 @param leafKeyLen return value, length of the key in the verified leaf certificate 586 @param extensionValueData return value, pointer to the extension value in the verified leaf certificate, see discussion 587 @param extensionValueLen return value, length of the extension value in the verified leaf certificate 588 @return 0 upon success, a parsing or validation error (see CTErrors.h) 589 @discussion It is expected that callers will first use CTParseAccessoryCerts and then pass that data into CTEvaluateAccessoryCert. 590 Which extension value is returned is based on which policy the cert was verified against: 591 - For MFI AuthV3, this is the value of the extension with OID 1.2.840.113635.100.6.36 592 - For SW Auth, this is the value of the extension with OID 1.2.840.113635.100.6.59.1 (GeneralCapabilities extension) 593 - For Component certs, this si the value of the extension with OID 1.2.840.113635.100.11.1 (Component Type) 594 - For MFi AuthV4, this is the value of the extension with OID 1.2.840.113635.100.6.71.1 (Apple Accessory Properties extension) 595 The following CoreTrustPolicyFlags are accepted: 596 - CORETRUST_POLICY_BASIC 597 - CORETRUST_POLICY_MFI_AUTHV2 598 - CORETRUST_POLICY_MFI_AUTHV3 599 - CORETRUST_POLICY_MFI_SW_AUTH_DEV 600 - CORETRUST_POLICY_MFI_SW_AUTH_PROD 601 - CORETRUST_POLICY_COMPONENT 602 - CORETRUST_POLICY_MFI_AUTHV4_ACCESSORY 603 - CORETRUST_POLICY_MFI_AUTHV4_ATTESTATION 604 - CORETRUST_POLICY_MFI_AUTHV4_PROVISIONING 605 */ 606 CT_int CTEvaluateAccessoryCert( 607 const CT_uint8_t *__counted_by(leafCertLen) leafCertData, CT_size_t leafCertLen, 608 const CT_uint8_t *__counted_by(subCACertLen) subCACertData, CT_size_t subCACertLen, 609 const CT_uint8_t *__counted_by(anchorCertLen) anchorCertData, CT_size_t anchorCertLen, 610 CoreTrustPolicyFlags policy, 611 const CT_uint8_t *__counted_by(*leafKeyLen) *leafKeyData, CT_size_t *leafKeyLen, 612 const CT_uint8_t *__counted_by(*extensionValueLen) *extensionValueData, CT_size_t *extensionValueLen); 613 614 /*! @function CTEvaluateAppleSSL 615 @abstract Verify certificates against an Apple SSL pinning policy 616 @param certsData pointer to beginning of the binary (DER-encoded) certificates (leaf first) 617 @param certsLen the length of the certificates byte array 618 @param hostnameData the hostname of the server being connected to 619 @param hostnameLen length of the hostname 620 @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) 621 @param allowTestRoots allow the Test Apple roots to be used as anchors in addition to the production roots 622 @return 0 upon success, a parsing or validation error (see CTErrors.h) */ 623 CT_int CTEvaluateAppleSSL( 624 const CT_uint8_t *__counted_by(certsLen) certsData, CT_size_t certsLen, 625 const CT_uint8_t *__counted_by(hostnameLen) hostnameData, CT_size_t hostnameLen, 626 CT_uint64_t leafMarker, 627 CT_bool allowTestRoots); 628 629 /*! @function CTEvaluateAppleSSLWithOptionalTemporalCheck 630 @abstract Verify certificates against an Apple SSL pinning policy 631 @param certsData pointer to beginning of the binary (DER-encoded) certificates (leaf first) 632 @param certsLen the length of the certificates byte array 633 @param hostnameData the hostname of the server being connected to 634 @param hostnameLen length of the hostname 635 @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) 636 @param allowTestRoots allow the Test Apple roots to be used as anchors in addition to the production roots 637 @param checkTemporalValidity indicate whether to check the temporal validity of certificates 638 @return 0 upon success, a parsing or validation error (see CTErrors.h) */ 639 CT_int CTEvaluateAppleSSLWithOptionalTemporalCheck( 640 const CT_uint8_t *__counted_by(certsLen) certsData, CT_size_t certsLen, 641 const CT_uint8_t *__counted_by(hostnameLen) hostnameData, CT_size_t hostnameLen, 642 CT_uint64_t leafMarker, 643 CT_bool allowTestRoots, 644 CT_bool checkTemporalValidity); 645 646 /*! @function CTEvaluateProvisioningProfile 647 @abstract Parse and verify the certificates of a signed provisioning profile 648 @param provisioningProfileData pointer to beginning of the binary (BER-encoded) provisioning profile CMS object 649 @param provisioningProfileLen the length of the provisioning profile 650 @param allowTestRoots allow the Test Apple roots to be used as anchors in addition to the production roots 651 @param contentData return value, pointer to the profile content 652 @param contentLen return value, length of the profile content 653 @return 0 upon success, a parsing or validation error (see CTErrors.h) */ 654 int CTEvaluateProvisioningProfile( 655 const CT_uint8_t *__counted_by(provisioningProfileLen) provisioningProfileData, CT_size_t provisioningProfileLen, 656 CT_bool allowTestRoots, 657 const CT_uint8_t *__counted_by(*contentLen) *contentData, CT_size_t *contentLen); 658 659 __END_DECLS 660 661 #endif /* _CORETRUST_EVALUATE_H_ */ 662