Skip to content

Commit 35207be

Browse files
touilleMantouilleMan
committed
Add RFC 1029: Advisory device protection
1 parent 3ce59a7 commit 35207be

1 file changed

Lines changed: 157 additions & 0 deletions

File tree

‎docs/rfcs/1029-advisory-device-protection.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
<!-- Parsec Cloud (https://parsec.cloud) Copyright (c) BUSL-1.1 2016-present Scille SAS -->
2+
3+
# Advisory device protection
4+
5+
## 1 - Goals
6+
7+
This RFC introduces a mechanism for the Parsec server to provide a recommended
8+
device protection configuration to clients.
9+
10+
This allows a server administrator to specify that local devices should be protected
11+
using specific strategies (e.g. PKI, or password + TOTP), guiding the client towards
12+
security policies.
13+
14+
> [!IMPORTANT]
15+
>
16+
> This configuration is **purely advisory**: the server cannot enforce it because
17+
> the local device keys file is encrypted entirely client-side. The server never sees
18+
> the cleartext device keys and has no way to verify which protection strategy was
19+
> actually used.
20+
21+
## 2 - Overview
22+
23+
### 2.1 - Client workflow
24+
25+
1. The client requests the server for config via the anonymous server API `server_config`.
26+
2. **If no answer** (e.g. the server is unreachable / offline): a default config is
27+
used that allows all protection strategies (i.e. no restriction). This ensures
28+
the client can still operate offline.
29+
3. **If an answer is received**: the advisory protection config is used to:
30+
- Prioritize the recommended protection strategies during device creation.
31+
- At login time, compare the current device's protection strategy against the
32+
advisory config. If the current strategy is not in the recommended set, a
33+
dialogue is displayed to the user suggesting they change their device protection.
34+
35+
```mermaid
36+
flowchart TD
37+
A[Client start] --> B[server_config request]
38+
B -- offline --> C[Use default: all strategies allowed]
39+
B -- online --> D[Use server-provided advisory config]
40+
C --> E[Proceed to device auth/create]
41+
D --> E
42+
```
43+
44+
### 2.2 - Device protection formats
45+
46+
The following local device protection strategies exist in Parsec:
47+
48+
| Strategy | Description | Offline login | Offline attack resistance |
49+
|----------------|------------------------------------------------------|:-------------:|:-------------------------:|
50+
| Password | Derived key from user-provided password | ✅ | Moderate (key stretching) |
51+
| Keyring | OS-level credential store (Keychain, Secret Service) | ✅ | Low (tied to OS session) |
52+
| PKI | Smartcard / X.509 certificate | ✅ | High |
53+
| OpenBao | SSO-based key retrieval via OpenBao | ❌ | High |
54+
| Account Vault | Key stored in Parsec account vault on server | ❌ | High |
55+
56+
On top of any of these, TOTP can be layered as a secondary protection
57+
(see [RFC 1025]) which adds server involvement at login time (and thus removes
58+
offline login capability but increases offline attack resistance).
59+
60+
The advisory configuration specifies which **combinations** of primary strategy
61+
(+ optional TOTP) are acceptable.
62+
63+
To keep the protocol simple and forward-compatible, each acceptable combination is
64+
serialized as a canonical string identifier such as `PASSWORD`, `PASSWORD+TOTP`,
65+
`PKI` or `PKI+TOTP`.
66+
67+
## 3 - Protocol
68+
69+
### 3.1 - New `AdvisoryDeviceFileProtection`
70+
71+
To keep the protocol forward-compatible, each device protection is serialized as a
72+
canonical string in `server_config`.
73+
This way the client can simply ignore an unknown one instead of rejecting the entire
74+
`server_config` response.
75+
76+
Canonical values initially defined by this RFC are:
77+
78+
- `PASSWORD`
79+
- `PASSWORD+TOTP`
80+
- `KEYRING`
81+
- `KEYRING+TOTP`
82+
- `PKI`
83+
- `PKI+TOTP`
84+
- `OPENBAO`
85+
- `OPENBAO+TOTP`
86+
- `ACCOUNT_VAULT`
87+
- `ACCOUNT_VAULT+TOTP`
88+
89+
Deserialization is done by the new type `AdvisoryDeviceFileProtection`
90+
91+
```rust
92+
93+
enum AdvisoryDeviceFilePrimaryProtection {
94+
Password,
95+
Keyring,
96+
PKI,
97+
OpenBao,
98+
AccountVault,
99+
}
100+
101+
struct AdvisoryDeviceFileProtection {
102+
primary: AdvisoryDeviceFilePrimaryProtection,
103+
with_totp: bool,
104+
}
105+
```
106+
107+
### 3.2 - Updated `server_config` schema
108+
109+
```json5
110+
[
111+
{
112+
"major_versions": [
113+
5
114+
],
115+
"cmd": "server_config",
116+
"req": {},
117+
"reps": [
118+
{
119+
"status": "ok",
120+
"fields": [
121+
// ...
122+
{
123+
// Advisory configuration for local device protection (e.g.
124+
// `["PASSWORD+TOTP", "PKI"]`).
125+
//
126+
// Each entry is a serialized `AdvisoryDeviceFileProtection`
127+
// (this way unknown values can simply be ignored by the client).
128+
//
129+
// Missing field or empty list means no recommendation.
130+
"introduced_in": "5.5",
131+
"name": "advisory_device_file_protection",
132+
"type": "List<String>"
133+
}
134+
]
135+
}
136+
],
137+
"nested_types": [
138+
// ... (existing nested types unchanged) ...
139+
]
140+
}
141+
]
142+
```
143+
144+
### 3.3 - Server CLI changes
145+
146+
New CLI flags for `parsec run` to configure the advisory device protection:
147+
148+
```bash
149+
--device-protection-strategy <STRATEGY>...
150+
```
151+
152+
Where `<STRATEGY>` is one of the canonical identifiers defined above.
153+
154+
When no `--device-protection-strategy` is specified, the default is an empty
155+
recommendation list (all strategies are accepted).
156+
157+
[RFC 1025]: ./1025-totp-protected-local-device.md

0 commit comments

Comments
 (0)