1// Copyright 2015 The Android Open Source Project 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15#ifndef KEYSTORE_KEYSTORE_CLIENT_H_ 16#define KEYSTORE_KEYSTORE_CLIENT_H_ 17 18#include <set> 19#include <string> 20#include <vector> 21 22#include <android-base/macros.h> 23 24#include "authorization_set.h" 25#include "keystore.h" 26#include "keystore_return_types.h" 27 28namespace keystore { 29 30 31 32// An abstract class providing a convenient interface to keystore services. This 33// interface is designed to: 34// - hide details of the IPC mechanism (e.g. binder) 35// - use std data types 36// - encourage the use of keystore::AuthorizationSet[Builder] 37// - be convenient for native services integrating with keystore 38// - be safely mocked for unit testing (e.g. pure virtual methods) 39// 40// Example usage: 41// KeystoreClient* keystore = new KeyStoreClientImpl(); 42// keystore->AddRandomNumberGeneratorEntropy("unpredictable"); 43// 44// Notes on error codes: 45// Keystore binder methods return a variety of values including ResponseCode 46// values defined in keystore.h, keymaster_error_t values defined in 47// keymaster_defs.h, or just 0 or -1 (both of which conflict with 48// keymaster_error_t). The methods in this class converge on a single success 49// indicator for convenience. KM_ERROR_OK was chosen over ::NO_ERROR for two 50// reasons: 51// 1) KM_ERROR_OK is 0, which is a common convention for success, is the gmock 52// default, and allows error checks like 'if (error) {...'. 53// 2) Although both pollute the global namespace, KM_ERROR_OK has a prefix per 54// C convention and hopefully clients can use this interface without 55// needing to include 'keystore.h' directly. 56class KeystoreClient { 57 public: 58 KeystoreClient() = default; 59 virtual ~KeystoreClient() = default; 60 61 // Encrypts and authenticates |data| with minimal configuration for local 62 // decryption. If a key identified by |key_name| does not already exist it 63 // will be generated. On success returns true and populates |encrypted_data|. 64 // Note: implementations may generate more than one key but they will always 65 // have |key_name| as a prefix. 66 virtual bool encryptWithAuthentication(const std::string& key_name, const std::string& data, 67 std::string* encrypted_data) = 0; 68 69 // Decrypts and authenticates |encrypted_data| as output by 70 // EncryptWithAuthentication using the key(s) identified by |key_name|. On 71 // success returns true and populates |data|. 72 virtual bool decryptWithAuthentication(const std::string& key_name, 73 const std::string& encrypted_data, 74 std::string* data) = 0; 75 76 // Performs a Begin/Update/Finish sequence for an operation. The |purpose|, 77 // |key_name|, |input_parameters|, and |output_parameters| are as in 78 // BeginOperation. The |input_data| is as in UpdateOperation. The 79 // |signature_to_verify| and |output_data| are as in FinishOperation. On 80 // success returns true. 81 virtual bool oneShotOperation(KeyPurpose purpose, const std::string& key_name, 82 const keystore::AuthorizationSet& input_parameters, 83 const std::string& input_data, 84 const std::string& signature_to_verify, 85 keystore::AuthorizationSet* output_parameters, 86 std::string* output_data) = 0; 87 88 // Adds |entropy| to the random number generator. Returns KM_ERROR_OK on 89 // success and a Keystore ResponseCode or keymaster_error_t on failure. 90 virtual KeyStoreNativeReturnCode addRandomNumberGeneratorEntropy(const std::string& entropy) = 0; 91 92 // Generates a key according to the given |key_parameters| and stores it with 93 // the given |key_name|. The [hardware|software]_enforced_characteristics of 94 // the key are provided on success. Returns KM_ERROR_OK on success. Returns 95 // KM_ERROR_OK on success and a Keystore ResponseCode or keymaster_error_t on 96 // failure. 97 virtual KeyStoreNativeReturnCode generateKey(const std::string& key_name, 98 const keystore::AuthorizationSet& key_parameters, 99 keystore::AuthorizationSet* hardware_enforced_characteristics, 100 keystore::AuthorizationSet* software_enforced_characteristics) = 0; 101 102 // Provides the [hardware|software]_enforced_characteristics of a key 103 // identified by |key_name|. Returns KM_ERROR_OK on success and a Keystore 104 // ResponseCode or keymaster_error_t on failure. 105 virtual KeyStoreNativeReturnCode 106 getKeyCharacteristics(const std::string& key_name, 107 keystore::AuthorizationSet* hardware_enforced_characteristics, 108 keystore::AuthorizationSet* software_enforced_characteristics) = 0; 109 110 // Imports |key_data| in the given |key_format|, applies the given 111 // |key_parameters|, and stores it with the given |key_name|. The 112 // [hardware|software]_enforced_characteristics of the key are provided on 113 // success. Returns KM_ERROR_OK on success and a Keystore ResponseCode or 114 // keymaster_error_t on failure. 115 virtual KeyStoreNativeReturnCode importKey(const std::string& key_name, 116 const keystore::AuthorizationSet& key_parameters, 117 KeyFormat key_format, const std::string& key_data, 118 keystore::AuthorizationSet* hardware_enforced_characteristics, 119 keystore::AuthorizationSet* software_enforced_characteristics) = 0; 120 121 // Exports the public key identified by |key_name| to |export_data| using 122 // |export_format|. Returns KM_ERROR_OK on success and a Keystore ResponseCode 123 // or keymaster_error_t on failure. 124 virtual KeyStoreNativeReturnCode exportKey(KeyFormat export_format, const std::string& key_name, 125 std::string* export_data) = 0; 126 127 // Deletes the key identified by |key_name|. Returns KM_ERROR_OK on success 128 // and a Keystore ResponseCode or keymaster_error_t on failure. 129 virtual KeyStoreNativeReturnCode deleteKey(const std::string& key_name) = 0; 130 131 // Deletes all keys owned by the caller. Returns KM_ERROR_OK on success and a 132 // Keystore ResponseCode or keymaster_error_t on failure. 133 virtual KeyStoreNativeReturnCode deleteAllKeys() = 0; 134 135 // Begins a cryptographic operation (e.g. encrypt, sign) identified by 136 // |purpose| using the key identified by |key_name| and the given 137 // |input_parameters|. On success, any |output_parameters| and an operation 138 // |handle| are populated. Returns KM_ERROR_OK on success and a Keystore 139 // ResponseCode or keymaster_error_t on failure. 140 virtual KeyStoreNativeReturnCode beginOperation(KeyPurpose purpose, const std::string& key_name, 141 const keystore::AuthorizationSet& input_parameters, 142 keystore::AuthorizationSet* output_parameters, 143 uint64_t* handle) = 0; 144 145 // Continues the operation associated with |handle| using the given 146 // |input_parameters| and |input_data|. On success, the 147 // |num_input_bytes_consumed| and any |output_parameters| are populated. Any 148 // |output_data| will be appended. Returns KM_ERROR_OK on success and a 149 // Keystore ResponseCode or keymaster_error_t on failure. 150 virtual KeyStoreNativeReturnCode updateOperation(uint64_t handle, 151 const keystore::AuthorizationSet& input_parameters, 152 const std::string& input_data, size_t* num_input_bytes_consumed, 153 keystore::AuthorizationSet* output_parameters, 154 std::string* output_data) = 0; 155 156 // Finishes the operation associated with |handle| using the given 157 // |input_parameters| and, if necessary, a |signature_to_verify|. On success, 158 // any |output_parameters| are populated and |output_data| is appended. 159 // Returns KM_ERROR_OK on success and a Keystore ResponseCode or 160 // keymaster_error_t on failure. 161 virtual KeyStoreNativeReturnCode finishOperation(uint64_t handle, 162 const keystore::AuthorizationSet& input_parameters, 163 const std::string& signature_to_verify, 164 keystore::AuthorizationSet* output_parameters, 165 std::string* output_data) = 0; 166 167 // Aborts the operation associated with |handle|. Returns KM_ERROR_OK on 168 // success and a Keystore ResponseCode or keymaster_error_t on failure. 169 virtual KeyStoreNativeReturnCode abortOperation(uint64_t handle) = 0; 170 171 // Returns true if a key identified by |key_name| exists in the caller's 172 // key store. Returns false if an error occurs. 173 virtual bool doesKeyExist(const std::string& key_name) = 0; 174 175 // Provides a |key_name_list| containing all existing key names in the 176 // caller's key store starting with |prefix|. Returns true on success. 177 virtual bool listKeys(const std::string& prefix, std::vector<std::string>* key_name_list) = 0; 178 179 private: 180 DISALLOW_COPY_AND_ASSIGN(KeystoreClient); 181}; 182 183} // namespace keystore 184 185#endif // KEYSTORE_KEYSTORE_CLIENT_H_ 186