1//
2// Copyright (C) 2015 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
17// NOTE: All tpm_manager protobufs are in the same file because the Android
18// build system cannot handle import statements without using Android-specific
19// paths.
20
21option optimize_for = LITE_RUNTIME;
22package tpm_manager;
23
24enum TpmManagerStatus {
25  STATUS_SUCCESS = 0;
26  STATUS_DEVICE_ERROR = 1;
27  STATUS_NOT_AVAILABLE = 2;
28}
29
30// Result codes. For convenience, keep these in sync with Brillo NVRAM HAL
31// values defined in hardware/nvram_defs.h.
32enum NvramResult {
33  NVRAM_RESULT_SUCCESS = 0;
34  // An unexpected TPM error occurred. More information should be in logs.
35  NVRAM_RESULT_DEVICE_ERROR = 1;
36  // The caller is not authorized to perform the requested operation. This may
37  // be due to a bad authorization value or to system state.
38  NVRAM_RESULT_ACCESS_DENIED = 2;
39  NVRAM_RESULT_INVALID_PARAMETER = 3;
40  NVRAM_RESULT_SPACE_DOES_NOT_EXIST = 4;
41  NVRAM_RESULT_SPACE_ALREADY_EXISTS = 5;
42  // This may be because a space is locked or because an operation has been
43  // explicitly disabled.
44  NVRAM_RESULT_OPERATION_DISABLED = 6;
45  // Literally, the TPM is out of non-volatile storage.
46  NVRAM_RESULT_INSUFFICIENT_SPACE = 7;
47  // An error occurred sending the request to the system service.
48  NVRAM_RESULT_IPC_ERROR = 100;
49}
50
51// More background on these attributes can be found by looking up the TPMA_NV_*
52// constants in the TPM 2.0 specification or the TPM_NV_PER_* constants in the
53// TPM 1.2 specification.
54enum NvramSpaceAttribute {
55  // The space can be locked for writing until it is destroyed. Without TPM
56  // owner privilege this is always after the TPM is cleared. This typically
57  // occurs during device factory reset.
58  NVRAM_PERSISTENT_WRITE_LOCK = 0;
59  // The space can be locked for writing until the next boot.
60  NVRAM_BOOT_WRITE_LOCK = 1;
61  // The space can be locked for reading until the next boot.
62  NVRAM_BOOT_READ_LOCK = 2;
63  // The space requires an authorization value for writing.
64  NVRAM_WRITE_AUTHORIZATION = 3;
65  // The space requires an authorization value for reading.
66  NVRAM_READ_AUTHORIZATION = 4;
67  // The space can not be written directly, only extended.
68  // E.g. new_value = HASH(old_value + input)
69  NVRAM_WRITE_EXTEND = 5;
70  // The space is tied to the global lock (bGlobalLock). This global lock is
71  // typically locked early in boot. This is defined for inspecting existing
72  // spaces, this interface cannot be used to define spaces with this attribute.
73  NVRAM_GLOBAL_LOCK = 6;
74  // The space is tied to the platform rather than the TPM owner. The 'platform'
75  // is whatever executes first after boot. Typically this access is locked
76  // early in boot. This is defined for inspecting existing spaces, this
77  // interface cannot be used to define spaces with this attribute.
78  NVRAM_PLATFORM_WRITE = 7;
79  // The space can only be written by the TPM owner. For TPM 2.0 this can be
80  // used only for inspecting existing spaces, not for defining new spaces.
81  NVRAM_OWNER_WRITE = 8;
82  // The space can only be read by the TPM owner. For TPM 2.0 this can be used
83  // only for inspecting existing spaces, not for defining new spaces.
84  NVRAM_OWNER_READ = 9;
85}
86
87enum NvramSpacePolicy {
88  // No policy. Authorization values are still enforced. This is the default.
89  NVRAM_POLICY_NONE = 0;
90  // Bind both read and write access to the current PCR0 value in addition to
91  // enforcing any authorization value.
92  NVRAM_POLICY_PCR0 = 1;
93}
94
95// Tracks the expected policy for a particular NVRAM space.
96message NvramPolicyRecord {
97  optional uint32 index = 1;
98  optional NvramSpacePolicy policy = 2;
99  // This will be true if the NVRAM_READ_AUTHORIZATION attribute was not
100  // specified when the space was created.
101  optional bool world_read_allowed = 3;
102  // This will be true if the NVRAM_WRITE_AUTHORIZATION attribute was not
103  // specified when the space was created.
104  optional bool world_write_allowed = 4;
105  repeated bytes policy_digests = 5;
106}
107
108// The format of persistent local TPM management data stored on the device.
109// When TPM ownership is taken, this protobuf is populated with the passwords
110// used to take ownership, and with a list of clients who have a dependency on
111// the owner password (like Attestation, InstallAttributes and BootLockbox).
112// when all the clients have the owner password injected, this protobuf is
113// cleared of all passwords.
114message LocalData {
115  optional bytes owner_password = 2;
116  repeated string owner_dependency = 3;
117  optional bytes endorsement_password = 4;
118  optional bytes lockout_password = 5;
119  repeated NvramPolicyRecord nvram_policy = 6;
120}
121
122////////////////////////////////////////////////////////////////////////////////
123// A series of request and reply messages for the NVRAM interface methods.
124////////////////////////////////////////////////////////////////////////////////
125message DefineSpaceRequest {
126  optional uint32 index = 1;
127  optional uint32 size = 2;
128  repeated NvramSpaceAttribute attributes = 3;
129  optional bytes authorization_value = 4;
130  optional NvramSpacePolicy policy = 5;
131}
132
133message DefineSpaceReply {
134  optional NvramResult result = 1;
135}
136
137message DestroySpaceRequest {
138  optional uint32 index = 1;
139}
140
141message DestroySpaceReply {
142  optional NvramResult result = 1;
143}
144
145message WriteSpaceRequest {
146  optional uint32 index = 1;
147  optional bytes data = 2;
148  optional bytes authorization_value = 3;
149  optional bool use_owner_authorization = 4;
150}
151
152message WriteSpaceReply {
153  optional NvramResult result = 1;
154}
155
156message ReadSpaceRequest {
157  optional uint32 index = 1;
158  optional bytes authorization_value = 2;
159  optional bool use_owner_authorization = 3;
160}
161
162message ReadSpaceReply {
163  optional NvramResult result = 1;
164  optional bytes data = 2;
165}
166
167message LockSpaceRequest {
168  optional uint32 index = 1;
169  optional bool lock_read = 2;
170  optional bool lock_write = 3;
171  optional bytes authorization_value = 4;
172  optional bool use_owner_authorization = 5;
173}
174
175message LockSpaceReply {
176  optional NvramResult result = 1;
177}
178
179message ListSpacesRequest {
180}
181
182message ListSpacesReply {
183  optional NvramResult result = 1;
184  repeated uint32 index_list = 2;
185}
186
187message GetSpaceInfoRequest {
188  optional uint32 index = 1;
189}
190
191message GetSpaceInfoReply {
192  optional NvramResult result = 1;
193  optional uint32 size = 2;
194  optional bool is_read_locked = 3;
195  optional bool is_write_locked = 4;
196  repeated NvramSpaceAttribute attributes = 5;
197  optional NvramSpacePolicy policy = 6;
198}
199
200////////////////////////////////////////////////////////////////////////////////
201// A series of request and reply messages for the ownership interface methods.
202////////////////////////////////////////////////////////////////////////////////
203message GetTpmStatusRequest {
204}
205
206message GetTpmStatusReply {
207  optional TpmManagerStatus status = 1;
208  // Whether a TPM is enabled on the system.
209  optional bool enabled = 2;
210  // Whether the TPM has been owned.
211  optional bool owned = 3;
212  // Local TPM management data (including the owner password if available).
213  optional LocalData local_data = 4;
214  // The current dictionary attack counter value.
215  optional uint32 dictionary_attack_counter = 5;
216  // The current dictionary attack counter threshold.
217  optional uint32 dictionary_attack_threshold = 6;
218  // Whether the TPM is in some form of dictionary attack lockout.
219  optional bool dictionary_attack_lockout_in_effect = 7;
220  // The number of seconds remaining in the lockout.
221  optional uint32 dictionary_attack_lockout_seconds_remaining = 8;
222}
223
224message TakeOwnershipRequest {
225}
226
227message TakeOwnershipReply {
228  optional TpmManagerStatus status = 1;
229}
230
231message RemoveOwnerDependencyRequest {
232  optional bytes owner_dependency = 1;
233}
234
235message RemoveOwnerDependencyReply {
236  optional TpmManagerStatus status = 1;
237}
238