EXTERNAL_HEADERS/coretrust/CTEvaluate.h

   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 <stdint.h>
  12 #include <stdbool.h>
  13
  14 __BEGIN_DECLS
  15
  16 typedef struct x509_octet_string {
  17     const uint8_t *data;
  18     size_t length;
  19 } CTAsn1Item;
  20
  21 int CTParseCertificateSet(const uint8_t *der, const uint8_t *der_end,       // Input: binary representation of concatenated DER-encoded certs
  22                           CTAsn1Item *certStorage, size_t certStorageLen,   // Output: An array of certStorageLen CTAsn1Items that will be populated with the
  23                                                                             //    CTAsn1Item for each parsed cert (in the same order as input)
  24                           size_t *numParsedCerts);                          // Output: number of successfully parsed certs
  25
  26 int CTEvaluateSavageCerts(const uint8_t *certsData, size_t certsLen,
  27                           const uint8_t *rootKeyData, size_t rootKeyLen,
  28                           const uint8_t **leafKeyData, size_t *leafKeyLen,
  29                           bool *isProdCert);
  30
  31 int CTEvaluateSavageCertsWithUID(const uint8_t *certsData, size_t certsLen,
  32                                  const uint8_t *rootKeyData, size_t rootKeyLen,
  33                                  const uint8_t **leafKeyData, size_t *leafKeyLen, // Output: points to the leaf key data in the input certsData
  34                                  uint8_t *UIDData, size_t UIDLen,                 // Output: a pre-allocated buffer of UIDLen
  35                                  bool *isProdCert);
  36
  37 int CTEvaluateYonkersCerts(const uint8_t *certsData, size_t certsLen,
  38                            const uint8_t *rootKeyData, size_t rootKeyLen,
  39                            const uint8_t **leafKeyData, size_t *leafKeyLen, // Output: points to the leaf key data in the input certsData
  40                            uint8_t *UIDData, size_t UIDLen,                 // Output: a pre-allocated buffer of UIDLen
  41                            bool *isProdCert);
  42
  43 int CTEvaluateAcrt(const uint8_t *certsData, size_t certsLen,         // Input: binary representation of at most 3 concatenated certs
  44                                                                       //         with leaf first (root may be omitted)
  45                    const uint8_t **leafKeyData, size_t *leafKeyLen);  // Output: points to the leaf key data in the input certsData
  46
  47 int CTEvaluateUcrt(const uint8_t *certsData, size_t certsLen,         // Input: binary representation of exactly 3 concatenated
  48                                                                       //        DER-encoded certs, with leaf first
  49                    const uint8_t **leafKeyData, size_t *leafKeyLen);  // Output: points to the leaf key data in the input certsData)
  50
  51 int CTEvaluateUcrtTestRoot(const uint8_t *certsData, size_t certsLen,         // Input: binary representation of exactly 3 concatenated
  52                                                                               //        DER-encoded certs, with leaf first
  53                            const uint8_t *rootKeyData, size_t rootKeyLen,     // Input: Root public key, if not specified production root will be used
  54                            const uint8_t **leafKeyData, size_t *leafKeyLen);  // Output: points to the leaf key data in the input certsData)
  55
  56 int CTEvaluateBAASystem(const uint8_t *certsData, size_t certsLen,         // Input: binary representation of exactly 3 concatenated
  57                                                                            //        DER-encoded certs, with leaf first
  58                         const uint8_t **leafKeyData, size_t *leafKeyLen);  // Output: points to the leaf key data in the input certsData
  59
  60 typedef struct baa_identity {
  61     uint32_t chipId;
  62     uint64_t ecid;
  63     bool productionStatus;
  64     bool securityMode;
  65     uint8_t securityDomain;
  66     CTAsn1Item img4;
  67 } CTBAAIdentity;
  68
  69 int CTEvaluateBAASystemWithId(const uint8_t *certsData, size_t certsLen,        // Input: binary representation of exactly 3 concatenated
  70                                                                                 //        DER-encoded certs, with leaf first
  71                               const uint8_t **leafKeyData, size_t *leafKeyLen,  // Output: points to the leaf key data in the input certsData
  72                               CTBAAIdentity *identity);                         // Output from identity field in leaf certificate
  73
  74 int CTEvaluateBAASystemTestRoot(const uint8_t *certsData, size_t certsLen,      // Input: binary representation of exactly 3 concatenated
  75                                                                                 //        DER-encoded certs, with leaf first
  76                                 const uint8_t *rootKeyData, size_t rootKeyLen,  // Input: Root public key, if not specified production root will be used
  77                                 const uint8_t **leafKeyData, size_t *leafKeyLen,// Output: points to the leaf key data in the input certsData
  78                                 CTBAAIdentity *identity);                       // Output from identity field in leaf certificate
  79
  80 int CTEvaluateBAAUser(const uint8_t *certsData, size_t certsLen,        // Input: binary representation of exactly 3 concatenated
  81                                                                         //        DER-encoded certs, with leaf first
  82                       const uint8_t **leafKeyData, size_t *leafKeyLen,  // Output: points to the leaf key data in the input certsData
  83                       CTBAAIdentity *identity);                         // Output from identity field in leaf certificate
  84
  85 int CTEvaluateBAAUserTestRoot(const uint8_t *certsData, size_t certsLen,        // Input: binary representation of exactly 3 concatenated
  86                                                                                 //        DER-encoded certs, with leaf first
  87                               const uint8_t *rootKeyData, size_t rootKeyLen,    // Input: Root public key, if not specified production root will be used
  88                               const uint8_t **leafKeyData, size_t *leafKeyLen,  // Output: points to the leaf key data in the input certsData
  89                               CTBAAIdentity *identity);                         // Output from identity field in leaf certificate
  90
  91 int CTEvaluateSatori(const uint8_t *certsData, size_t certsLen,         // Input: binary (DER) representation of 3 concatenated certs
  92                                                                         //        with leaf first
  93                      bool allowTestRoot,                                // Input: whether to allow the Test Apple Roots
  94                      const uint8_t **leafKeyData, size_t *leafKeyLen);  // Output: points to the leaf key data in the input certsData
  95
  96 int CTEvaluatePragueSignatureCMS(const uint8_t *cmsData, size_t cmsLen,                 // Input: CMS signature blob
  97                                  const uint8_t *detachedData, size_t detachedDataLen,   // Input: data signed by CMS blob
  98                                  bool allowTestRoot,                                    // Input: permit use of test hierarchy
  99                                  const uint8_t **leafKeyData, size_t *leafKeyLen);      // Output: points to leaf key data in input cmsData
 100
 101 int CTEvaluateKDLSignatureCMS(const uint8_t *cmsData, size_t cmsLen,                    // Input: CMS signature blob
 102                               const uint8_t *detachedData, size_t detachedDataLen,      // Input: data signed by CMS blob
 103                               bool allowTestRoot,                                       // Input: permit use of test hierarchy
 104                               const uint8_t **leafKeyData, size_t *leafKeyLen);         // Output: points to leaf key data in input cmsData
 105
 106 typedef uint64_t CoreTrustPolicyFlags;
 107 enum {
 108     CORETRUST_POLICY_BASIC =                0,
 109     CORETRUST_POLICY_SAVAGE_DEV =           1 << 0,
 110     CORETRUST_POLICY_SAVAGE_PROD =          1 << 1,
 111     CORETRUST_POLICY_MFI_AUTHV3 =           1 << 2,
 112     CORETRUST_POLICY_MAC_PLATFORM =         1 << 3,
 113     CORETRUST_POLICY_MAC_DEVELOPER =        1 << 4,
 114     CORETRUST_POLICY_DEVELOPER_ID =         1 << 5,
 115     CORETRUST_POLICY_MAC_APP_STORE =        1 << 6,
 116     CORETRUST_POLICY_IPHONE_DEVELOPER =     1 << 7,
 117     CORETRUST_POLICY_IPHONE_APP_PROD =      1 << 8,
 118     CORETRUST_POLICY_IPHONE_APP_DEV =       1 << 9,
 119     CORETRUST_POLICY_IPHONE_VPN_PROD =      1 << 10,
 120     CORETRUST_POLICY_IPHONE_VPN_DEV =       1 << 11,
 121     CORETRUST_POLICY_TVOS_APP_PROD =        1 << 12,
 122     CORETRUST_POLICY_TVOS_APP_DEV =         1 << 13,
 123     CORETRUST_POLICY_TEST_FLIGHT_PROD =     1 << 14,
 124     CORETRUST_POLICY_TEST_FLIGHT_DEV =      1 << 15,
 125     CORETRUST_POLICY_IPHONE_DISTRIBUTION =  1 << 16,
 126     CORETRUST_POLICY_MAC_SUBMISSION =       1 << 17,
 127     CORETRUST_POLICY_YONKERS_DEV =          1 << 18,
 128     CORETRUST_POLICY_YONKERS_PROD =         1 << 19,
 129     CORETRUST_POLICY_MAC_PLATFORM_G2 =      1 << 20,
 130     CORETRUST_POLICY_ACRT =                 1 << 21,
 131     CORETRUST_POLICY_SATORI =               1 << 22,
 132     CORETRUST_POLICY_BAA =                  1 << 23,
 133     CORETRUST_POLICY_UCRT =                 1 << 24,
 134     CORETRUST_POLICY_PRAGUE =               1 << 25,
 135     CORETRUST_POLICY_KDL =                  1 << 26,
 136     CORETRUST_POLICY_MFI_AUTHV2 =           1 << 27,
 137     CORETRUST_POLICY_MFI_SW_AUTH_PROD =     1 << 28,
 138     CORETRUST_POLICY_MFI_SW_AUTH_DEV =      1 << 29,
 139     CORETRUST_POLICY_COMPONENT =            1 << 30,
 140     CORETRUST_POLICY_IMG4 =                 1ULL << 31,
 141     CORETRUST_POLICY_SERVER_AUTH =          1ULL << 32,
 142     CORETRUST_POLICY_SERVER_AUTH_STRING =   1ULL << 33,
 143 };
 144
 145 typedef uint32_t CoreTrustDigestType;
 146 enum {
 147     CORETRUST_DIGEST_TYPE_SHA1 = 1,
 148     CORETRUST_DIGEST_TYPE_SHA224 = 2,
 149     CORETRUST_DIGEST_TYPE_SHA256 = 4,
 150     CORETRUST_DIGEST_TYPE_SHA384 = 8,
 151     CORETRUST_DIGEST_TYPE_SHA512 = 16
 152 };
 153
 154 int CTEvaluateAMFICodeSignatureCMS(const uint8_t *cmsData, size_t cmsLen,                   // Input: CMS blob
 155                                    const uint8_t *detachedData, size_t detachedDataLen,     // Input: data signed by CMS blob
 156                                    bool allow_test_hierarchy,                               // Input: permit use of test hierarchy
 157                                    const uint8_t **leafCert, size_t *leafCertLen,           // Output: signing certificate
 158                                    CoreTrustPolicyFlags *policyFlags,                       // Output: policy met by signing certificate
 159                                    CoreTrustDigestType *cmsDigestType,                      // Output: digest used to sign the CMS blob
 160                                    CoreTrustDigestType *hashAgilityDigestType,              // Output: highest stregth digest type
 161                                                                                             //          from hash agility attribute
 162                                    const uint8_t **digestData, size_t *digestLen);          // Output: pointer to hash agility value
 163                                                                                             //          in CMS blob (with digest type above)
 164 /* Returns non-zero if there's a standards-based problem with the CMS or certificates.
 165  * Policy matching of the certificates is only reflected in the policyFlags output. Namely, if the only problem is that
 166  * the certificates don't match a policy, the returned integer will be 0 (success) and the policyFlags will be 0 (no matching policies).
 167  * Some notes about hash agility outputs:
 168  *  - hashAgilityDigestType is only non-zero for HashAgilityV2
 169  *  - If hashAgilityDigestType is non-zero, digestData/Len provides the digest value
 170  *  - If hashAgilityDigestType is zero, digestData/Len provides the content of the HashAgilityV1 attribute (if present)
 171  *  - If neither HashAgilityV1 nor HashAgilityV2 attributes are found, these outputs will all be NULL.
 172  */
 173
 174 int CTParseAccessoryCerts(const uint8_t *certsData, size_t certsLen,                    // Input: CMS or binary representation of DER-encoded certs
 175                                   const uint8_t **leafCertData, size_t *leafCertLen,    // Output: points to leaf cert data in input certsData
 176                                   const uint8_t **subCACertData, size_t *subCACertLen,  // Output: points to subCA cert data (1st of 2) in input certsData, if present. Is set to NULL if only one cert present in input.
 177                                   CoreTrustPolicyFlags *flags);                         // Output: policy flags set by this leaf
 178
 179
 180 int CTEvaluateAccessoryCert(const uint8_t *leafCertData, size_t leafCertLen,            // Input: binary representation of DER-encoded leaf cert
 181                             const uint8_t *subCACertData, size_t subCACertLen,          // Input: (optional) binary representation of DER-encoded subCA cert
 182                             const uint8_t *anchorCertData, size_t anchorCertLen,        // Input: binary representation of DER-encoded anchor cert
 183                             CoreTrustPolicyFlags policy,                                // Input: policy to use when evaluating chain
 184                             const uint8_t **leafKeyData, size_t *leafKeyLen,            // Output: points to the leaf key data in the input leafCertData
 185                             const uint8_t **extensionValueData, size_t *extensionValueLen); // Output: points to the extension value in the input leafCertData
 186 /* Which extension value is returned is based on which policy the cert was verified against:
 187  *  - For MFI AuthV3, this is the value of the extension with OID 1.2.840.113635.100.6.36
 188  *  - For SW Auth, this is the value of the extension with OID 1.2.840.113635.100.6.59.1 (GeneralCapabilities extension)
 189  *  - For Component certs, this si the value of the extension with OID 1.2.840.113635.100.11.1 (Component Type)
 190  *
 191  * The following CoreTrustPolicyFlags are accepted:
 192  *  - CORETRUST_POLICY_BASIC
 193  *  - CORETRUST_POLICY_MFI_AUTHV2
 194  *  - CORETRUST_POLICY_MFI_AUTHV3
 195  *  - CORETRUST_POLICY_MFI_SW_AUTH_DEV
 196  *  - CORETRUST_POLICY_MFI_SW_AUTH_PROD
 197  *  - CORETRUST_POLICY_COMPONENT
 198  */
 199
 200 int CTEvaluateAppleSSL(const uint8_t *certsData, size_t certsLen,           // Input: binary representation of up to 3 concatenated
 201                                                                             //        DER-encoded certificates, with leaf first
 202                        const uint8_t *hostnameData, size_t hostnameLen,     // Input: The hostname of the TLS server being connected to
 203                        uint64_t leafMarker,                                 // Input: The last decimal of the marker OID for this project
 204                                                                             //        (e.g. 32 for 1.2.840.113635.100.6.27.32
 205                        bool allowTestRoots);                                // Input: permit use of test hierarchy
 206
 207 int CTEvaluateAppleSSLWithOptionalTemporalCheck(const uint8_t *certsData, size_t certsLen,
 208                                                  const uint8_t *hostnameData, size_t hostnameLen,
 209                                                  uint64_t leafMarker,
 210                                                  bool allowTestRoots,
 211                                                  bool checkTemporalValidity);
 212
 213 __END_DECLS
 214
 215 #endif /* _CORETRUST_EVALUATE_H_ */