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