1// Copyright 2022 Google LLC
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     https://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15syntax = "proto3";
16
17option java_outer_classname = "SecurityProto";
18
19package pandora;
20
21import "google/protobuf/empty.proto";
22import "google/protobuf/wrappers.proto";
23import "pandora/host.proto";
24
25// Service to trigger Bluetooth Host security pairing procedures.
26service Security {
27  // Listen to pairing events.
28  // This is handled independently from connections for several reasons:
29  // - Pairing can be triggered at any time and multiple times during the
30  //   lifetime of a connection (this also explains why this is a stream).
31  // - In BR/EDR, the specification allows for a device to authenticate before
32  //   connecting when in security mode 3 (link level enforced security).
33  rpc OnPairing(stream PairingEventAnswer) returns (stream PairingEvent);
34  // Secure (i.e. authenticate and/or encrypt) a connection with a specific
35  // security level to reach. Pairing events shall be handled through `OnPairing`
36  // if a corresponding stream has been opened prior to this call, otherwise, they
37  // shall be automatically confirmed by the host.
38  // If authentication and/or encryption procedures necessary to reach the
39  // desired security level have already been triggered before (typically as
40  // part of the connection establishment), this shall not trigger them again
41  // and only wait for the desired security level to be reached. If the desired
42  // security level has already been reached, this shall return immediately.
43  // Note: During the entire life of a connection, the security level can only
44  // be upgraded, see `SecurityLevel` and `LESecurityLevel` enumerable for
45  // details about each security level.
46  rpc Secure(SecureRequest) returns (SecureResponse);
47  // Wait for a specific connection security level to be reached. Events may
48  // be streamed through `OnPairing` if running, otherwise the host shall
49  // automatically confirm.
50  rpc WaitSecurity(WaitSecurityRequest) returns (WaitSecurityResponse);
51}
52
53// Service to trigger Bluetooth Host security persistent storage procedures.
54service SecurityStorage {
55  // Return whether or not a bond exists for a connection in the host
56  // persistent storage.
57  rpc IsBonded(IsBondedRequest) returns (google.protobuf.BoolValue);
58  // Remove a bond for a connection, if exists, from the host
59  // persistent storage.
60  rpc DeleteBond(DeleteBondRequest) returns (google.protobuf.Empty);
61}
62
63// BR/EDR pairing security levels.
64enum SecurityLevel {
65  // Level 0, for services with the following attributes:
66  // - Authentication of the remote device not required.
67  // - MITM protection not required.
68  // - No encryption required.
69  // - No user interaction required.
70  //
71  // No security.
72  // Permitted only for SDP and service data sent via either L2CAP fixed
73  // signaling channels or the L2CAP connection-less channel to PSMs that
74  // correspond to service class UUIDs which are allowed to utilize Level 0.
75  LEVEL0 = 0;
76  // Level 1, for services with the following attributes:
77  // - Authentication of the remote device required when encryption is enabled.
78  // - MITM protection not required.
79  // - Encryption not necessary.
80  // - At least 56-bit equivalent strength for encryption key when encryption is
81  //   enabled should be used.
82  // - Minimal user interaction desired.
83  //
84  // Low security level.
85  LEVEL1 = 1;
86  // Level 2, for services with the following attributes:
87  // - Authentication of the remote device required.
88  // - MITM protection not required.
89  // - Encryption required.
90  // - At least 56-bit equivalent strength for encryption key should be used.
91  //
92  // Medium security level.
93  LEVEL2 = 2;
94  // Level 3, for services with the following attributes:
95  // - Authentication of the remote device required.
96  // - MITM protection required.
97  // - Encryption required.
98  // - At least 56-bit equivalent strength for encryption key should be used.
99  // - User interaction acceptable.
100  //
101  // High security.
102  LEVEL3 = 3;
103  // Level 4, for services with the following attributes:
104  // - Authentication of the remote device required.
105  // - MITM protection required.
106  // - Encryption required.
107  // - 128-bit equivalent strength for link and encryption keys required using FIPS
108  //   approved algorithms (E0 not allowed, SAFER+ not allowed, and P-192 not
109  //   allowed; encryption key not shortened).
110  // - User interaction acceptable.
111  //
112  // Highest security level.
113  // Only possible when both devices support Secure Connections.
114  LEVEL4 = 4;
115}
116
117// Low Energy pairing security levels.
118enum LESecurityLevel {
119  // No security (No authentication and no encryption).
120  LE_LEVEL1 = 0;
121  //  Unauthenticated pairing with encryption.
122  LE_LEVEL2 = 1;
123  // Authenticated pairing with encryption.
124  LE_LEVEL3 = 2;
125  // Authenticated LE Secure Connections pairing with encryption using a 128-
126  // bit strength encryption key.
127  LE_LEVEL4 = 3;
128}
129
130message PairingEvent {
131  // Pairing event remote device.
132  oneof remote {
133    // BR/EDR only. Used when a pairing event is received before the connection
134    // being complete: when the remote controller is set in security mode 3,
135    // it shall automatically pair with the remote device before notifying
136    // the host for a connection complete.
137    bytes address = 1;
138    // BR/EDR or Low Energy connection.
139    Connection connection = 2;
140  }
141  // Pairing method used for this pairing event.
142  oneof method {
143    // "Just Works" SSP / LE pairing association
144    // model. Confirmation is automatic.
145    google.protobuf.Empty just_works = 3;
146    // Numeric Comparison SSP / LE pairing association
147    // model. Confirmation is required.
148    uint32 numeric_comparison = 4;
149    // Passkey Entry SSP / LE pairing association model.
150    // Passkey is typed by the user.
151    // Only for LE legacy pairing or on devices without a display.
152    google.protobuf.Empty passkey_entry_request = 5;
153    // Passkey Entry SSP / LE pairing association model.
154    // Passkey is shown to the user.
155    // The peer device receives a Passkey Entry request.
156    uint32 passkey_entry_notification = 6;
157    // Legacy PIN Pairing.
158    // A PIN Code is typed by the user on IUT.
159    google.protobuf.Empty pin_code_request = 7;
160    // Legacy PIN Pairing.
161    // We generate a PIN code, and the user enters it in the peer
162    // device. While this is not part of the specification, some display
163    // devices automatically generate their PIN Code, instead of asking the
164    // user to type it.
165    bytes pin_code_notification = 8;
166  }
167}
168
169message PairingEventAnswer {
170  // Received pairing event.
171  PairingEvent event = 1;
172  // Answer when needed to the pairing event method.
173  oneof answer {
174    // Numeric Comparison confirmation.
175    // Used when pairing event method is `numeric_comparison` or `just_works`.
176    bool confirm = 2;
177    // Passkey typed by the user.
178    // Used when pairing event method is `passkey_entry_request`.
179    uint32 passkey = 3;
180    // Pin typed by the user.
181    // Used when pairing event method is `pin_code_request`.
182    bytes pin = 4;
183  };
184}
185
186// Request of the `Secure` method.
187message SecureRequest {
188  // Peer connection to secure.
189  Connection connection = 1;
190  // Security level to wait for.
191  oneof level {
192    // BR/EDR (classic) level.
193    SecurityLevel classic = 2;
194    // Low Energy level.
195    LESecurityLevel le = 3;
196  }
197}
198
199// Response of the `Secure` method.
200message SecureResponse {
201  // Response result.
202  oneof result {
203    // `Secure` completed successfully.
204    google.protobuf.Empty success = 1;
205    // `Secure` was unable to reach the desired security level.
206    google.protobuf.Empty not_reached = 2;
207    // Connection died before completion.
208    google.protobuf.Empty connection_died = 3;
209    // Pairing failure error.
210    google.protobuf.Empty pairing_failure = 4;
211    // Authentication failure error.
212    google.protobuf.Empty authentication_failure = 5;
213    // Encryption failure error.
214    google.protobuf.Empty encryption_failure = 6;
215  }
216}
217
218// Request of the `WaitSecurity` method.
219message WaitSecurityRequest {
220  // Peer connection to wait security level to be reached.
221  Connection connection = 1;
222  // Security level to wait for.
223  oneof level {
224    // BR/EDR (classic) level.
225    SecurityLevel classic = 2;
226    // Low Energy level.
227    LESecurityLevel le = 3;
228  }
229}
230
231// Response of the `WaitSecurity` method.
232message WaitSecurityResponse {
233  // Response result.
234  oneof result {
235    // `WaitSecurity` completed successfully.
236    google.protobuf.Empty success = 1;
237    // Connection died before completion.
238    google.protobuf.Empty connection_died = 2;
239    // Pairing failure error.
240    google.protobuf.Empty pairing_failure = 3;
241    // Authentication failure error.
242    google.protobuf.Empty authentication_failure = 4;
243    // Encryption failure error.
244    google.protobuf.Empty encryption_failure = 5;
245  }
246}
247
248// Request of the `IsBonded` method.
249message IsBondedRequest {
250  oneof address {
251    // Public device address.
252    bytes public = 1;
253    // Random device address.
254    bytes random = 2;
255  }
256}
257
258// Request of the `DeleteBond` method.
259message DeleteBondRequest {
260  oneof address {
261    // Public device address.
262    bytes public = 1;
263    // Random device address.
264    bytes random = 2;
265  }
266}
267