1 /* 2 ** 3 ** Copyright 2017, The Android Open Source Project 4 ** 5 ** Licensed under the Apache License, Version 2.0 (the "License"); 6 ** you may not use this file except in compliance with the License. 7 ** You may obtain a copy of the License at 8 ** 9 ** http://www.apache.org/licenses/LICENSE-2.0 10 ** 11 ** Unless required by applicable law or agreed to in writing, software 12 ** distributed under the License is distributed on an "AS IS" BASIS, 13 ** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 ** See the License for the specific language governing permissions and 15 ** limitations under the License. 16 */ 17 18 #ifndef KM_OPENSSL_ATTESTATION_UTILS_H_ 19 #define KM_OPENSSL_ATTESTATION_UTILS_H_ 20 21 #include <hardware/keymaster_defs.h> 22 #include <keymaster/android_keymaster_utils.h> 23 #include <keymaster/attestation_context.h> 24 25 #include <openssl/x509v3.h> 26 27 #include "openssl_utils.h" 28 29 namespace keymaster { 30 31 class AuthorizationSet; 32 class AttestationContext; 33 class AsymmetricKey; 34 class Key; 35 36 struct AttestKeyInfo { 37 AttestKeyInfo() = default; 38 AttestKeyInfo(const UniquePtr<Key>& key, const KeymasterBlob* issuer_subject, 39 keymaster_error_t* error); 40 AttestKeyInfo(AttestKeyInfo&&) = default; 41 AttestKeyInfo(const AttestKeyInfo&) = delete; 42 43 void operator=(const AttestKeyInfo&) = delete; 44 45 explicit operator bool() const { return signing_key.get() != nullptr; } 46 47 EVP_PKEY_Ptr signing_key; 48 const KeymasterBlob* issuer_subject; 49 }; 50 51 /** 52 * Generate attestation certificate. 53 * 54 * @param key is an AsymmetricKey object containing the key to be attested. The contained 55 * authorization lists are used for the key description. 56 * 57 * @param attest_params contains parameters for the attestation, including: 58 * 59 * TAG_ATTESTATION_CHALLENGE 60 * TAG_ATTESTATION_APPLICATION_ID 61 * TAG_ATTESTATION_ID_* 62 * TAG_DEVICE_UNIQUE_ATTESTATION 63 * TAG_RESET_SINCE_ROTATION 64 * 65 * @param attest_key optionally contains the attestation key and issuer subject to use. If 66 * attest_key.signing_key is non-null, that key will be used to sign the attestation and the 67 * issuer subject that will be placed in the attestation certificate. This is only used for 68 * KeyMint. If attest_key.signing_key is null, the signing key will be obtained from the 69 * AttestationContext, and the issuer subject will be obtained from the cetificate chain 70 * provided by the AttestationContext. 71 * 72 * @param context is the attestation context, used to generate unique IDs and obtain boot parameters 73 * as well as provide information about the SecurityLevel and KM version. 74 * 75 * @param error must be non-null and will be used to return any errors. In the event of an error 76 * the returned certificate chain will be empty. 77 * 78 * @return Returns the completed certificate chain, ordered from leaf (which is the generated 79 * attestation certificate) to root. 80 */ 81 CertificateChain generate_attestation(const AsymmetricKey& key, 82 const AuthorizationSet& attest_params, 83 AttestKeyInfo attest_key, 84 const AttestationContext& context, // 85 keymaster_error_t* error); 86 87 /** 88 * Generate attestation certificate. 89 * 90 * @param evp_key contains the key to be attested. Must not be null. 91 * 92 * @param sw_enforced contains the software-enforced elements of the key description. 93 * 94 * @param hw_enforced contains the hardware-enforced elements of the key description. 95 * 96 * @param attest_params contains parameters for the attestation, including: 97 * 98 * TAG_ATTESTATION_CHALLENGE 99 * TAG_ATTESTATION_APPLICATION_ID 100 * TAG_ATTESTATION_ID_* 101 * TAG_DEVICE_UNIQUE_ATTESTATION 102 * TAG_RESET_SINCE_ROTATION 103 * 104 * @param attest_key optionally contains the attestation key and issuer subject to use. If 105 * attest_key.signing_key is non-null, that key will be used to sign the attestation and the 106 * issuer subject that will be placed in the attestation certificate. This is only used for 107 * KeyMint. If attest_key.signign_key is null, the signing key will be obtained from the 108 * AttestationContext, and the issuer subject will be obtained from the cetificate chain 109 * provided by the AttestationContext. 110 * 111 * @param context is the attestation context, used to generate unique IDs and obtain boot parameters 112 * as well as provide information about the SecurityLevel and KM version. 113 * 114 * @param error must be non-null and will be used to return any errors. In the event of an error 115 * the returned certificate chain will be empty. 116 * 117 * @return Returns the completed certificate chain, ordered from leaf (which is the generated 118 * attestation certificate) to root. 119 */ 120 CertificateChain generate_attestation(const EVP_PKEY* evp_key, // 121 const AuthorizationSet& sw_enforced, // 122 const AuthorizationSet& hw_enforced, // 123 const AuthorizationSet& attest_params, 124 AttestKeyInfo attest_key, 125 const AttestationContext& context, // 126 keymaster_error_t* error); 127 128 } // namespace keymaster 129 130 #endif // KM_OPENSSL_ATTESTATION_UTILS_H_ 131