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