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