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