1// Copyright 2019 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5// Next MinVersion: 1
6
7// This file defines the mojo interface between Android and Chrome OS for the
8// keymaster implementation used in ARC.
9
10module arc.mojom;
11
12// Host is implemented in Chrome. Listens until server and instance come online
13// and forwards a server handle to the instance.
14interface KeymasterHost {
15  GetServer@0() => (KeymasterServer server_ptr);
16};
17
18// Instance is implemented in ARC. Retrieves a server pointer from the host and
19// uses it to fulfill Android Keymaster operations.
20interface KeymasterInstance {
21  Init@0(KeymasterHost host_ptr) => ();
22};
23
24// Server is implemented in arc-keymasterd in Chrome OS. This interface is the
25// mojo equivalent of the Keymaster 3.0 HIDL interface. Please refer to
26// Android's IKeymasterDevice.hal for a more detailed description on how the
27// methods and structs below should function.
28interface KeymasterServer {
29
30  // Sets the Android version information used.
31  SetSystemVersion@0(uint32 os_version, uint32 os_patchlevel);
32
33  AddRngEntropy@1(array<uint8> data) => (int32 error);
34
35  // Returns the characteristics of the specified key if it is valid.
36  GetKeyCharacteristics@2(GetKeyCharacteristicsRequest request) =>
37      (GetKeyCharacteristicsResult response);
38
39  GenerateKey@3(array<KeyParameter> key_params) => (GenerateKeyResult response);
40
41  ImportKey@4(ImportKeyRequest request) => (ImportKeyResult response);
42
43  // Exports a public key, returning the key in the specified format.
44  ExportKey@5(ExportKeyRequest request) => (ExportKeyResult response);
45
46  // Generates a signed X.509 certificate chain attesting to the presence of
47  // keyToAttest in Keymaster.
48  AttestKey@6(AttestKeyRequest request) => (AttestKeyResult result);
49
50  // Upgrades a key generated by an older version of the Keymaster.
51  UpgradeKey@7(UpgradeKeyRequest request) => (UpgradeKeyResult response);
52
53  DeleteKey@8(array<uint8> key_blob) => (int32 error);
54
55  DeleteAllKeys@9() => (int32 error);
56
57  // Begins a cryptographic operation using the specified key.
58  Begin@10(BeginRequest request) => (BeginResult result);
59
60  // Provides data and possibly receives output from an ongoing operation.
61  Update@11(UpdateRequest request) => (UpdateResult response);
62
63  // Finalizes a cryptographic operation and invalidates operation handle.
64  Finish@12(FinishRequest request) => (FinishResult response);
65
66  // Aborts an operation and invalidates the operation handle.
67  Abort@13(uint64 op_handle) => (int32 error);
68};
69
70////////////////////////////////////////////////////////////////////////////////
71// KeymasterServer helper enums and structs
72
73[Extensible]
74enum KeyPurpose {
75  ENCRYPT = 0,    // Usable with RSA, EC and AES keys.
76  DECRYPT = 1,    // Usable with RSA, EC and AES keys.
77  SIGN = 2,       // Usable with RSA, EC and HMAC keys.
78  VERIFY = 3,     // Usable with RSA, EC and HMAC keys.
79  DERIVE_KEY = 4, // Usable with EC keys.
80  WRAP_KEY = 5,   // Usable with wrapping keys.
81};
82
83[Extensible]
84enum KeyFormat {
85  X509 = 0,  // for public key export
86  PKCS8 = 1, // for asymmetric key pair import
87  RAW = 3,   // for symmetric key import and export
88};
89
90// Helper union for key parameter values.
91union IntegerKeyParam {
92  bool boolean_value;  // KM_BOOL
93  uint32 integer;      // KM_ENUM, KM_ENUM_REP, KM_INT and KM_INT_REP
94  uint64 long_integer; // KM_LONG
95  uint64 date_time;    // KM_DATE
96  array<uint8> blob;   // KM_BIGNUM and KM_BYTES
97};
98
99struct KeyParameter {
100  // Discriminates the IntegerKeyParam union field used.
101  uint32 tag;
102  IntegerKeyParam param;
103};
104
105// Defines the attributes of a key, including cryptographic parameters, and
106// usage restrictions.
107struct KeyCharacteristics {
108  array<KeyParameter> software_enforced;
109  array<KeyParameter> tee_enforced;
110};
111
112////////////////////////////////////////////////////////////////////////////////
113// KeymasterServer request and response structs
114
115struct GetKeyCharacteristicsRequest {
116  array<uint8> key_blob;
117  array<uint8> client_id;
118  array<uint8> app_data;
119};
120
121struct GetKeyCharacteristicsResult {
122  KeyCharacteristics key_characteristics;
123  int32 error;
124};
125
126struct GenerateKeyResult {
127  array<uint8> key_blob;
128  KeyCharacteristics key_characteristics;
129  int32 error;
130};
131
132struct ImportKeyRequest {
133  array<KeyParameter> key_description;
134  KeyFormat key_format;
135  array<uint8> key_data;
136};
137
138struct ImportKeyResult {
139  array<uint8> key_blob;
140  KeyCharacteristics key_characteristics;
141  int32 error;
142};
143
144struct ExportKeyRequest {
145  KeyFormat key_format;
146  array<uint8> key_blob;
147  array<uint8> client_id;
148  array<uint8> app_data;
149};
150
151struct ExportKeyResult {
152  array<uint8> key_material;
153  int32 error;
154};
155
156struct AttestKeyRequest {
157  array<uint8> key_to_attest;
158  array<KeyParameter> attest_params;
159};
160
161struct AttestKeyResult {
162  array<array<uint8>> cert_chain;
163  int32 error;
164};
165
166struct UpgradeKeyRequest {
167  array<uint8> key_blob_to_upgrade;
168  array<KeyParameter> upgrade_params;
169};
170
171struct UpgradeKeyResult {
172  array<uint8> upgraded_key_blob;
173  int32 error;
174};
175
176struct BeginRequest {
177  KeyPurpose purpose;
178  array<uint8> key;
179  array<KeyParameter> in_params;
180};
181
182struct BeginResult {
183  array<KeyParameter> out_params;
184  uint64 op_handle;
185  int32 error;
186};
187
188struct UpdateRequest {
189  uint64 op_handle;
190  array<KeyParameter> in_params;
191  array<uint8> input;
192};
193
194struct UpdateResult {
195  uint32 input_consumed;
196  array<KeyParameter> out_params;
197  array<uint8> output;
198  int32 error;
199};
200
201struct FinishRequest {
202  uint64 op_handle;
203  array<KeyParameter> in_params;
204  array<uint8> input;
205  array<uint8> signature;
206};
207
208struct FinishResult {
209  array<KeyParameter> out_params;
210  array<uint8> output;
211  int32 error;
212};
213