1 /* 2 * Copyright 2017 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 ATAP_OPS_H_ 18 #define ATAP_OPS_H_ 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 #include "atap_sysdeps.h" 25 #include "atap_types.h" 26 27 /* High-level operations/functions/methods that are platform 28 * dependent. 29 */ 30 struct AtapOps { 31 /* This pointer can be used by the application/TEE and is typically 32 * used in each operation to get a pointer to platform-specific 33 * resources. It cannot be used by this library. 34 */ 35 void* user_data; 36 37 /* Reads the Product Id from permanent attibutes, and outputs 38 * ATAP_PRODUCT_ID_LEN bytes to |product_id|. On success, returns 39 * ATAP_RESULT_OK. 40 */ 41 AtapResult (*read_product_id)(AtapOps* ops, 42 uint8_t product_id[ATAP_PRODUCT_ID_LEN]); 43 44 /* Outputs the type of the authentication key to |key_type|. On success, 45 * returns ATAP_RESULT_OK. 46 */ 47 AtapResult (*get_auth_key_type)(AtapOps* ops, AtapKeyType* key_type); 48 49 /* Reads the stored authentication key certificate chain. On success, 50 * returns ATAP_RESULT_OK and populates |cert_chain|. New memory will be 51 * allocated for the certificate chain entries, and caller takes 52 * ownership. Entries for |cert_chain| must be allocated using 53 * atap_malloc(), and cert_chain->entry_count must be valid. 54 */ 55 AtapResult (*read_auth_key_cert_chain)(AtapOps* ops, 56 AtapCertChain* cert_chain); 57 58 /* Writes the |key_type| attestation |key| and |cert_chain|. The data 59 * MUST be stored in a location that cannot be read or written to by 60 * Android. For certify operations, |key| will be NULL. On success, 61 * returns ATAP_RESULT_OK. 62 */ 63 AtapResult (*write_attestation_key)(AtapOps* ops, 64 AtapKeyType key_type, 65 const AtapBlob* key, 66 const AtapCertChain* cert_chain); 67 68 /* Reads an asymmetric public key of type |key_type| to be certified 69 * for attestation. The keypair to be certified may either be generated 70 * on the fly or provisioned and securely stored at an earlier stage. On 71 * success, returns ATAP_RESULT_OK and writes at most ATAP_KEY_LEN_MAX 72 * bytes to |pubkey|, and the size of the public key is written to 73 * |*pubkey_len|. 74 */ 75 AtapResult (*read_attestation_public_key)(AtapOps* ops, 76 AtapKeyType key_type, 77 uint8_t pubkey[ATAP_KEY_LEN_MAX], 78 uint32_t* pubkey_len); 79 80 /* Reads the SoC global key. If an SoC global key is not supported, 81 * ATAP_RESULT_ERROR_UNSUPPORTED_OPERATION is returned and nothing is 82 * written to |global_key|. On success, returns ATAP_RESULT_OK and writes 83 * ATAP_AES_128_KEY_LEN bytes to |global_key|. 84 */ 85 AtapResult (*read_soc_global_key)(AtapOps* ops, 86 uint8_t global_key[ATAP_AES_128_KEY_LEN]); 87 88 /* Writes the hex encoded UUID that appears in the subjectName of the 89 * Product Key Certificate to storage. The UUID will be read by 90 * invoking a fastboot command. On success, returns ATAP_RESULT_OK. 91 */ 92 AtapResult (*write_hex_uuid)(AtapOps* ops, 93 const uint8_t uuid[ATAP_HEX_UUID_LEN]); 94 95 /* Outputs |buf_size| random bytes to |buf|. Bytes should be 96 * generated with either a hardware random number generator, or a 97 * pseudorandom function seeded with hardware entropy. 98 */ 99 AtapResult (*get_random_bytes)(AtapOps* ops, uint8_t* buf, uint32_t buf_size); 100 101 /* Signs |nonce_len| bytes of |nonce| with the authentication key. On 102 * success, returns ATAP_RESULT_OK and writes at most 103 * ATAP_SIGNATURE_LEN_MAX bytes to |signature|, and the size of the 104 * signature is written to |*signature_len|. 105 */ 106 AtapResult (*auth_key_sign)(AtapOps* ops, 107 const uint8_t* nonce, 108 uint32_t nonce_len, 109 uint8_t signature[ATAP_SIGNATURE_LEN_MAX], 110 uint32_t* signature_len); 111 112 /* Generates a new ECDH keypair using curve |curve|, and writes 113 * ATAP_ECDH_KEY_LEN bytes of the public key to |pubkey|. Computes the 114 * ECDH shared secret using |other_pubkey| and the generated private key 115 * as inputs. Writes |ATAP_ECDH_SHARED_SECRET_LEN| bytes to 116 * |shared_secret|. The raw private key material is not exposed to the 117 * caller. On success, returns ATAP_RESULT_OK. 118 */ 119 AtapResult (*ecdh_shared_secret_compute)( 120 AtapOps* ops, 121 AtapCurveType curve, 122 const uint8_t other_pubkey[ATAP_ECDH_KEY_LEN], 123 uint8_t pubkey[ATAP_ECDH_KEY_LEN], 124 uint8_t shared_secret[ATAP_ECDH_SHARED_SECRET_LEN]); 125 126 /* Encrypts |len| bytes of |plaintext| using |key| and |iv|, and outputs 127 * |len| bytes to |ciphertext| and ATAP_GCM_TAG_LEN bytes to |tag|. On 128 * success, returns ATAP_RESULT_OK. 129 */ 130 AtapResult (*aes_gcm_128_encrypt)(AtapOps* ops, 131 const uint8_t* plaintext, 132 uint32_t len, 133 const uint8_t iv[ATAP_GCM_IV_LEN], 134 const uint8_t key[ATAP_AES_128_KEY_LEN], 135 uint8_t* ciphertext, 136 uint8_t tag[ATAP_GCM_TAG_LEN]); 137 138 /* Decrypts |len| bytes of |ciphertext| using |key|, |iv|, and |tag|, and 139 * outputs |len| bytes to |plaintext|. On success, returns ATAP_RESULT_OK. 140 */ 141 AtapResult (*aes_gcm_128_decrypt)(AtapOps* ops, 142 const uint8_t* ciphertext, 143 uint32_t len, 144 const uint8_t iv[ATAP_GCM_IV_LEN], 145 const uint8_t key[ATAP_AES_128_KEY_LEN], 146 const uint8_t tag[ATAP_GCM_TAG_LEN], 147 uint8_t* plaintext); 148 149 /* Computes a SHA256 hash of the |input|, and outputs 150 * ATAP_SHA256_DIGEST_LEN bytes to |HASH|. On success, returns 151 * ATAP_RESULT_OK. 152 */ 153 AtapResult (*sha256)(AtapOps* ops, 154 const uint8_t* input, 155 uint32_t input_len, 156 uint8_t hash[ATAP_SHA256_DIGEST_LEN]); 157 158 /* Computes HKDF (as specificed by RFC 5868) of initial keying 159 * material |ikm| with |salt| and |info| using SHA256 as the digest, 160 * and outputs |okm_len| bytes to |okm|. 161 */ 162 AtapResult (*hkdf_sha256)(AtapOps* ops, 163 const uint8_t* salt, 164 uint32_t salt_len, 165 const uint8_t* ikm, 166 uint32_t ikm_len, 167 const uint8_t* info, 168 uint32_t info_len, 169 uint8_t* okm, 170 uint32_t okm_len); 171 }; 172 173 #ifdef __cplusplus 174 } 175 #endif 176 177 #endif /* ATAP_OPS_H_ */ 178