• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1/*
2 * Copyright (C) 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
17syntax = "proto3";
18
19package nugget.app.keymaster;
20
21import "nugget/app/keymaster/keymaster_defs.proto";
22import "nugget/app/keymaster/keymaster_types.proto";
23import "nugget/protobuf/options.proto";
24
25/*
26 * Keymaster service methods.
27 *
28 * TODO: some methods may be implemented in the host side HAL implementation.
29 */
30service Keymaster {
31  option (nugget.protobuf.app_id) = "KEYMASTER";
32  option (nugget.protobuf.app_name) = "Keymaster";
33  option (nugget.protobuf.app_version) = 1;
34  /*
35   * Both request and response buffers are sized such
36   * that a key-blob may be fully contained.
37   *
38   * TODO: revisit this choice in the event that memory
39   * is running out.  Supporting smaller buffers will
40   * require that the keymaster app switch from the
41   * transport API to the datagram API.
42   */
43  option (nugget.protobuf.request_buffer_size) = 3072;
44  option (nugget.protobuf.response_buffer_size) = 2048;
45
46  /*
47   * KM3 methods, from:
48   *     ::android::hardware::keymaster::V3_0::IKeymasterDevice
49   */
50  rpc AddRngEntropy (AddRngEntropyRequest) returns (AddRngEntropyResponse);
51  rpc GenerateKey (GenerateKeyRequest) returns (GenerateKeyResponse);
52  rpc GetKeyCharacteristics (GetKeyCharacteristicsRequest) returns (GetKeyCharacteristicsResponse);
53  rpc ImportKey (ImportKeyRequest) returns (ImportKeyResponse);
54  rpc ExportKey (ExportKeyRequest) returns (ExportKeyResponse);
55  rpc StartAttestKey (StartAttestKeyRequest) returns (StartAttestKeyResponse);
56  rpc UpgradeKey (UpgradeKeyRequest) returns (UpgradeKeyResponse);
57  rpc DeleteKey (DeleteKeyRequest) returns (DeleteKeyResponse);
58  rpc DeleteAllKeys (DeleteAllKeysRequest) returns (DeleteAllKeysResponse);
59  rpc DestroyAttestationIds (DestroyAttestationIdsRequest) returns (DestroyAttestationIdsResponse);
60  rpc BeginOperation (BeginOperationRequest) returns (BeginOperationResponse);
61  rpc UpdateOperation (UpdateOperationRequest) returns (UpdateOperationResponse);
62  rpc FinishOperation (FinishOperationRequest) returns (FinishOperationResponse);
63  rpc AbortOperation (AbortOperationRequest) returns (AbortOperationResponse);
64
65  /*
66   * KM4 methods.
67   */
68  rpc ImportWrappedKey (ImportWrappedKeyRequest) returns (ImportKeyResponse);
69
70  /*
71   * Vendor specific methods (bootloader, manufacturing, status,
72   * factory reset, upgrade).
73   */
74  // Only callable by the Bootloader.
75  rpc SetRootOfTrust (SetRootOfTrustRequest) returns (SetRootOfTrustResponse);
76  // Only callable by the Bootloader.
77  rpc SetBootState (SetBootStateRequest) returns (SetBootStateResponse);
78  // Only callable at the Device Factory.
79  rpc ProvisionDeviceIds (ProvisionDeviceIdsRequest) returns (ProvisionDeviceIdsResponse);
80  // Only callable at the Device Factory.
81  rpc ReadTeeBatchCertificate (ReadTeeBatchCertificateRequest) returns (ReadTeeBatchCertificateResponse);
82
83  /*
84   * More KM4 methods.
85   */
86  rpc GetHmacSharingParameters (GetHmacSharingParametersRequest) returns (GetHmacSharingParametersResponse);
87  rpc ComputeSharedHmac (ComputeSharedHmacRequest) returns (ComputeSharedHmacResponse);
88
89  /*
90   * DTup input session methods.
91   */
92  rpc HandshakeDTup (DTupHandshakeRequest) returns (DTupHandshakeResponse);
93  rpc FetchDTupInputEvent (DTupFetchInputEventRequest) returns (DTupFetchInputEventResponse);
94
95  /*
96   * More vendor specific methods.
97   */
98  // Only callable once per boot.
99  rpc SetSystemVersionInfo (SetSystemVersionInfoRequest) returns (SetSystemVersionInfoResponse);
100  rpc GetBootInfo (GetBootInfoRequest) returns (GetBootInfoResponse);
101
102  /*
103   * Called during provisioning by the CitadelProvision tool.
104   */
105  rpc ProvisionPresharedSecret (ProvisionPresharedSecretRequest) returns (ProvisionPresharedSecretResponse);
106
107  /*
108   * Additional attestation methods.
109   */
110  rpc ContinueAttestKey(ContinueAttestKeyRequest) returns (ContinueAttestKeyResponse);
111  rpc FinishAttestKey(FinishAttestKeyRequest) returns (FinishAttestKeyResponse);
112
113  /*
114   * More vendor specific methods.
115   */
116  rpc ProvisionCertificates(ProvisionCertificatesRequest) returns (ProvisionCertificatesResponse);
117
118  // These are implemented with a enum, so new RPCs must be appended, and
119  // deprecated RPCs need placeholders.
120}
121
122/*
123 *  KM3 messages.
124 */
125
126// AddEntropy
127message AddRngEntropyRequest {
128  bytes data = 1;
129}
130message AddRngEntropyResponse {
131  ErrorCode error_code = 1;
132}
133
134// GenerateKey
135message GenerateKeyRequest {
136  KeyParameters params = 1;
137  uint64 creation_time_ms = 2;  // Rough current time (ms since epoch).
138}
139message GenerateKeyResponse {
140  ErrorCode error_code = 1;
141  KeyBlob blob = 2;
142  KeyCharacteristics characteristics = 3;
143}
144
145// GetKeyCharacteristics
146message GetKeyCharacteristicsRequest {
147  KeyBlob blob = 1;
148  bytes client_id = 2;
149  bytes app_data = 3;
150}
151message GetKeyCharacteristicsResponse {
152  ErrorCode error_code = 1;
153  KeyCharacteristics characteristics = 2;
154}
155
156// ImportKey
157message ImportKeyRequest {
158  KeyParameters params = 1;
159  RSAKey rsa = 2;
160  ECKey ec = 3;
161  SymmetricKey symmetric_key = 4;
162  uint64 creation_time_ms = 5;     // Rough current time (ms since epoch).
163};
164message ImportKeyResponse {
165  ErrorCode error_code = 1;
166  KeyBlob blob = 2;
167  KeyCharacteristics characteristics = 3;
168};
169
170// ExportKey
171message ExportKeyRequest {
172  KeyFormat format = 1;
173  KeyBlob blob = 2;
174  bytes client_id = 3;
175  bytes app_data = 4;
176};
177message ExportKeyResponse {
178  ErrorCode error_code = 1;
179  Algorithm algorithm = 2;
180  RSAKey rsa = 3;
181  ECKey ec = 4;
182};
183
184// StartAttestKey
185message StartAttestKeyRequest {
186  KeyBlob blob = 1;
187  KeyParameters params = 2;
188  uint32 attestation_app_id_len = 3;
189  AttestationSelector selector = 4;
190  bytes not_before = 5;      // strftime('%y%m%d%H%M%SZ') [13 octects]
191  bytes not_after = 6;       // strftime('%y%m%d%H%M%SZ') [13 octects]
192}
193message StartAttestKeyResponse {
194  ErrorCode error_code = 1;
195  OperationHandle handle = 2;
196  bytes certificate_prologue = 3;
197}
198
199// ContinueAttestKeyRequest
200message ContinueAttestKeyRequest {
201  OperationHandle handle = 1;
202  //  bytes attestation_app_id = 2;    // Unused, contained within params
203  KeyParameters params = 3;
204}
205message  ContinueAttestKeyResponse {
206  ErrorCode error_code = 1;
207  bytes certificate_body = 2;
208}
209
210// FinishAttestKeyRequest
211message FinishAttestKeyRequest {
212  OperationHandle handle = 1;
213}
214message  FinishAttestKeyResponse {
215  ErrorCode error_code = 1;
216  bytes certificate_epilogue = 2;
217  ChipFusing chip_fusing = 3;
218  bool nodelocked_ro = 4;
219}
220
221// UpgradeKey
222message UpgradeKeyRequest {
223  KeyBlob blob = 1;
224  KeyParameters params = 2;
225}
226message UpgradeKeyResponse {
227  ErrorCode error_code = 1;
228  KeyBlob blob = 2;
229}
230
231// DeleteKey
232message DeleteKeyRequest {
233  KeyBlob blob = 1;
234}
235message DeleteKeyResponse {
236  ErrorCode error_code = 1;
237}
238
239// DeleteAllKeys
240message DeleteAllKeysRequest {}
241message DeleteAllKeysResponse {
242  ErrorCode error_code = 1;
243}
244
245// DestroyAttestationIds
246message DestroyAttestationIdsRequest {}
247message DestroyAttestationIdsResponse {
248  ErrorCode error_code = 1;
249}
250
251// BeginOperation
252message BeginOperationRequest {
253  KeyPurpose purpose = 1;
254  KeyBlob blob = 2;
255  KeyParameters params = 3;
256  HardwareAuthToken auth_token = 4;
257}
258message BeginOperationResponse {
259  ErrorCode error_code = 1;
260  KeyParameters params = 2;
261  OperationHandle handle = 3;
262  Algorithm algorithm = 4;
263  uint32 key_bits = 5;
264}
265
266// UpdateOperation
267message UpdateOperationRequest {
268  OperationHandle handle = 1;
269  KeyParameters params = 2;
270  bytes input = 3;
271  HardwareAuthToken auth_token = 4;
272  VerificationToken verification_token = 5;
273}
274message UpdateOperationResponse {
275  ErrorCode error_code = 1;
276  uint32 consumed = 2;
277  KeyParameters params = 3;
278  bytes output = 4;
279}
280
281// FinishOperation
282message FinishOperationRequest {
283  OperationHandle handle = 1;
284  KeyParameters params = 2;
285  bytes input = 3;
286  bytes signature = 4;
287  HardwareAuthToken auth_token = 5;
288  VerificationToken verification_token = 6;
289};
290message FinishOperationResponse {
291  ErrorCode error_code = 1;
292  KeyParameters params = 2;
293  bytes output = 3;
294};
295
296// AbortOperation
297message AbortOperationRequest {
298  OperationHandle handle = 1;
299};
300message AbortOperationResponse {
301  ErrorCode error_code = 1;
302};
303
304/*
305 * KM4 messages.
306 */
307
308// ImportWrappedKey
309message ImportWrappedKeyRequest {
310  uint32 key_format = 1;
311  KeyParameters params = 2;
312  bytes rsa_envelope = 3;
313  bytes initialization_vector = 4;   // Fixed sized array.
314  bytes encrypted_import_key = 5;
315  bytes aad = 6;
316  bytes gcm_tag = 7;                 // Fixed sized array.
317  KeyBlob wrapping_key_blob = 8;
318  bytes masking_key = 9;             // Fixed sized array.
319  uint64 creation_time_ms = 10;      // Rough current time (ms since epoch).
320}
321// ImportWrappedKey returns a ImportKeyResponse.
322
323// GetHmacSharingParametersRequest
324message GetHmacSharingParametersRequest {
325}
326message GetHmacSharingParametersResponse {
327  ErrorCode error_code = 1;
328  HmacSharingParameters hmac_sharing_params = 2;
329}
330
331// ComputeSharedHmacRequest
332message ComputeSharedHmacRequest {
333  repeated HmacSharingParameters hmac_sharing_params = 1;
334}
335message ComputeSharedHmacResponse {
336  ErrorCode error_code = 1;
337  bytes sharing_check = 2;
338}
339
340/*
341 * Vendor HAL.
342 */
343
344// SetRootOfTrustRequest
345// Only callable by the Bootloader.
346message SetRootOfTrustRequest {
347  bytes digest = 1;                  // This is a SHA256 digest.
348}
349message SetRootOfTrustResponse {
350  // Specified in keymaster_defs.proto:ErrorCode
351  ErrorCode error_code = 1;
352}
353
354// SetBootStateRequest
355// Only callable by the Bootloader.
356message SetBootStateRequest {
357  bool is_unlocked = 1;
358  bytes public_key = 2;              // This is a SHA256 digest.
359  BootColor color = 3;
360  uint32 system_version = 4;         // Deprecated.
361  uint32 system_security_level = 5;  // Patch level of the boot partition.
362  bytes boot_hash = 6;               // This is a SHA256 digest.
363}
364message SetBootStateResponse {
365  // Specified in keymaster_defs.proto:ErrorCode
366  ErrorCode error_code = 1;
367}
368
369// ProvisionDeviceIds
370// Only callable at the Device Factory
371message ProvisionDeviceIdsRequest {
372  bytes product_brand = 1;
373  bytes product_device = 2;
374  bytes product_name = 3;
375  bytes serialno = 4;
376  bytes product_manufacturer = 5;
377  bytes product_model = 6;
378  bytes imei = 7;
379  bytes meid = 8;
380}
381message ProvisionDeviceIdsResponse {
382  // Specified in keymaster_defs.proto:ErrorCode
383  ErrorCode error_code = 1;
384  ChipFusing chip_fusing = 2;
385  bool nodelocked_ro = 3;
386}
387
388// ReadTeeBatchCertificate
389// Only callable at the Device Factory
390message ReadTeeBatchCertificateRequest {
391  Algorithm algorithm = 1;
392}
393message ReadTeeBatchCertificateResponse {
394  ErrorCode error_code = 1;
395  RSAKey rsa = 2;   // rsa or ec set based on request algorithm selector.
396  ECKey ec = 3;
397  bytes batch_cert = 4;
398}
399
400message DTupHandshakeRequest {
401  bytes nonce_client = 1;
402}
403
404message DTupHandshakeResponse {
405  DTupError error_code = 1;
406  bytes nonce_citadel = 2;
407  bytes signature = 3;
408}
409
410message DTupFetchInputEventRequest {}
411
412message DTupFetchInputEventResponse {
413  DTupError error_code = 1;
414  DTupKeyEvent event = 2;
415  bytes signature = 3;
416}
417
418message SetSystemVersionInfoRequest {
419  uint32 system_version = 1;  // getprop "ro.build.version.release"
420  uint32 system_security_level = 2; // getprop "ro.build.version.security_patch"
421  uint32 vendor_security_level = 3; // getprop "ro.vendor.build.security_patch"
422}
423
424message SetSystemVersionInfoResponse {
425  // Specified in keymaster_defs.proto:ErrorCode
426  ErrorCode error_code = 1;
427}
428
429message GetBootInfoRequest {}
430
431message GetBootInfoResponse {
432  ErrorCode error_code = 1;
433  bool is_unlocked = 2;
434  BootColor boot_color = 3;
435  bytes boot_key = 4;               // This is a SHA256 digest.
436  bytes boot_hash = 5;              // This is a SHA256 digest.
437}
438
439message ProvisionPresharedSecretRequest {
440  bytes preshared_secret = 1;
441  bool get_status = 2;
442}
443message ProvisionPresharedSecretResponse {
444  ErrorCode error_code = 1;
445  PresharedSecretStatus status = 2;
446  BootColor color = 3;
447  bytes digest = 4;
448}
449
450message ProvisionCertificatesRequest {
451  uint32 block_number = 1;
452  bytes cert_block = 2;
453  bytes digest = 3;
454}
455message ProvisionCertificatesResponse {
456  ErrorCode error_code = 1;
457  CertificateStatus cert_status = 2;
458}