1 /* 2 * Copyright 2016 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef SYSTEM_KEYMASTER_ATTESTATION_RECORD_H_ 18 #define SYSTEM_KEYMASTER_ATTESTATION_RECORD_H_ 19 20 #include <hardware/keymaster_defs.h> 21 22 #include <keymaster/authorization_set.h> 23 24 #include <openssl/asn1t.h> 25 26 namespace keymaster { 27 28 constexpr uint kCurrentKeymasterVersion = 41; 29 30 struct stack_st_ASN1_TYPE_Delete { operatorstack_st_ASN1_TYPE_Delete31 void operator()(stack_st_ASN1_TYPE* p) { sk_ASN1_TYPE_free(p); } 32 }; 33 34 struct ASN1_STRING_Delete { operatorASN1_STRING_Delete35 void operator()(ASN1_STRING* p) { ASN1_STRING_free(p); } 36 }; 37 38 struct ASN1_TYPE_Delete { operatorASN1_TYPE_Delete39 void operator()(ASN1_TYPE* p) { ASN1_TYPE_free(p); } 40 }; 41 42 #define ASN1_INTEGER_SET STACK_OF(ASN1_INTEGER) 43 44 typedef struct km_root_of_trust { 45 ASN1_OCTET_STRING* verified_boot_key; 46 ASN1_BOOLEAN device_locked; 47 ASN1_ENUMERATED* verified_boot_state; 48 ASN1_OCTET_STRING* verified_boot_hash; 49 } KM_ROOT_OF_TRUST; 50 51 ASN1_SEQUENCE(KM_ROOT_OF_TRUST) = { 52 ASN1_SIMPLE(KM_ROOT_OF_TRUST, verified_boot_key, ASN1_OCTET_STRING), 53 ASN1_SIMPLE(KM_ROOT_OF_TRUST, device_locked, ASN1_BOOLEAN), 54 ASN1_SIMPLE(KM_ROOT_OF_TRUST, verified_boot_state, ASN1_ENUMERATED), 55 ASN1_SIMPLE(KM_ROOT_OF_TRUST, verified_boot_hash, ASN1_OCTET_STRING), 56 } ASN1_SEQUENCE_END(KM_ROOT_OF_TRUST); 57 DECLARE_ASN1_FUNCTIONS(KM_ROOT_OF_TRUST); 58 59 typedef struct km_auth_list { 60 ASN1_INTEGER_SET* purpose; 61 ASN1_INTEGER* algorithm; 62 ASN1_INTEGER* key_size; 63 ASN1_INTEGER_SET* block_mode; 64 ASN1_INTEGER_SET* digest; 65 ASN1_INTEGER_SET* padding; 66 ASN1_NULL* caller_nonce; 67 ASN1_INTEGER* min_mac_length; 68 ASN1_INTEGER_SET* kdf; 69 ASN1_INTEGER* ec_curve; 70 ASN1_INTEGER* rsa_public_exponent; 71 ASN1_INTEGER* active_date_time; 72 ASN1_INTEGER* origination_expire_date_time; 73 ASN1_INTEGER* usage_expire_date_time; 74 ASN1_NULL* no_auth_required; 75 ASN1_INTEGER* user_auth_type; 76 ASN1_INTEGER* auth_timeout; 77 ASN1_NULL* allow_while_on_body; 78 ASN1_NULL* trusted_confirmation_required; 79 ASN1_NULL* unlocked_device_required; 80 ASN1_NULL* all_applications; 81 ASN1_OCTET_STRING* application_id; 82 ASN1_INTEGER* creation_date_time; 83 ASN1_INTEGER* origin; 84 ASN1_NULL* rollback_resistance; 85 ASN1_NULL* rollback_resistant; 86 KM_ROOT_OF_TRUST* root_of_trust; 87 ASN1_INTEGER* os_version; 88 ASN1_INTEGER* os_patchlevel; 89 ASN1_OCTET_STRING* attestation_application_id; 90 ASN1_OCTET_STRING* attestation_id_brand; 91 ASN1_OCTET_STRING* attestation_id_device; 92 ASN1_OCTET_STRING* attestation_id_product; 93 ASN1_OCTET_STRING* attestation_id_serial; 94 ASN1_OCTET_STRING* attestation_id_imei; 95 ASN1_OCTET_STRING* attestation_id_meid; 96 ASN1_OCTET_STRING* attestation_id_manufacturer; 97 ASN1_OCTET_STRING* attestation_id_model; 98 ASN1_NULL* early_boot_only; 99 ASN1_NULL* device_unique_attestation; 100 ASN1_NULL* identity_credential_key; 101 } KM_AUTH_LIST; 102 103 ASN1_SEQUENCE(KM_AUTH_LIST) = { 104 ASN1_EXP_SET_OF_OPT(KM_AUTH_LIST, purpose, ASN1_INTEGER, TAG_PURPOSE.masked_tag()), 105 ASN1_EXP_OPT(KM_AUTH_LIST, algorithm, ASN1_INTEGER, TAG_ALGORITHM.masked_tag()), 106 ASN1_EXP_OPT(KM_AUTH_LIST, key_size, ASN1_INTEGER, TAG_KEY_SIZE.masked_tag()), 107 ASN1_EXP_SET_OF_OPT(KM_AUTH_LIST, block_mode, ASN1_INTEGER, TAG_BLOCK_MODE.masked_tag()), 108 ASN1_EXP_SET_OF_OPT(KM_AUTH_LIST, digest, ASN1_INTEGER, TAG_DIGEST.masked_tag()), 109 ASN1_EXP_SET_OF_OPT(KM_AUTH_LIST, padding, ASN1_INTEGER, TAG_PADDING.masked_tag()), 110 ASN1_EXP_OPT(KM_AUTH_LIST, caller_nonce, ASN1_NULL, TAG_CALLER_NONCE.masked_tag()), 111 ASN1_EXP_OPT(KM_AUTH_LIST, min_mac_length, ASN1_INTEGER, TAG_MIN_MAC_LENGTH.masked_tag()), 112 ASN1_EXP_SET_OF_OPT(KM_AUTH_LIST, kdf, ASN1_INTEGER, TAG_KDF.masked_tag()), 113 ASN1_EXP_OPT(KM_AUTH_LIST, ec_curve, ASN1_INTEGER, TAG_EC_CURVE.masked_tag()), 114 ASN1_EXP_OPT(KM_AUTH_LIST, rsa_public_exponent, ASN1_INTEGER, 115 TAG_RSA_PUBLIC_EXPONENT.masked_tag()), 116 ASN1_EXP_OPT(KM_AUTH_LIST, active_date_time, ASN1_INTEGER, TAG_ACTIVE_DATETIME.masked_tag()), 117 ASN1_EXP_OPT(KM_AUTH_LIST, origination_expire_date_time, ASN1_INTEGER, 118 TAG_ORIGINATION_EXPIRE_DATETIME.masked_tag()), 119 ASN1_EXP_OPT(KM_AUTH_LIST, usage_expire_date_time, ASN1_INTEGER, 120 TAG_USAGE_EXPIRE_DATETIME.masked_tag()), 121 ASN1_EXP_OPT(KM_AUTH_LIST, no_auth_required, ASN1_NULL, TAG_NO_AUTH_REQUIRED.masked_tag()), 122 ASN1_EXP_OPT(KM_AUTH_LIST, user_auth_type, ASN1_INTEGER, TAG_USER_AUTH_TYPE.masked_tag()), 123 ASN1_EXP_OPT(KM_AUTH_LIST, auth_timeout, ASN1_INTEGER, TAG_AUTH_TIMEOUT.masked_tag()), 124 ASN1_EXP_OPT(KM_AUTH_LIST, allow_while_on_body, ASN1_NULL, 125 TAG_ALLOW_WHILE_ON_BODY.masked_tag()), 126 ASN1_EXP_OPT(KM_AUTH_LIST, unlocked_device_required, ASN1_NULL, 127 TAG_UNLOCKED_DEVICE_REQUIRED.masked_tag()), 128 ASN1_EXP_OPT(KM_AUTH_LIST, all_applications, ASN1_NULL, TAG_ALL_APPLICATIONS.masked_tag()), 129 ASN1_EXP_OPT(KM_AUTH_LIST, application_id, ASN1_OCTET_STRING, TAG_APPLICATION_ID.masked_tag()), 130 ASN1_EXP_OPT(KM_AUTH_LIST, creation_date_time, ASN1_INTEGER, 131 TAG_CREATION_DATETIME.masked_tag()), 132 ASN1_EXP_OPT(KM_AUTH_LIST, origin, ASN1_INTEGER, TAG_ORIGIN.masked_tag()), 133 ASN1_EXP_OPT(KM_AUTH_LIST, rollback_resistance, ASN1_NULL, 134 TAG_ROLLBACK_RESISTANCE.masked_tag()), 135 ASN1_EXP_OPT(KM_AUTH_LIST, rollback_resistant, ASN1_NULL, TAG_ROLLBACK_RESISTANT.masked_tag()), 136 ASN1_EXP_OPT(KM_AUTH_LIST, root_of_trust, KM_ROOT_OF_TRUST, TAG_ROOT_OF_TRUST.masked_tag()), 137 ASN1_EXP_OPT(KM_AUTH_LIST, os_version, ASN1_INTEGER, TAG_OS_VERSION.masked_tag()), 138 ASN1_EXP_OPT(KM_AUTH_LIST, os_patchlevel, ASN1_INTEGER, TAG_OS_PATCHLEVEL.masked_tag()), 139 ASN1_EXP_OPT(KM_AUTH_LIST, attestation_application_id, ASN1_OCTET_STRING, 140 TAG_ATTESTATION_APPLICATION_ID.masked_tag()), 141 ASN1_EXP_OPT(KM_AUTH_LIST, attestation_id_brand, ASN1_OCTET_STRING, 142 TAG_ATTESTATION_ID_BRAND.masked_tag()), 143 ASN1_EXP_OPT(KM_AUTH_LIST, attestation_id_device, ASN1_OCTET_STRING, 144 TAG_ATTESTATION_ID_DEVICE.masked_tag()), 145 ASN1_EXP_OPT(KM_AUTH_LIST, attestation_id_product, ASN1_OCTET_STRING, 146 TAG_ATTESTATION_ID_PRODUCT.masked_tag()), 147 ASN1_EXP_OPT(KM_AUTH_LIST, attestation_id_serial, ASN1_OCTET_STRING, 148 TAG_ATTESTATION_ID_SERIAL.masked_tag()), 149 ASN1_EXP_OPT(KM_AUTH_LIST, attestation_id_imei, ASN1_OCTET_STRING, 150 TAG_ATTESTATION_ID_IMEI.masked_tag()), 151 ASN1_EXP_OPT(KM_AUTH_LIST, attestation_id_meid, ASN1_OCTET_STRING, 152 TAG_ATTESTATION_ID_MEID.masked_tag()), 153 ASN1_EXP_OPT(KM_AUTH_LIST, attestation_id_manufacturer, ASN1_OCTET_STRING, 154 TAG_ATTESTATION_ID_MANUFACTURER.masked_tag()), 155 ASN1_EXP_OPT(KM_AUTH_LIST, attestation_id_model, ASN1_OCTET_STRING, 156 TAG_ATTESTATION_ID_MODEL.masked_tag()), 157 ASN1_EXP_OPT(KM_AUTH_LIST, early_boot_only, ASN1_NULL, TAG_EARLY_BOOT_ONLY.masked_tag()), 158 ASN1_EXP_OPT(KM_AUTH_LIST, device_unique_attestation, ASN1_NULL, 159 TAG_DEVICE_UNIQUE_ATTESTATION.masked_tag()), 160 ASN1_EXP_OPT(KM_AUTH_LIST, identity_credential_key, ASN1_NULL, 161 TAG_IDENTITY_CREDENTIAL_KEY.masked_tag()), 162 } ASN1_SEQUENCE_END(KM_AUTH_LIST); 163 DECLARE_ASN1_FUNCTIONS(KM_AUTH_LIST); 164 165 typedef struct km_key_description { 166 ASN1_INTEGER* attestation_version; 167 ASN1_ENUMERATED* attestation_security_level; 168 ASN1_INTEGER* keymaster_version; 169 ASN1_ENUMERATED* keymaster_security_level; 170 ASN1_OCTET_STRING* attestation_challenge; 171 KM_AUTH_LIST* software_enforced; 172 KM_AUTH_LIST* tee_enforced; 173 ASN1_INTEGER* unique_id; 174 } KM_KEY_DESCRIPTION; 175 176 ASN1_SEQUENCE(KM_KEY_DESCRIPTION) = { 177 ASN1_SIMPLE(KM_KEY_DESCRIPTION, attestation_version, ASN1_INTEGER), 178 ASN1_SIMPLE(KM_KEY_DESCRIPTION, attestation_security_level, ASN1_ENUMERATED), 179 ASN1_SIMPLE(KM_KEY_DESCRIPTION, keymaster_version, ASN1_INTEGER), 180 ASN1_SIMPLE(KM_KEY_DESCRIPTION, keymaster_security_level, ASN1_ENUMERATED), 181 ASN1_SIMPLE(KM_KEY_DESCRIPTION, attestation_challenge, ASN1_OCTET_STRING), 182 ASN1_SIMPLE(KM_KEY_DESCRIPTION, unique_id, ASN1_OCTET_STRING), 183 ASN1_SIMPLE(KM_KEY_DESCRIPTION, software_enforced, KM_AUTH_LIST), 184 ASN1_SIMPLE(KM_KEY_DESCRIPTION, tee_enforced, KM_AUTH_LIST), 185 } ASN1_SEQUENCE_END(KM_KEY_DESCRIPTION); 186 DECLARE_ASN1_FUNCTIONS(KM_KEY_DESCRIPTION); 187 188 class AttestationRecordContext { 189 protected: ~AttestationRecordContext()190 virtual ~AttestationRecordContext() {} 191 192 public: 193 /** 194 * Returns the security level (SW or TEE) of this keymaster implementation. 195 */ GetSecurityLevel()196 virtual keymaster_security_level_t GetSecurityLevel() const { 197 return KM_SECURITY_LEVEL_SOFTWARE; 198 } 199 200 /** 201 * Verify that the device IDs provided in the attestation_params match the device's actual IDs 202 * and copy them to attestation. If *any* of the IDs do not match or verification is not 203 * possible, return KM_ERROR_CANNOT_ATTEST_IDS. If *all* IDs provided are successfully verified 204 * or no IDs were provided, return KM_ERROR_OK. 205 * 206 * If you do not support device ID attestation, ignore all arguments and return 207 * KM_ERROR_UNIMPLEMENTED. 208 */ 209 virtual keymaster_error_t VerifyAndCopyDeviceIds(const AuthorizationSet &,AuthorizationSet *)210 VerifyAndCopyDeviceIds(const AuthorizationSet& /* attestation_params */, 211 AuthorizationSet* /* attestation */) const { 212 return KM_ERROR_UNIMPLEMENTED; 213 } 214 /** 215 * Generate the current unique ID. 216 */ GenerateUniqueId(uint64_t,const keymaster_blob_t &,bool,Buffer *)217 virtual keymaster_error_t GenerateUniqueId(uint64_t /*creation_date_time*/, 218 const keymaster_blob_t& /*application_id*/, 219 bool /*reset_since_rotation*/, 220 Buffer* /*unique_id*/) const { 221 return KM_ERROR_UNIMPLEMENTED; 222 } 223 224 /** 225 * Returns verified boot parameters for the Attestation Extension. For hardware-based 226 * implementations, these will be the values reported by the bootloader. By default, verified 227 * boot state is unknown, and KM_ERROR_UNIMPLEMENTED is returned. 228 */ 229 virtual keymaster_error_t GetVerifiedBootParams(keymaster_blob_t *,keymaster_blob_t *,keymaster_verified_boot_t *,bool *)230 GetVerifiedBootParams(keymaster_blob_t* /* verified_boot_key */, 231 keymaster_blob_t* /* verified_boot_hash */, 232 keymaster_verified_boot_t* /* verified_boot_state */, 233 bool* /* device_locked */) const { 234 return KM_ERROR_UNIMPLEMENTED; 235 } 236 }; 237 238 /** 239 * The OID for Android attestation records. For the curious, it breaks down as follows: 240 * 241 * 1 = ISO 242 * 3 = org 243 * 6 = DoD (Huh? OIDs are weird.) 244 * 1 = IANA 245 * 4 = Private 246 * 1 = Enterprises 247 * 11129 = Google 248 * 2 = Google security 249 * 1 = certificate extension 250 * 17 = Android attestation extension. 251 */ 252 static const char kAttestionRecordOid[] = "1.3.6.1.4.1.11129.2.1.17"; 253 254 // This build_attestation_record sets the keymaster version to the default 255 // value. 256 keymaster_error_t build_attestation_record(const AuthorizationSet& attestation_params, 257 AuthorizationSet software_enforced, 258 AuthorizationSet tee_enforced, 259 const AttestationRecordContext& context, 260 UniquePtr<uint8_t[]>* asn1_key_desc, 261 size_t* asn1_key_desc_len); 262 263 // Builds attestation record, same as above, except this allows the keymaster 264 // version to be set to different value than the default. 265 keymaster_error_t 266 build_attestation_record(const AuthorizationSet& attestation_params, AuthorizationSet sw_enforced, 267 AuthorizationSet tee_enforced, const AttestationRecordContext& context, 268 const uint keymaster_version, UniquePtr<uint8_t[]>* asn1_key_desc, 269 size_t* asn1_key_desc_len); 270 271 /** 272 * Helper functions for attestation record tests. Caller takes ownership of 273 * |attestation_challenge->data| and |unique_id->data|, deallocate using delete[]. 274 */ 275 keymaster_error_t parse_attestation_record(const uint8_t* asn1_key_desc, size_t asn1_key_desc_len, 276 uint32_t* attestation_version, // 277 keymaster_security_level_t* attestation_security_level, 278 uint32_t* keymaster_version, 279 keymaster_security_level_t* keymaster_security_level, 280 keymaster_blob_t* attestation_challenge, 281 AuthorizationSet* software_enforced, 282 AuthorizationSet* tee_enforced, 283 keymaster_blob_t* unique_id); 284 285 /** 286 * Caller takes ownership of |verified_boot_key->data|, deallocate using delete[]. 287 */ 288 keymaster_error_t parse_root_of_trust(const uint8_t* asn1_key_desc, size_t asn1_key_desc_len, 289 keymaster_blob_t* verified_boot_key, 290 keymaster_verified_boot_t* verified_boot_state, 291 bool* device_locked); 292 293 keymaster_error_t build_auth_list(const AuthorizationSet& auth_list, KM_AUTH_LIST* record); 294 295 keymaster_error_t extract_auth_list(const KM_AUTH_LIST* record, AuthorizationSet* auth_list); 296 } // namespace keymaster 297 298 #endif // SYSTEM_KEYMASTER_ATTESTATION_RECORD_H_ 299