CTEvaluate.h

//
//  CoreTrust.h
//  CoreTrust
//
//  Copyright © 2017-2020 Apple Inc. All rights reserved.
//

#ifndef _CORETRUST_EVALUATE_H_
#define _CORETRUST_EVALUATE_H_

#if !defined(EFI) || !EFI
#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
#else // EFI
// This requires $(SDKROOT)/usr/local/efi/include/Platform to be in your header
// search path.
#include <Apple/Common/Library/Include/EfiCompatibility.h>
#endif // EFI

#if EFI
    #if defined(__cplusplus)
        #define __BEGIN_DECLS extern "C" {
        #define __END_DECLS }
    #else
        #define __BEGIN_DECLS
        #define __END_DECLS
    #endif
#else // !EFI
#include <sys/cdefs.h>
#endif // !EFI

__BEGIN_DECLS

#if !EFI
typedef uint8_t CT_uint8_t;
typedef uint32_t CT_uint32_t;
typedef uint64_t CT_uint64_t;
typedef size_t CT_size_t;
typedef int CT_int;
typedef bool CT_bool;
#else
typedef UINT8 CT_uint8_t;
typedef UINT32 CT_uint32_t;
typedef INT32 CT_int;
typedef UINT64 CT_uint64_t;
typedef size_t CT_size_t;
typedef BOOLEAN CT_bool;
#endif

typedef struct x509_octet_string {
    const CT_uint8_t *data;
    CT_size_t length;
} CTAsn1Item;

extern const CTAsn1Item CTOidItemAppleDeviceAttestationNonce;               // 1.2.840.113635.100.8.2
extern const CTAsn1Item CTOidItemAppleDeviceAttestationHardwareProperties;  // 1.2.840.113635.100.8.4
extern const CTAsn1Item CTOidItemAppleDeviceAttestationKeyUsageProperties;  // 1.2.840.113635.100.8.5
extern const CTAsn1Item CTOidItemAppleDeviceAttestationDeviceOSInformation; // 1.2.840.113635.100.8.7

CT_int CTParseCertificateSet(
    const CT_uint8_t *der, const CT_uint8_t *der_end,     // Input: binary representation of concatenated DER-encoded certs
    CTAsn1Item *certStorage, CT_size_t certStorageLen,    // Output: An array of certStorageLen CTAsn1Items that will be populated with the
                                                          //    CTAsn1Item for each parsed cert (in the same order as input)
    CT_size_t *numParsedCerts);                           // Output: number of successfully parsed certs

CT_int CTParseExtensionValue(
    const CT_uint8_t *certData, CT_size_t certLen,                          // Input: binary representation of DER-encoded cert
    const CT_uint8_t *extensionOidData, CT_size_t extensionOidLen,          // Input: extension OID to return value
    const CT_uint8_t **extensionValueData, CT_size_t *extensionValueLen);   // Output: points to the extension value

CT_int CTEvaluateSavageCerts(
    const CT_uint8_t *certsData, CT_size_t certsLen,
    const CT_uint8_t *rootKeyData, CT_size_t rootKeyLen,
    const CT_uint8_t **leafKeyData, CT_size_t *leafKeyLen,
    CT_bool *isProdCert);

CT_int CTEvaluateSavageCertsWithUID(
    const CT_uint8_t *certsData, CT_size_t certsLen,
    const CT_uint8_t *rootKeyData, CT_size_t rootKeyLen,
    const CT_uint8_t **leafKeyData, CT_size_t *leafKeyLen, // Output: points to the leaf key data in the input certsData
    CT_uint8_t *UIDData, CT_size_t UIDLen,                 // Output: a pre-allocated buffer of UIDLen
    CT_bool *isProdCert);

CT_int CTEvaluateYonkersCerts(
    const CT_uint8_t *certsData, CT_size_t certsLen,
    const CT_uint8_t *rootKeyData, CT_size_t rootKeyLen,
    const CT_uint8_t **leafKeyData, CT_size_t *leafKeyLen, // Output: points to the leaf key data in the input certsData
    CT_uint8_t *UIDData, CT_size_t UIDLen,                 // Output: a pre-allocated buffer of UIDLen
    CT_bool *isProdCert);

CT_int CTEvaluateAcrt(
    const CT_uint8_t *certsData, CT_size_t certsLen,         // Input: binary representation of at most 3 concatenated certs
                                                             //         with leaf first (root may be omitted)
    const CT_uint8_t **leafKeyData, CT_size_t *leafKeyLen);  // Output: points to the leaf key data in the input certsData

CT_int CTEvaluateUcrt(
    const CT_uint8_t *certsData, CT_size_t certsLen,         // Input: binary representation of exactly 3 concatenated
                                                             //        DER-encoded certs, with leaf first
    const CT_uint8_t **leafKeyData, CT_size_t *leafKeyLen);  // Output: points to the leaf key data in the input certsData)

CT_int CTEvaluateUcrtTestRoot(
    const CT_uint8_t *certsData, CT_size_t certsLen,         // Input: binary representation of exactly 3 concatenated
                                                             //        DER-encoded certs, with leaf first
    const CT_uint8_t *rootKeyData, CT_size_t rootKeyLen,     // Input: Root public key, if not specified production root will be used
    const CT_uint8_t **leafKeyData, CT_size_t *leafKeyLen);  // Output: points to the leaf key data in the input certsData)

CT_int CTEvaluateBAASystem(
    const CT_uint8_t *certsData, CT_size_t certsLen,        // Input: binary representation of exactly 3 concatenated
                                                            //        DER-encoded certs, with leaf first
    const CT_uint8_t **leafKeyData, CT_size_t *leafKeyLen); // Output: points to the leaf key data in the input certsData

typedef struct baa_identity {
    CT_uint32_t chipId;
    CT_uint64_t ecid;
    CT_bool productionStatus;
    CT_bool securityMode;
    CT_uint8_t securityDomain;
    CTAsn1Item img4;
} CTBAAIdentity;

CT_int CTEvaluateBAASystemWithId(
    const CT_uint8_t *certsData, CT_size_t certsLen,          // Input: binary representation of exactly 3 concatenated
                                                              //        DER-encoded certs, with leaf first
    const CT_uint8_t **leafKeyData, CT_size_t *leafKeyLen,    // Output: points to the leaf key data in the input certsData
    CTBAAIdentity *identity);                                 // Output from identity field in leaf certificate

CT_int CTEvaluateBAASystemTestRoot(
    const CT_uint8_t *certsData, CT_size_t certsLen,        // Input: binary representation of exactly 3 concatenated
                                                            //        DER-encoded certs, with leaf first
    const CT_uint8_t *rootKeyData, CT_size_t rootKeyLen,    // Input: Root public key, if not specified production root will be used
    const CT_uint8_t **leafKeyData, CT_size_t *leafKeyLen,  // Output: points to the leaf key data in the input certsData
    CTBAAIdentity *identity);                               // Output from identity field in leaf certificate

CT_int CTEvaluateBAAUser(
    const CT_uint8_t *certsData, CT_size_t certsLen,          // Input: binary representation of exactly 3 concatenated
                                                              //        DER-encoded certs, with leaf first
    const CT_uint8_t **leafKeyData, CT_size_t *leafKeyLen,    // Output: points to the leaf key data in the input certsData
    CTBAAIdentity *identity);                                 // Output from identity field in leaf certificate

CT_int CTEvaluateBAAUserTestRoot(
    const CT_uint8_t *certsData, CT_size_t certsLen,        // Input: binary representation of exactly 3 concatenated
                                                            //        DER-encoded certs, with leaf first
    const CT_uint8_t *rootKeyData, CT_size_t rootKeyLen,    // Input: Root public key, if not specified production root will be used
    const CT_uint8_t **leafKeyData, CT_size_t *leafKeyLen,  // Output: points to the leaf key data in the input certsData
    CTBAAIdentity *identity);                               // Output from identity field in leaf certificate

CT_int CTEvaluateBAAAccessory(
    const CT_uint8_t *certsData, CT_size_t certsLen,        // Input: binary representation of 2-4 concatenated
                                                            //        DER-encoded certs, with leaf first
    const CT_uint8_t *rootKeyData, CT_size_t rootKeyLen,    // Input: Root public key, if not specified
                                                            //        production root will be used
    const CT_uint8_t **leafKeyData, CT_size_t *leafKeyLen,  // Output: points to the leaf key data in the input certsData
    const CT_uint8_t **propertiesData, CT_size_t *propertiesLen); // Output: points to the Apple Accessory Properties extension value

CT_int CTEvaluateSatori(
    const CT_uint8_t *certsData, CT_size_t certsLen,           // Input: binary (DER) representation of 3 concatenated certs
                                                               //        with leaf first
    CT_bool allowTestRoot,                                     // Input: whether to allow the Test Apple Roots
    const CT_uint8_t **leafKeyData, CT_size_t *leafKeyLen);    // Output: points to the leaf key data in the input certsData

CT_int CTEvaluatePragueSignatureCMS(
    const CT_uint8_t *cmsData, CT_size_t cmsLen,                 // Input: CMS signature blob
    const CT_uint8_t *detachedData, CT_size_t detachedDataLen,   // Input: data signed by CMS blob
    CT_bool allowTestRoot,                                       // Input: permit use of test hierarchy
    const CT_uint8_t **leafKeyData, CT_size_t *leafKeyLen);      // Output: points to leaf key data in input cmsData

CT_int CTEvaluateKDLSignatureCMS(
    const CT_uint8_t *cmsData, CT_size_t cmsLen,                    // Input: CMS signature blob
    const CT_uint8_t *detachedData, CT_size_t detachedDataLen,      // Input: data signed by CMS blob
    CT_bool allowTestRoot,                                          // Input: permit use of test hierarchy
    const CT_uint8_t **leafKeyData, CT_size_t *leafKeyLen);         // Output: points to leaf key data in input cmsData

typedef CT_uint64_t CoreTrustPolicyFlags;
enum {
    CORETRUST_POLICY_BASIC =                0,
    CORETRUST_POLICY_SAVAGE_DEV =           1 << 0,
    CORETRUST_POLICY_SAVAGE_PROD =          1 << 1,
    CORETRUST_POLICY_MFI_AUTHV3 =           1 << 2,
    CORETRUST_POLICY_MAC_PLATFORM =         1 << 3,
    CORETRUST_POLICY_MAC_DEVELOPER =        1 << 4,
    CORETRUST_POLICY_DEVELOPER_ID =         1 << 5,
    CORETRUST_POLICY_MAC_APP_STORE =        1 << 6,
    CORETRUST_POLICY_IPHONE_DEVELOPER =     1 << 7,
    CORETRUST_POLICY_IPHONE_APP_PROD =      1 << 8,
    CORETRUST_POLICY_IPHONE_APP_DEV =       1 << 9,
    CORETRUST_POLICY_IPHONE_VPN_PROD =      1 << 10,
    CORETRUST_POLICY_IPHONE_VPN_DEV =       1 << 11,
    CORETRUST_POLICY_TVOS_APP_PROD =        1 << 12,
    CORETRUST_POLICY_TVOS_APP_DEV =         1 << 13,
    CORETRUST_POLICY_TEST_FLIGHT_PROD =     1 << 14,
    CORETRUST_POLICY_TEST_FLIGHT_DEV =      1 << 15,
    CORETRUST_POLICY_IPHONE_DISTRIBUTION =  1 << 16,
    CORETRUST_POLICY_MAC_SUBMISSION =       1 << 17,
    CORETRUST_POLICY_YONKERS_DEV =          1 << 18,
    CORETRUST_POLICY_YONKERS_PROD =         1 << 19,
    CORETRUST_POLICY_MAC_PLATFORM_G2 =      1 << 20,
    CORETRUST_POLICY_ACRT =                 1 << 21,
    CORETRUST_POLICY_SATORI =               1 << 22,
    CORETRUST_POLICY_BAA =                  1 << 23,
    CORETRUST_POLICY_UCRT =                 1 << 24,
    CORETRUST_POLICY_PRAGUE =               1 << 25,
    CORETRUST_POLICY_KDL =                  1 << 26,
    CORETRUST_POLICY_MFI_AUTHV2 =           1 << 27,
    CORETRUST_POLICY_MFI_SW_AUTH_PROD =     1 << 28,
    CORETRUST_POLICY_MFI_SW_AUTH_DEV =      1 << 29,
    CORETRUST_POLICY_COMPONENT =            1 << 30,
    CORETRUST_POLICY_IMG4 =                 1ULL << 31,
    CORETRUST_POLICY_SERVER_AUTH =          1ULL << 32,
    CORETRUST_POLICY_SERVER_AUTH_STRING =   1ULL << 33,
    CORETRUST_POLICY_MFI_AUTHV4_ACCESSORY = 1ULL << 34,
    CORETRUST_POLICY_MFI_AUTHV4_ATTESTATION = 1ULL << 35,
    CORETRUST_POLICY_MFI_AUTHV4_PROVISIONING = 1ULL << 36,
    CORETRUST_POLICY_WWDR_CLOUD_MANAGED =   1ULL << 37,
    CORETRUST_POLICY_HAVEN =                1ULL << 38,
    CORETRUST_POLICY_PROVISIONING_PROFILE = 1ULL << 39,
};

typedef CT_uint32_t CoreTrustDigestType;
enum {
    CORETRUST_DIGEST_TYPE_SHA1 = 1,
    CORETRUST_DIGEST_TYPE_SHA224 = 2,
    CORETRUST_DIGEST_TYPE_SHA256 = 4,
    CORETRUST_DIGEST_TYPE_SHA384 = 8,
    CORETRUST_DIGEST_TYPE_SHA512 = 16
};

CT_int CTEvaluateAMFICodeSignatureCMS(
    const CT_uint8_t *cmsData, CT_size_t cmsLen,               // Input: CMS blob
    const CT_uint8_t *detachedData, CT_size_t detachedDataLen, // Input: data signed by CMS blob
    CT_bool allow_test_hierarchy,                              // Input: permit use of test hierarchy
    const CT_uint8_t **leafCert, CT_size_t *leafCertLen,       // Output: signing certificate
    CoreTrustPolicyFlags *policyFlags,                         // Output: policy met by signing certificate
    CoreTrustDigestType *cmsDigestType,                        // Output: digest used to sign the CMS blob
    CoreTrustDigestType *hashAgilityDigestType,                // Output: highest strength digest type
                                                               //          from hash agility attribute
    const CT_uint8_t **digestData, CT_size_t *digestLen);      // Output: pointer to hash agility value
                                                               //          in CMS blob (with digest type above)

/* Returns non-zero if there's a standards-based problem with the CMS or certificates.
 * Policy matching of the certificates is only reflected in the policyFlags output. Namely, if the only problem is that
 * the certificates don't match a policy, the returned integer will be 0 (success) and the policyFlags will be 0 (no matching policies).
 * Some notes about hash agility outputs:
 *  - hashAgilityDigestType is only non-zero for HashAgilityV2
 *  - If hashAgilityDigestType is non-zero, digestData/Len provides the digest value
 *  - If hashAgilityDigestType is zero, digestData/Len provides the content of the HashAgilityV1 attribute (if present)
 *  - If neither HashAgilityV1 nor HashAgilityV2 attributes are found, these outputs will all be NULL.
 */

int CTEvaluateAMFICodeSignatureCMSPubKey(
    const CT_uint8_t *cmsData, CT_size_t cmsLen,                        // Input: CMS blob
    const CT_uint8_t *detachedData, CT_size_t detachedDataLen,          // Input: data signed by CMS blob
    const CT_uint8_t *anchorPublicKey, CT_size_t anchorPublicKeyLen,    // Input: anchor public key for self-signed cert
    CoreTrustDigestType *cmsDigestType,                                 // Output: digest used to sign the CMS blob
    CoreTrustDigestType *hashAgilityDigestType,                         // Output: highest strength digest type
                                                                        //          from hash agility attribute
    const CT_uint8_t **digestData, CT_size_t *digestLen);               // Output: pointer to hash agility value
                                                                        //          in CMS blob (with digest type above)

CT_int CTParseAccessoryCerts(
    const CT_uint8_t *certsData, CT_size_t certsLen,            // Input: CMS or binary representation of DER-encoded certs
    const CT_uint8_t **leafCertData, CT_size_t *leafCertLen,    // Output: points to leaf cert data in input certsData
    const CT_uint8_t **subCACertData, CT_size_t *subCACertLen,  // Output: points to subCA cert(s) data in input
                                                                //  certsData, if present. Is set to NULL if only
                                                                //  one cert present in input.
    CoreTrustPolicyFlags *flags);                               // Output: policy flags set by this leaf


CT_int CTEvaluateAccessoryCert(
    const CT_uint8_t *leafCertData, CT_size_t leafCertLen,        // Input: binary representation of DER-encoded leaf cert
    const CT_uint8_t *subCACertData, CT_size_t subCACertLen,      // Input: (optional) binary representation of DER-encoded subCA cert(s)
    const CT_uint8_t *anchorCertData, CT_size_t anchorCertLen,    // Input: binary representation of DER-encoded anchor cert
    CoreTrustPolicyFlags policy,                                  // Input: policy to use when evaluating chain
    const CT_uint8_t **leafKeyData, CT_size_t *leafKeyLen,        // Output: points to the leaf key data in the input leafCertData
    const CT_uint8_t **extensionValueData, CT_size_t *extensionValueLen); // Output: points to the extension value in the input leafCertData

/* Which extension value is returned is based on which policy the cert was verified against:
 *  - For MFI AuthV3, this is the value of the extension with OID 1.2.840.113635.100.6.36
 *  - For SW Auth, this is the value of the extension with OID 1.2.840.113635.100.6.59.1 (GeneralCapabilities extension)
 *  - For Component certs, this si the value of the extension with OID 1.2.840.113635.100.11.1 (Component Type)
 *  - For MFi AuthV4, this is the value of the extension with OID 1.2.840.113635.100.6.71.1 (Apple Accessory Properties extension)
 *
 * The following CoreTrustPolicyFlags are accepted:
 *  - CORETRUST_POLICY_BASIC
 *  - CORETRUST_POLICY_MFI_AUTHV2
 *  - CORETRUST_POLICY_MFI_AUTHV3
 *  - CORETRUST_POLICY_MFI_SW_AUTH_DEV
 *  - CORETRUST_POLICY_MFI_SW_AUTH_PROD
 *  - CORETRUST_POLICY_COMPONENT
 *  - CORETRUST_POLICY_MFI_AUTHV4_ACCESSORY
 *  - CORETRUST_POLICY_MFI_AUTHV4_ATTESTATION
 *  - CORETRUST_POLICY_MFI_AUTHV4_PROVISIONING
 */

CT_int CTEvaluateAppleSSL(
    const CT_uint8_t *certsData, CT_size_t certsLen,        // Input: binary representation of up to 3 concatenated
                                                            //        DER-encoded certificates, with leaf first
    const CT_uint8_t *hostnameData, CT_size_t hostnameLen,  // Input: The hostname of the TLS server being connected to
    CT_uint64_t leafMarker,                                 // Input: The last decimal of the marker OID for this project
                                                            //        (e.g. 32 for 1.2.840.113635.100.6.27.32
    CT_bool allowTestRoots);                                // Input: permit use of test hierarchy

CT_int CTEvaluateAppleSSLWithOptionalTemporalCheck(
    const CT_uint8_t *certsData, CT_size_t certsLen,
    const CT_uint8_t *hostnameData, CT_size_t hostnameLen,
    CT_uint64_t leafMarker,
    CT_bool allowTestRoots,
    CT_bool checkTemporalValidity);

int CTEvaluateProvisioningProfile(
    const CT_uint8_t *provisioningProfileData, CT_size_t provisioningProfileLen,
    CT_bool allowTestRoots,
    const CT_uint8_t **contentData, CT_size_t *contentLen);

__END_DECLS

#endif /* _CORETRUST_EVALUATE_H_ */