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  /*
119   * KM4.1 methods.
120   */
121  rpc DeviceLocked(DeviceLockedRequest) returns (DeviceLockedResponse);
122  rpc EarlyBootEnded(EarlyBootEndedRequest) returns (EarlyBootEndedResponse);
123
124  /*
125   * More vendor specific methods.
126   */
127  rpc ReadCertificate(ReadCertificateRequest) returns (ReadCertificateResponse);
128  rpc IdentityStartAttestKey (IdentityStartAttestKeyRequest) returns (IdentityStartAttestKeyResponse);
129  rpc IdentityFinishAttestKey (IdentityFinishAttestKeyRequest) returns (IdentityFinishAttestKeyResponse);
130
131  /*
132   * Resume-on-Reboot implementation.
133   */
134  rpc VigoReadVS(VigoReadVSRequest) returns (VigoReadVSResponse);
135  rpc VigoStartChannel(VigoStartChannelRequest)
136      returns (VigoStartChannelResponse);
137  rpc VigoStoreSecret(VigoStoreSecretRequest) returns (VigoStoreSecretResponse);
138  rpc VigoReleaseSecret(VigoReleaseSecretRequest)
139      returns (VigoReleaseSecretResponse);
140
141  // These are implemented with a enum, so new RPCs must be appended, and
142  // deprecated RPCs need placeholders.
143}
144
145/*
146 *  KM3 messages.
147 */
148
149// AddEntropy
150message AddRngEntropyRequest {
151  bytes data = 1;
152}
153message AddRngEntropyResponse {
154  ErrorCode error_code = 1;
155}
156
157// GenerateKey
158message GenerateKeyRequest {
159  KeyParameters params = 1;
160  uint64 creation_time_ms = 2;  // Rough current time (ms since epoch).
161}
162message GenerateKeyResponse {
163  ErrorCode error_code = 1;
164  KeyBlob blob = 2;
165  KeyCharacteristics characteristics = 3;
166}
167
168// GetKeyCharacteristics
169message GetKeyCharacteristicsRequest {
170  KeyBlob blob = 1;
171  bytes client_id = 2;
172  bytes app_data = 3;
173}
174message GetKeyCharacteristicsResponse {
175  ErrorCode error_code = 1;
176  KeyCharacteristics characteristics = 2;
177}
178
179// ImportKey
180message ImportKeyRequest {
181  KeyParameters params = 1;
182  RSAKey rsa = 2;
183  ECKey ec = 3;
184  SymmetricKey symmetric_key = 4;
185  uint64 creation_time_ms = 5;     // Rough current time (ms since epoch).
186};
187message ImportKeyResponse {
188  ErrorCode error_code = 1;
189  KeyBlob blob = 2;
190  KeyCharacteristics characteristics = 3;
191};
192
193// ExportKey
194message ExportKeyRequest {
195  KeyFormat format = 1;
196  KeyBlob blob = 2;
197  bytes client_id = 3;
198  bytes app_data = 4;
199};
200message ExportKeyResponse {
201  ErrorCode error_code = 1;
202  Algorithm algorithm = 2;
203  RSAKey rsa = 3;
204  ECKey ec = 4;
205};
206
207// StartAttestKey
208message StartAttestKeyRequest {
209  KeyBlob blob = 1;
210  KeyParameters params = 2;
211  uint32 attestation_app_id_len = 3;
212  AttestationSelector selector = 4;
213  bytes not_before = 5;      // strftime('%Y%m%d%H%M%SZ') [15 octects]
214  bytes not_after = 6;       // strftime('%Y%m%d%H%M%SZ') [15 octects]
215  bytes caller_issuer_subj_name = 7;
216  KeyParameters caller_key_params = 8;
217}
218message StartAttestKeyResponse {
219  ErrorCode error_code = 1;
220  OperationHandle handle = 2;
221  bytes certificate_prologue = 3;
222}
223
224// ContinueAttestKeyRequest
225message ContinueAttestKeyRequest {
226  OperationHandle handle = 1;
227  //  bytes attestation_app_id = 2;    // Unused, contained within params
228  KeyParameters params = 3;
229}
230message  ContinueAttestKeyResponse {
231  ErrorCode error_code = 1;
232  bytes certificate_body = 2;
233}
234
235// FinishAttestKeyRequest
236message FinishAttestKeyRequest {
237  OperationHandle handle = 1;
238  KeyBlob caller_blob = 2;
239  KeyParameters caller_key_params = 3;
240}
241message  FinishAttestKeyResponse {
242  ErrorCode error_code = 1;
243  bytes certificate_epilogue = 2;
244  ChipFusing chip_fusing = 3;
245  bool nodelocked_ro = 4;
246}
247
248// UpgradeKey
249message UpgradeKeyRequest {
250  KeyBlob blob = 1;
251  KeyParameters params = 2;
252}
253message UpgradeKeyResponse {
254  ErrorCode error_code = 1;
255  KeyBlob blob = 2;
256}
257
258// DeleteKey
259message DeleteKeyRequest {
260  KeyBlob blob = 1;
261}
262message DeleteKeyResponse {
263  ErrorCode error_code = 1;
264}
265
266// DeleteAllKeys
267message DeleteAllKeysRequest {}
268message DeleteAllKeysResponse {
269  ErrorCode error_code = 1;
270}
271
272// DestroyAttestationIds
273message DestroyAttestationIdsRequest {}
274message DestroyAttestationIdsResponse {
275  ErrorCode error_code = 1;
276}
277
278// BeginOperation
279message BeginOperationRequest {
280  KeyPurpose purpose = 1;
281  KeyBlob blob = 2;
282  KeyParameters params = 3;
283  HardwareAuthToken auth_token = 4;
284}
285message BeginOperationResponse {
286  ErrorCode error_code = 1;
287  KeyParameters params = 2;
288  OperationHandle handle = 3;
289  Algorithm algorithm = 4;
290  uint32 key_bits = 5;
291}
292
293// UpdateOperation
294message UpdateOperationRequest {
295  OperationHandle handle = 1;
296  KeyParameters params = 2;
297  bytes input = 3;
298  HardwareAuthToken auth_token = 4;
299  VerificationToken verification_token = 5;
300}
301message UpdateOperationResponse {
302  ErrorCode error_code = 1;
303  uint32 consumed = 2;
304  KeyParameters params = 3;
305  bytes output = 4;
306}
307
308// FinishOperation
309message FinishOperationRequest {
310  OperationHandle handle = 1;
311  KeyParameters params = 2;
312  bytes input = 3;
313  bytes signature = 4;
314  HardwareAuthToken auth_token = 5;
315  VerificationToken verification_token = 6;
316};
317message FinishOperationResponse {
318  ErrorCode error_code = 1;
319  KeyParameters params = 2;
320  bytes output = 3;
321};
322
323// AbortOperation
324message AbortOperationRequest {
325  OperationHandle handle = 1;
326};
327message AbortOperationResponse {
328  ErrorCode error_code = 1;
329};
330
331/*
332 * KM4 messages.
333 */
334
335// ImportWrappedKey
336message ImportWrappedKeyRequest {
337  uint32 key_format = 1;
338  KeyParameters params = 2;
339  bytes rsa_envelope = 3;
340  bytes initialization_vector = 4;   // Fixed sized array.
341  bytes encrypted_import_key = 5;
342  bytes aad = 6;
343  bytes gcm_tag = 7;                 // Fixed sized array.
344  KeyBlob wrapping_key_blob = 8;
345  bytes masking_key = 9;             // Fixed sized array.
346  uint64 creation_time_ms = 10;      // Rough current time (ms since epoch).
347}
348// ImportWrappedKey returns a ImportKeyResponse.
349
350// GetHmacSharingParametersRequest
351message GetHmacSharingParametersRequest {
352}
353message GetHmacSharingParametersResponse {
354  ErrorCode error_code = 1;
355  HmacSharingParameters hmac_sharing_params = 2;
356}
357
358// ComputeSharedHmacRequest
359message ComputeSharedHmacRequest {
360  repeated HmacSharingParameters hmac_sharing_params = 1;
361}
362message ComputeSharedHmacResponse {
363  ErrorCode error_code = 1;
364  bytes sharing_check = 2;
365}
366
367// DeviceLockedRequest
368message DeviceLockedRequest {
369  bool password_only = 1;
370  VerificationToken verification_token = 2;
371}
372message DeviceLockedResponse {
373  ErrorCode error_code = 1;
374}
375
376// DeviceLockedRequest
377message EarlyBootEndedRequest {}
378message EarlyBootEndedResponse {
379  ErrorCode error_code = 1;
380}
381
382/*
383 * Vendor HAL.
384 */
385
386// SetRootOfTrustRequest
387// Only callable by the Bootloader.
388message SetRootOfTrustRequest {
389  bytes digest = 1;                  // This is a SHA256 digest.
390}
391message SetRootOfTrustResponse {
392  // Specified in keymaster_defs.proto:ErrorCode
393  ErrorCode error_code = 1;
394}
395
396// SetBootStateRequest
397// Only callable by the Bootloader.
398message SetBootStateRequest {
399  bool is_unlocked = 1;
400  bytes public_key = 2;              // This is a SHA256 digest.
401  BootColor color = 3;
402  uint32 system_version = 4;         // Deprecated.
403  uint32 system_security_level = 5;  // Patch level of the boot partition.
404  bytes boot_hash = 6;               // This is a SHA256 digest.
405}
406message SetBootStateResponse {
407  // Specified in keymaster_defs.proto:ErrorCode
408  ErrorCode error_code = 1;
409}
410
411// ProvisionDeviceIds
412// Only callable at the Device Factory
413message ProvisionDeviceIdsRequest {
414  bytes product_brand = 1;
415  bytes product_device = 2;
416  bytes product_name = 3;
417  bytes serialno = 4;
418  bytes product_manufacturer = 5;
419  bytes product_model = 6;
420  bytes imei = 7;
421  bytes meid = 8;
422}
423message ProvisionDeviceIdsResponse {
424  // Specified in keymaster_defs.proto:ErrorCode
425  ErrorCode error_code = 1;
426  ChipFusing chip_fusing = 2;
427  bool nodelocked_ro = 3;
428}
429
430// ReadTeeBatchCertificate
431// Only callable at the Device Factory
432message ReadTeeBatchCertificateRequest {
433  Algorithm algorithm = 1;
434}
435message ReadTeeBatchCertificateResponse {
436  ErrorCode error_code = 1;
437  RSAKey rsa = 2;   // rsa or ec set based on request algorithm selector.
438  ECKey ec = 3;
439  bytes batch_cert = 4;
440}
441
442message DTupHandshakeRequest {
443  bytes nonce_client = 1;
444}
445
446message DTupHandshakeResponse {
447  DTupError error_code = 1;
448  bytes nonce_citadel = 2;
449  bytes signature = 3;
450}
451
452message DTupFetchInputEventRequest {}
453
454message DTupFetchInputEventResponse {
455  DTupError error_code = 1;
456  DTupKeyEvent event = 2;
457  bytes signature = 3;
458}
459
460message SetSystemVersionInfoRequest {
461  uint32 system_version = 1;  // getprop "ro.build.version.release"
462  uint32 system_security_level = 2; // getprop "ro.build.version.security_patch"
463  uint32 vendor_security_level = 3; // getprop "ro.vendor.build.security_patch"
464}
465
466message SetSystemVersionInfoResponse {
467  // Specified in keymaster_defs.proto:ErrorCode
468  ErrorCode error_code = 1;
469}
470
471message GetBootInfoRequest {}
472
473message GetBootInfoResponse {
474  ErrorCode error_code = 1;
475  bool is_unlocked = 2;
476  BootColor boot_color = 3;
477  bytes boot_key = 4;               // This is a SHA256 digest.
478  bytes boot_hash = 5;              // This is a SHA256 digest.
479}
480
481message ProvisionPresharedSecretRequest {
482  bytes preshared_secret = 1;
483  bool get_status = 2;
484}
485message ProvisionPresharedSecretResponse {
486  ErrorCode error_code = 1;
487  PresharedSecretStatus status = 2;
488  BootColor color = 3;
489  bytes digest = 4;
490}
491
492message ProvisionCertificatesRequest {
493  uint32 block_number = 1;
494  bytes cert_block = 2;
495  bytes digest = 3;
496}
497message ProvisionCertificatesResponse {
498  ErrorCode error_code = 1;
499  CertificateStatus cert_status = 2;
500}
501
502message ReadCertificateRequest {
503  AttestationSelector selector = 1;
504  Algorithm algorithm = 2;
505}
506message ReadCertificateResponse {
507  ErrorCode error_code = 1;
508  Certificate cert = 2;
509}
510
511message VigoReadVSRequest {}
512message VigoReadVSResponse {
513  ErrorCode error_code = 1;
514  VigoKey vs_key = 2;
515}
516message VigoStartChannelRequest {
517  VigoKey client_key = 1;
518}
519message VigoStartChannelResponse {
520  ErrorCode error_code = 1;
521  VigoKey server_key = 2;
522  VigoSignature channel_signature = 3;
523}
524message VigoStoreSecretRequest {
525  VigoKey rs_key = 1;
526  VigoSecret secret_encrypted = 2;
527}
528message VigoStoreSecretResponse {
529  ErrorCode error_code = 1;
530}
531message VigoReleaseSecretRequest {
532  VigoSignature rs_signature = 1;
533}
534message VigoReleaseSecretResponse {
535  ErrorCode error_code = 1;
536  VigoSecret secret_encrypted = 2;
537}
538
539// IdentityStartAttestKey
540message IdentityStartAttestKeyRequest {
541  bytes pubkey = 1;
542  KeyParameters params = 2;
543  uint32 attestation_app_id_len = 3;
544  AttestationSelector selector = 4;
545  bytes not_before = 5;      // strftime('%y%m%d%H%M%SZ') [15 octects]
546  bytes not_after = 6;       // strftime('%y%m%d%H%M%SZ') [15 octects]
547  uint64 creation_time_ms = 7;      // Rough current time (ms since epoch).
548  bool use_km_attest_key = 8;
549}
550message IdentityStartAttestKeyResponse {
551  ErrorCode error_code = 1;
552  OperationHandle handle = 2;
553  bytes certificate_prologue = 3;
554}
555
556// IdentityFinishAttestKeyRequest
557message IdentityFinishAttestKeyRequest {
558  OperationHandle handle = 1;
559  bool use_km_attest_key = 2;
560}
561message IdentityFinishAttestKeyResponse {
562  ErrorCode error_code = 1;
563  bytes certificate_epilogue = 2;
564  ChipFusing chip_fusing = 3;
565  bool nodelocked_ro = 4;
566}
567