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 }; 375 376 typedef CT_uint32_t CoreTrustDigestType; 377 enum { 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 */ 398 CT_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 */ 425 CT_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 */ 445 CT_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 */ 476 CT_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 */ 512 CT_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 */ 546 int 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) */ 564 CT_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 */ 601 CT_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) */ 618 CT_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) */ 634 CT_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) */ 649 int 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