Marco Ricci commited on 2024-12-25 20:55:45
Zeige 4 geänderte Dateien mit 968 Einfügungen und 82 Löschungen.
The barebones HTML "manpage" for `derivepassphrase` was essentially an HTML-ized version of the help text. In particular, the option descriptions only contained the one-line help text, and many typical sections (FILES, ENVIRONMENT, EXAMPLES, DIAGNOSTICS, AUTHOR, BUGS) were missing. This commit contributes a proper manpage, in `*roff`/`mdoc` format. It was authored using guidance from the `groff_mdoc` documentation, the only sensible-appearing authoritative source on manpage style issues. (Perl's `perlpodstyle`, `groff_man` and `groff_man_style` were also consulted, but ultimately disregarded.) The content changes were also folded back into the HTML version, save for some styling choices that aren't possible in the `*roff` version. In particular, both versions are hand-written, and manually synchronized with each other. The manpages use the option group headings "Passphrase generation" and "Compatibility and extension options" instead of "Password generation" and "Options concerning compatibility with other tools", for better text flow. Accordingly, this phrasing has been adapted in `derivepassphrase_vault` as well.
... | ... |
@@ -0,0 +1,722 @@ |
1 |
+.Dd 2024-12-25 |
|
2 |
+.Dt DERIVEPASSPHRASE-VAULT 1 |
|
3 |
+.Os derivepassphrase 0.4.0 |
|
4 |
+. |
|
5 |
+.Sh NAME |
|
6 |
+. |
|
7 |
+.Nm derivepassphrase-vault |
|
8 |
+.Nd derive a passphrase using the vault derivation scheme |
|
9 |
+. |
|
10 |
+.Sh SYNOPSIS |
|
11 |
+. |
|
12 |
+.Bd -ragged |
|
13 |
+.Nm derivepassphrase vault |
|
14 |
+.Op Fl \-phrase | Fl \-key |
|
15 |
+.Op Fl \-length Ar n |
|
16 |
+.Op Fl \-repeat Ar n |
|
17 |
+.Op Fl \-lower Ar n |
|
18 |
+.Op Fl \-upper Ar n |
|
19 |
+.Op Fl \-number Ar n |
|
20 |
+.Op Fl \-space Ar n |
|
21 |
+.Op Fl \-dash Ar n |
|
22 |
+.Op Fl \-symbol Ar n |
|
23 |
+.Ar SERVICE |
|
24 |
+. |
|
25 |
+.Nm derivepassphrase vault |
|
26 |
+.Brq Fl \-phrase | \-key | No .\|.\|. | Fl \-symbol Ar n |
|
27 |
+.No .\|.\|. |
|
28 |
+.Fl \-config |
|
29 |
+.Op Fl \-unset Ar setting No .\|.\|. |
|
30 |
+.Op Fl \-overwrite\-existing | Fl \-merge\-existing |
|
31 |
+.Op Ar SERVICE |
|
32 |
+. |
|
33 |
+.Nm derivepassphrase vault |
|
34 |
+.Bro |
|
35 |
+.Fl \-notes |
|
36 |
+.Ar SERVICE |
|
37 |
+| |
|
38 |
+.Fl \-delete |
|
39 |
+.Ar SERVICE |
|
40 |
+| |
|
41 |
+.Fl \-delete\-globals |
|
42 |
+| |
|
43 |
+.Fl \-clear |
|
44 |
+.Brc |
|
45 |
+. |
|
46 |
+.Nm derivepassphrase vault |
|
47 |
+.Op Fl \-export\-as Brq Li json | sh |
|
48 |
+.Brq Fl \-import Ar PATH | Fl \-export Ar PATH |
|
49 |
+.Ed |
|
50 |
+. |
|
51 |
+.Sh DESCRIPTION |
|
52 |
+. |
|
53 |
+Using a master passphrase or a master |
|
54 |
+.Tn SSH |
|
55 |
+key, derive a passphrase for |
|
56 |
+.Ar SERVICE , |
|
57 |
+subject to length, character and character repetition constraints, in a |
|
58 |
+manner compatible with James Coglan's |
|
59 |
+.Xr vault 1 . |
|
60 |
+.Pp |
|
61 |
+. |
|
62 |
+The derivation is cryptographically strong, meaning that even if a single |
|
63 |
+passphrase is compromised, guessing the master passphrase or a different |
|
64 |
+service's passphrase is computationally infeasible. |
|
65 |
+The derivation is also deterministic, given the same inputs, thus the |
|
66 |
+resulting passphrase need not be stored explicitly. |
|
67 |
+.Pp |
|
68 |
+. |
|
69 |
+The service name and constraints themselves also need not be kept secret; |
|
70 |
+the latter are usually stored in a world-readable file. |
|
71 |
+. |
|
72 |
+.Sh OPTIONS |
|
73 |
+. |
|
74 |
+.Ss Passphrase generation |
|
75 |
+. |
|
76 |
+The passphrase generation options can be divided into |
|
77 |
+.Dq passphrase source |
|
78 |
+options |
|
79 |
+.Fl ( \-phrase , \-key ) |
|
80 |
+and |
|
81 |
+.Dq passphrase constraint |
|
82 |
+options (all others). |
|
83 |
+The passphrase source options are mutually exclusive \(em you may only |
|
84 |
+specify one of them \(em while the passphrase constraint options may be |
|
85 |
+combined in any way. |
|
86 |
+The |
|
87 |
+.Ar SERVICE |
|
88 |
+is mandatory (see synopsis\~#1), unless the |
|
89 |
+.Fl \-config |
|
90 |
+option is specified (see synopsis\~#2). |
|
91 |
+All character constraints refer to ASCII printable characters only (space |
|
92 |
+.Pq Li U+0020 |
|
93 |
+to tilde |
|
94 |
+.Pq Li U+007E , |
|
95 |
+excluding the grave accent |
|
96 |
+.Pq Li U+0060 ) . |
|
97 |
+. |
|
98 |
+.Bl -tag -width ".Fl p , \-phrase" |
|
99 |
+. |
|
100 |
+.It Fl p , \-phrase |
|
101 |
+Prompt for a passphrase. |
|
102 |
+.Pp |
|
103 |
+. |
|
104 |
+See also |
|
105 |
+.Sx Configuration |
|
106 |
+for how this interacts with a stored passphrase or |
|
107 |
+.Tn SSH |
|
108 |
+key. |
|
109 |
+. |
|
110 |
+.It Fl k , \-key |
|
111 |
+Select an SSH key. |
|
112 |
+.Pp |
|
113 |
+. |
|
114 |
+An SSH agent such as OpenSSH's |
|
115 |
+.Xr ssh-agent 1 |
|
116 |
+or PuTTY's |
|
117 |
+.Xr pageant 1 |
|
118 |
+must be running and accessible, and have the desired key loaded. |
|
119 |
+The SSH key must also be |
|
120 |
+.Em suitable |
|
121 |
+for this purpose; see |
|
122 |
+.Sx SSH key suitability |
|
123 |
+for details. |
|
124 |
+.Pp |
|
125 |
+. |
|
126 |
+See also |
|
127 |
+.Sx Configuration |
|
128 |
+for how this interacts with a stored passphrase or |
|
129 |
+.Tn SSH |
|
130 |
+key. |
|
131 |
+. |
|
132 |
+.It Fl l Ar n , Fl \-length Ar n |
|
133 |
+Force the passphrase to have the length |
|
134 |
+.Ar n . |
|
135 |
+Defaults to the length |
|
136 |
+.Sy 20 |
|
137 |
+if not specified, or if explicitly specified as |
|
138 |
+.Li 0 . |
|
139 |
+. |
|
140 |
+.It Fl r Ar n , Fl \-repeat Ar n |
|
141 |
+Permit only runs of up to |
|
142 |
+.Ar n |
|
143 |
+consecutive occurrences of the same character. |
|
144 |
+Alternatively, forbid immediate additional repetitions of length |
|
145 |
+.Ar n |
|
146 |
+(or more) for any character in the derived passphrase. |
|
147 |
+Setting |
|
148 |
+.Ar n No = Li 0 |
|
149 |
+disables repetition constraints, which is the default. |
|
150 |
+. |
|
151 |
+.It Fl \-lower Ar n |
|
152 |
+Include at least |
|
153 |
+.Ar n |
|
154 |
+lowercase characters in the derived passphrase. |
|
155 |
+Setting |
|
156 |
+.Ar n No = Li 0 |
|
157 |
+forbids these characters entirely. |
|
158 |
+The default is to not constain the occurrences in any manner. |
|
159 |
+. |
|
160 |
+.It Fl \-upper Ar n |
|
161 |
+Include at least |
|
162 |
+.Ar n |
|
163 |
+uppercase characters in the derived passphrase. |
|
164 |
+Setting |
|
165 |
+.Ar n No = Li 0 |
|
166 |
+forbids these characters entirely. |
|
167 |
+The default is to not constain the occurrences in any manner. |
|
168 |
+. |
|
169 |
+.It Fl \-number Ar n |
|
170 |
+Include at least |
|
171 |
+.Ar n |
|
172 |
+digits in the derived passphrase. |
|
173 |
+Setting |
|
174 |
+.Ar n No = Li 0 |
|
175 |
+forbids these characters entirely. |
|
176 |
+The default is to not constain the occurrences in any manner. |
|
177 |
+. |
|
178 |
+.It Fl \-space Ar n |
|
179 |
+Include at least |
|
180 |
+.Ar n |
|
181 |
+spaces in the derived passphrase. |
|
182 |
+Setting |
|
183 |
+.Ar n No = Li 0 |
|
184 |
+forbids these characters entirely. |
|
185 |
+The default is to not constain the occurrences in any manner. |
|
186 |
+. |
|
187 |
+.It Fl \-dash Ar n |
|
188 |
+Include at least |
|
189 |
+.Ar n |
|
190 |
+.Dq dashes |
|
191 |
+.Li ( \- |
|
192 |
+or |
|
193 |
+.Li _ ) |
|
194 |
+in the derived passphrase. |
|
195 |
+Setting |
|
196 |
+.Ar n No = Li 0 |
|
197 |
+forbids these characters entirely. |
|
198 |
+The default is to not constain the occurrences in any manner. |
|
199 |
+. |
|
200 |
+.It Fl \-symbol Ar n |
|
201 |
+Include at least |
|
202 |
+.Ar n |
|
203 |
+symbols (any of |
|
204 |
+.Li !\[dq]#$%&\[aq]()*+,./:;<=>?@[\e]\(ha{|}\(ti\-_ ) |
|
205 |
+in the derived passphrase. |
|
206 |
+Setting |
|
207 |
+.Ar n No = Li 0 |
|
208 |
+forbids these characters entirely, and effectively also implies |
|
209 |
+.Fl \-dash Li 0 . |
|
210 |
+The default is to not constain the occurrences in any manner. |
|
211 |
+. |
|
212 |
+.El |
|
213 |
+. |
|
214 |
+.Ss Configuration |
|
215 |
+. |
|
216 |
+The configuration options directly modify the stored settings: default |
|
217 |
+settings, known services, and service-specific settings. |
|
218 |
+They are mutually exclusive; you may only specify one of them. |
|
219 |
+The |
|
220 |
+.Ar SERVICE |
|
221 |
+is mandatory for |
|
222 |
+.Fl \-notes |
|
223 |
+and |
|
224 |
+.Fl \-delete , |
|
225 |
+optional for |
|
226 |
+.Fl \-config , |
|
227 |
+and forbidden for |
|
228 |
+.Fl \-delete\-globals |
|
229 |
+and |
|
230 |
+.Fl \-clear |
|
231 |
+(see synopsis\~#2 and synopsis\~#3). |
|
232 |
+. |
|
233 |
+.Bl -tag -width ".Fl p , \-phrase" |
|
234 |
+. |
|
235 |
+.It Fl n , \-notes |
|
236 |
+Spawn an editor to edit notes for |
|
237 |
+.Ar SERVICE . |
|
238 |
+Use the |
|
239 |
+.Ev VISUAL |
|
240 |
+or |
|
241 |
+.Ev EDITOR |
|
242 |
+environment variables to configure the spawned editor. |
|
243 |
+. |
|
244 |
+.It Fl c , \-config |
|
245 |
+Save the given settings for |
|
246 |
+.Ar SERVICE |
|
247 |
+(if given), or save the given settings as global default settings. |
|
248 |
+.Pp |
|
249 |
+. |
|
250 |
+See the |
|
251 |
+.Sx Passphrase generation |
|
252 |
+and |
|
253 |
+.Sx Compatibility and extension options |
|
254 |
+sections for other options compatible with |
|
255 |
+.Fl \-config . |
|
256 |
+.Pp |
|
257 |
+. |
|
258 |
+.Bf -symbolic |
|
259 |
+Do not use the |
|
260 |
+.Fl \-phrase |
|
261 |
+and |
|
262 |
+.Fl \-config |
|
263 |
+options together! |
|
264 |
+The configuration file is assumed to not contain sensitive contents, and is |
|
265 |
+not encrypted. |
|
266 |
+.Ef |
|
267 |
+. |
|
268 |
+.It Fl x , \-delete |
|
269 |
+Delete all stored settings for |
|
270 |
+.Ar SERVICE . |
|
271 |
+. |
|
272 |
+.It Fl \-delete\-globals |
|
273 |
+Delete all stored global default settings. |
|
274 |
+. |
|
275 |
+.It Fl X , \-clear |
|
276 |
+Delete all stored settings. |
|
277 |
+. |
|
278 |
+.El |
|
279 |
+. |
|
280 |
+.Ss Storage management |
|
281 |
+. |
|
282 |
+The storage management options deal with importing and exporting the stored |
|
283 |
+settings. |
|
284 |
+They are mutually exclusive; you may only specify one of them. |
|
285 |
+Using |
|
286 |
+.Li \- |
|
287 |
+as |
|
288 |
+.Ar PATH |
|
289 |
+for standard input/standard output is supported. |
|
290 |
+. |
|
291 |
+.Bl -tag -width ".Fl p , \-phrase" |
|
292 |
+. |
|
293 |
+.It Fl e Ar PATH , Fl \-export Ar PATH |
|
294 |
+Export all saved settings into file |
|
295 |
+.Ar PATH . |
|
296 |
+. |
|
297 |
+.It Fl i Ar PATH , Fl \-import Ar PATH |
|
298 |
+Import saved settings from file |
|
299 |
+.Ar PATH . |
|
300 |
+. |
|
301 |
+.El |
|
302 |
+. |
|
303 |
+.Ss Compatibility and extension options |
|
304 |
+. |
|
305 |
+By default, |
|
306 |
+.Nm derivepassphrase vault |
|
307 |
+behaves in a manner compatible with |
|
308 |
+.Xr vault 1 . |
|
309 |
+The compatibility and extension options modify the behavior to enable |
|
310 |
+additional functionality, or specifically to force compatibility. |
|
311 |
+.Pp |
|
312 |
+. |
|
313 |
+.Xr vault 1 |
|
314 |
+supports none of these options, and behaves as if the option had not been |
|
315 |
+given or had been left in its default state. |
|
316 |
+. |
|
317 |
+.Bl -tag -width ".Fl p , \-phrase" |
|
318 |
+. |
|
319 |
+.It Fl \-overwrite\-existing No "" / "" Fl \-merge\-existing |
|
320 |
+When importing a configuration via |
|
321 |
+.Fl \-import , |
|
322 |
+or configuring the settings via |
|
323 |
+.Fl \-config , |
|
324 |
+overwrite or merge |
|
325 |
+.Em ( default ) |
|
326 |
+the existing configuration. |
|
327 |
+.Pp |
|
328 |
+. |
|
329 |
+If overwriting the configuration, then the whole configuration |
|
330 |
+.Pq for Fl \-import |
|
331 |
+or the respective section |
|
332 |
+.Pq service-specific or global, for Fl \-config , |
|
333 |
+will be written from scratch. |
|
334 |
+If merging, then each section |
|
335 |
+.Pq service-specific or global, for Fl \-import |
|
336 |
+or each singular setting |
|
337 |
+.Pq for Fl \-config |
|
338 |
+will be overwritten, but other unaffected settings/sections will not. |
|
339 |
+.Pp |
|
340 |
+. |
|
341 |
+.Xr ( vault 1 |
|
342 |
+behaves as if |
|
343 |
+.Fl \-merge\-existing |
|
344 |
+were always given.) |
|
345 |
+. |
|
346 |
+.It Fl \-unset Ar setting |
|
347 |
+When configuring via |
|
348 |
+.Fl \-config , |
|
349 |
+also unset the specified |
|
350 |
+.Ar setting , |
|
351 |
+where |
|
352 |
+.Ar setting |
|
353 |
+is one of the passphrase generation settings |
|
354 |
+.Pq Li phrase , key , lower , No .\|.\|. . |
|
355 |
+May be specified multiple times. |
|
356 |
+Must not overlap with any of the settings being set afterwards. |
|
357 |
+.Pp |
|
358 |
+. |
|
359 |
+.Xr ( vault 1 |
|
360 |
+does not support this option.) |
|
361 |
+. |
|
362 |
+.It Fl \-export\-as Brq Li json | sh |
|
363 |
+When exporting the configuration via |
|
364 |
+.Fl \-export , |
|
365 |
+export as |
|
366 |
+.Tn JSON |
|
367 |
+(default) or as a shell script in |
|
368 |
+.Xr sh 1 |
|
369 |
+format. |
|
370 |
+.Pp |
|
371 |
+. |
|
372 |
+The |
|
373 |
+.Tn JSON |
|
374 |
+format is compatible with |
|
375 |
+.Xr vault 1 . |
|
376 |
+For the shell script format, see the |
|
377 |
+.Sx SHELL SCRIPT EXPORT FORMAT |
|
378 |
+section for details. |
|
379 |
+.Pp |
|
380 |
+. |
|
381 |
+.Xr ( vault 1 |
|
382 |
+behaves as if |
|
383 |
+.Fl \-export\-as Li json |
|
384 |
+were always given.) |
|
385 |
+. |
|
386 |
+.El |
|
387 |
+. |
|
388 |
+.Ss Other options |
|
389 |
+. |
|
390 |
+.Bl -tag -width ".Fl p , \-phrase" |
|
391 |
+. |
|
392 |
+.It Fl \-version |
|
393 |
+Show the version and exit. |
|
394 |
+. |
|
395 |
+.It Fl h , \-help |
|
396 |
+Show a help message and exit. |
|
397 |
+. |
|
398 |
+.El |
|
399 |
+. |
|
400 |
+.Sh SHELL SCRIPT EXPORT FORMAT |
|
401 |
+. |
|
402 |
+If the shell script export format is selected, the configuration will be |
|
403 |
+exported as a |
|
404 |
+.Tn POSIX |
|
405 |
+.Xr sh 1 |
|
406 |
+script, containing calls to |
|
407 |
+.Nm derivepassphrase vault |
|
408 |
+to reconstruct the current configuration from scratch. |
|
409 |
+The script assumes a conforming |
|
410 |
+.Xr sh 1 , |
|
411 |
+with support for |
|
412 |
+.Dq here |
|
413 |
+documents. |
|
414 |
+.Pp |
|
415 |
+. |
|
416 |
+.Bf -symbolic |
|
417 |
+Do not run these emitted shell scripts directly without double-checking |
|
418 |
+their output first! |
|
419 |
+.Ef |
|
420 |
+. |
|
421 |
+.Sh SSH KEY SUITABILITY |
|
422 |
+. |
|
423 |
+An |
|
424 |
+.Tn SSH |
|
425 |
+key is |
|
426 |
+.Sy suitable |
|
427 |
+for use with |
|
428 |
+.Nm derivepassphrase vault |
|
429 |
+if the |
|
430 |
+.Tn SSH |
|
431 |
+agent guarantees that signatures produced with this key will be |
|
432 |
+.Em deterministic , |
|
433 |
+given the same message to be signed. |
|
434 |
+This is a property specific to the key |
|
435 |
+.Em type , |
|
436 |
+and sometimes the agent used: |
|
437 |
+. |
|
438 |
+.Bl -bullet |
|
439 |
+. |
|
440 |
+.It |
|
441 |
+.Tn RSA , |
|
442 |
+Ed25519 and Ed448 keys are always suitable. |
|
443 |
+.Tn OpenSSH Ns No 's |
|
444 |
+.Xr ssh-agent 1 |
|
445 |
+supports only these keys as suitable keys. |
|
446 |
+. |
|
447 |
+.It |
|
448 |
+.Tn DSA |
|
449 |
+and |
|
450 |
+.Tn ECDSA |
|
451 |
+keys are suitable if the |
|
452 |
+.Tn SSH |
|
453 |
+agent supports deterministic |
|
454 |
+.Tn DSA |
|
455 |
+signatures, e.g. by implementing |
|
456 |
+.Tn RFC 6979 . |
|
457 |
+.Tn PuTTY Ns No 's |
|
458 |
+.Xr pageant 1 |
|
459 |
+supports this, in addition to the always-suitable keys mentioned above. |
|
460 |
+. |
|
461 |
+.El |
|
462 |
+. |
|
463 |
+.Sh ENVIRONMENT |
|
464 |
+. |
|
465 |
+.Bl -tag -width ".Fl p , \-phrase" |
|
466 |
+. |
|
467 |
+.It Ev VISUAL , EDITOR |
|
468 |
+.Nm derivepassphrase vault |
|
469 |
+uses this editor to edit service notes when called with |
|
470 |
+.Fl \-notes . |
|
471 |
+.Ev VISUAL |
|
472 |
+has higher precedence than |
|
473 |
+.Ev EDITOR . |
|
474 |
+. |
|
475 |
+.It Ev DERIVEPASSPHRASE_PATH |
|
476 |
+.Nm derivepassphrase |
|
477 |
+stores its configuration files and data in this directory. |
|
478 |
+Defaults to |
|
479 |
+.Pa \(ti/.derivepassphrase . |
|
480 |
+. |
|
481 |
+.El |
|
482 |
+. |
|
483 |
+.Sh FILES |
|
484 |
+. |
|
485 |
+.Bl -tag -width ".Fl p , \-phrase" |
|
486 |
+. |
|
487 |
+.It Ev $DERIVEPASSPHRASE_PATH Ns Pa /vault.json |
|
488 |
+The stored configuration for |
|
489 |
+.Nm derivepassphrase vault : |
|
490 |
+the default passphrase generation settings, the known service names, and the |
|
491 |
+service-specific settings. |
|
492 |
+This file is |
|
493 |
+.Em not |
|
494 |
+intended for the user to edit. |
|
495 |
+. |
|
496 |
+.El |
|
497 |
+. |
|
498 |
+.Sh SECURITY |
|
499 |
+. |
|
500 |
+.Bl -bullet |
|
501 |
+. |
|
502 |
+.It |
|
503 |
+There is |
|
504 |
+.Sy no way |
|
505 |
+to retrieve the generated passphrases if the master passphrase, the SSH key, |
|
506 |
+or the exact passphrase settings are lost, short of trying out all possible |
|
507 |
+combinations. |
|
508 |
+You are |
|
509 |
+.Sy strongly |
|
510 |
+advised to keep independent backups of the settings and the |
|
511 |
+.Tn SSH |
|
512 |
+key, if any. |
|
513 |
+. |
|
514 |
+.It |
|
515 |
+The configuration is |
|
516 |
+.Sy not |
|
517 |
+encrypted, and you are |
|
518 |
+.Sy strongly |
|
519 |
+discouraged from using a stored passphrase. |
|
520 |
+. |
|
521 |
+.It |
|
522 |
+You are |
|
523 |
+.Sy strongly |
|
524 |
+advised to avoid the |
|
525 |
+.Pq shell script |
|
526 |
+configuration export format if possible, and use the JSON format instead. |
|
527 |
+If you |
|
528 |
+.Em must |
|
529 |
+use the shell script format, then |
|
530 |
+.Sy always |
|
531 |
+validate the export before attempting to interpret or run it. |
|
532 |
+. |
|
533 |
+.El |
|
534 |
+. |
|
535 |
+.Sh EXAMPLES |
|
536 |
+. |
|
537 |
+.Dl $ derivepassphrase vault \-\-phrase email |
|
538 |
+.Pp |
|
539 |
+Prompt for a master passphrase, then generate a standard passphrase |
|
540 |
+.Pq length 20, no character or repetition constraints |
|
541 |
+for the |
|
542 |
+.Dq email |
|
543 |
+service. |
|
544 |
+.Pp |
|
545 |
+. |
|
546 |
+.Dl $ derivepassphrase vault \-\-key \-\-upper 9 \-\-lower 9 example.com |
|
547 |
+.Pp |
|
548 |
+. |
|
549 |
+Select an |
|
550 |
+.Tn SSH |
|
551 |
+key from the available suitable |
|
552 |
+.Tn SSH |
|
553 |
+keys in the running |
|
554 |
+.Tn SSH |
|
555 |
+agent, then generate a passphrase for the |
|
556 |
+.Li example.com |
|
557 |
+service using the previously selected |
|
558 |
+.Tn SSH |
|
559 |
+key. |
|
560 |
+The passphrase will have (standard) length 20, and at least nine characters |
|
561 |
+will be uppercase characters and at least another nine characters will be |
|
562 |
+lowercase characters. |
|
563 |
+.Pp |
|
564 |
+. |
|
565 |
+.Dl $ derivepassphrase vault \-\-key \-\-upper 9 \-\-lower 9 \-\-number 9 example.com |
|
566 |
+.Pp |
|
567 |
+. |
|
568 |
+Attempt to generate a passphrase as in the previous example. |
|
569 |
+.Em This |
|
570 |
+example will error out, because the passphrase constraints require at least |
|
571 |
+27 characters and the standard passphrase length 20 cannot accomodate this. |
|
572 |
+.Pp |
|
573 |
+. |
|
574 |
+.Dl $ derivepassphrase vault \-\-key \-\-upper 9 \-\-lower 9 \-\-space 2 \-\-config |
|
575 |
+.Pp |
|
576 |
+. |
|
577 |
+After selecting an |
|
578 |
+.Tn SSH |
|
579 |
+key, configure the default settings to use exactly nine uppercase characters, |
|
580 |
+nine lowercase characters, and two spaces for each generated passphrase. |
|
581 |
+(The specific service settings, or the command-line invocation, can still |
|
582 |
+override these settings.) |
|
583 |
+.Pp |
|
584 |
+. |
|
585 |
+.Dl $ derivepassphrase vault example.com |
|
586 |
+.Pp |
|
587 |
+. |
|
588 |
+Because of the previous setting, the generated passphrase for the |
|
589 |
+.Li example.com |
|
590 |
+service will behave as if |
|
591 |
+.Fl \-key \-upper Li 9 Fl \-lower Li 9 Fl \-space Li 2 |
|
592 |
+had been specified during invocation (with the |
|
593 |
+.Tn SSH |
|
594 |
+key already having been selected). |
|
595 |
+In particular, it is neither necessary to specify |
|
596 |
+.Fl \-phrase No or Fl \-key |
|
597 |
+nor is it necessary to actually select an |
|
598 |
+.Tn SSH |
|
599 |
+key or to type in a master passphrase. |
|
600 |
+. |
|
601 |
+.Sh DIAGNOSTICS |
|
602 |
+. |
|
603 |
+.Ex -std "derivepassphrase vault" |
|
604 |
+. |
|
605 |
+.Sh COMPATIBILITY |
|
606 |
+. |
|
607 |
+.Ss With other software |
|
608 |
+. |
|
609 |
+.Nm derivepassphrase vault |
|
610 |
+is |
|
611 |
+.Em almost |
|
612 |
+drop-in compatible with James Coglan's |
|
613 |
+.Xr vault 1 , |
|
614 |
+version 0.3.0 |
|
615 |
+.Pq including Do storeroom Dc support , |
|
616 |
+meaning that each tool supports the same file formats and command-line |
|
617 |
+arguments/options as the other one. |
|
618 |
+.Pp |
|
619 |
+. |
|
620 |
+Exceptions: |
|
621 |
+. |
|
622 |
+.Bl -bullet |
|
623 |
+. |
|
624 |
+.It |
|
625 |
+.Xr vault 1 |
|
626 |
+does not support the |
|
627 |
+.Sx "Compatibility and extension options" |
|
628 |
+listed above. |
|
629 |
+. |
|
630 |
+.It |
|
631 |
+.Nm derivepassphrase vault |
|
632 |
+can import and generate configuration exports in the same format as |
|
633 |
+.Xr vault 1 , |
|
634 |
+but it cannot |
|
635 |
+.Em natively |
|
636 |
+read or write |
|
637 |
+.Xr vault 1 |
|
638 |
+.Ns 's |
|
639 |
+configuration file |
|
640 |
+.Pq non-storeroom |
|
641 |
+or configuration directory |
|
642 |
+.Pq storeroom . |
|
643 |
+(The sister command |
|
644 |
+.Xr derivepassphrase-export 1 |
|
645 |
+can read both these formats and export the contents.) |
|
646 |
+. |
|
647 |
+.El |
|
648 |
+. |
|
649 |
+.Ss Forward and backward compatibility |
|
650 |
+. |
|
651 |
+.Bl -bullet |
|
652 |
+. |
|
653 |
+.It |
|
654 |
+.Bo Since v0.2.0 . Bc |
|
655 |
+In v1.0, the commands |
|
656 |
+.Nm derivepassphrase |
|
657 |
+and |
|
658 |
+.Nm derivepassphrase export |
|
659 |
+will require an explicit subcommand name. |
|
660 |
+Both default to the subcommand |
|
661 |
+.Ic vault . |
|
662 |
+. |
|
663 |
+.It |
|
664 |
+.Bo Since v0.2.0 . Bc |
|
665 |
+In v1.0, the configuration data file for the |
|
666 |
+.Ic vault |
|
667 |
+subcommand will be named |
|
668 |
+.Pa vault.json , |
|
669 |
+instead of |
|
670 |
+.Pa config.json . |
|
671 |
+. |
|
672 |
+.It |
|
673 |
+.Bo Since v0.2.0, to be removed in v1.0 . Bc |
|
674 |
+An existing configuration data file |
|
675 |
+.Pa config.json |
|
676 |
+will be attempted to be renamed to |
|
677 |
+.Pa vault.json . |
|
678 |
+.El |
|
679 |
+. |
|
680 |
+.Sh SEE ALSO |
|
681 |
+. |
|
682 |
+.Xr derivepassphrase 1 , |
|
683 |
+.Xr pageant 1 , |
|
684 |
+.Xr ssh-agent 1 . |
|
685 |
+.Rs |
|
686 |
+.%A "James Coglan" |
|
687 |
+.%T "vault(1)" |
|
688 |
+.%U https://www.npmjs.com/package/vault |
|
689 |
+.Re |
|
690 |
+.Pp |
|
691 |
+. |
|
692 |
+Further online documentation for |
|
693 |
+.Xr derivepassphrase 1 |
|
694 |
+.Pq tutorials, how-tos, reference and design documentation |
|
695 |
+is available at |
|
696 |
+.Lk https://the13thletter.info/derivepassphrase/ . |
|
697 |
+. |
|
698 |
+.Sh AUTHOR |
|
699 |
+. |
|
700 |
+.Lk mailto:software@the13thletter.info "Marco Ricci" |
|
701 |
+. |
|
702 |
+.Sh BUGS |
|
703 |
+. |
|
704 |
+.Bl -bullet |
|
705 |
+. |
|
706 |
+.It |
|
707 |
+The defaults are dictated by |
|
708 |
+.Xr vault 1 , |
|
709 |
+necessitating the |
|
710 |
+.Sx Compatibility and extension options . |
|
711 |
+.Pq WONTFIX. |
|
712 |
+. |
|
713 |
+.It |
|
714 |
+The Windows version does not support |
|
715 |
+.Tn SSH |
|
716 |
+keys because Python on Windows does not support the predominant type of |
|
717 |
+inter-process communication used by |
|
718 |
+.Tn SSH |
|
719 |
+agents on Windows. |
|
720 |
+. |
|
721 |
+.El |
|
722 |
+. |
... | ... |
@@ -2,116 +2,280 @@ |
2 | 2 |
|
3 | 3 |
## NAME |
4 | 4 |
|
5 |
-derivepassphrase-vault – derive a passphrase using the vault(1) |
|
6 |
-derivation scheme |
|
5 |
+derivepassphrase-vault – derive a passphrase using the vault derivation scheme |
|
7 | 6 |
|
8 | 7 |
## SYNOPSIS |
9 | 8 |
|
10 |
-```` |
|
11 |
-derivepassphrase vault [OPTIONS] [SERVICE] |
|
12 |
-```` |
|
9 |
+<pre> |
|
10 |
+<code><b>derivepassphrase vault</b> [--phrase | --key] [--length <var>n</var>] [--repeat <var>n</var>] [--lower <var>n</var>] [--upper <var>n</var>] [--number <var>n</var>] [--space <var>n</var>] [--dash <var>n</var>] [--symbol <var>n</var>] <var>SERVICE</var></code> |
|
11 |
+<code><b>derivepassphrase vault</b> {--phrase | --key | … | --symbol <var>n</var>} … --config [--unset <var>setting</var> …] [--overwrite-existing | --merge-existing] [<var>SERVICE</var>]</code> |
|
12 |
+<code><b>derivepassphrase vault</b> {--notes <var>SERVICE</var> | --delete <var>SERVICE</var> | --delete-globals | --clear}</code> |
|
13 |
+<code><b>derivepassphrase vault</b> [--export-as {json | sh}] {--import <var>PATH</var> | --export <var>PATH</var>}</code> |
|
14 |
+</pre> |
|
13 | 15 |
|
14 | 16 |
## DESCRIPTION |
15 | 17 |
|
16 |
-Using a master passphrase or a master SSH key, derive a passphrase for |
|
17 |
-<i>SERVICE</i>, subject to length, character and character repetition |
|
18 |
-constraints. The derivation is cryptographically strong, meaning that even |
|
19 |
-if a single passphrase is compromised, guessing the master passphrase or |
|
20 |
-a different service's passphrase is computationally infeasible. The |
|
21 |
-derivation is also deterministic, given the same inputs, thus the resulting |
|
22 |
-passphrase need not be stored explicitly. The service name and constraints |
|
23 |
-themselves also need not be kept secret; the latter are usually stored in |
|
24 |
-a world-readable file. |
|
18 |
+Using a master passphrase or a master SSH key, derive a passphrase for <var>SERVICE</var>, subject to length, character and character repetition constraints, in a manner compatible with James Coglan's <i>vault</i>(1). |
|
25 | 19 |
|
26 |
-If operating on global settings, or importing/exporting settings, then |
|
27 |
-<i>SERVICE</i> must be omitted. Otherwise it is required. |
|
20 |
+The derivation is cryptographically strong, meaning that even if a single passphrase is compromised, guessing the master passphrase or a different service's passphrase is computationally infeasible. |
|
21 |
+The derivation is also deterministic, given the same inputs, thus the resulting passphrase need not be stored explicitly. |
|
22 |
+ |
|
23 |
+The service name and constraints themselves also need not be kept secret; the latter are usually stored in a world-readable file. |
|
28 | 24 |
|
29 | 25 |
## OPTIONS |
30 | 26 |
|
31 |
-### Password generation |
|
27 |
+### Passphrase generation |
|
28 |
+ |
|
29 |
+The passphrase generation options can be divided into "passphrase source" options (`--phrase`, `--key`) and "passphrase constraint" options (all others). |
|
30 |
+The passphrase source options are mutually exclusive --- you may only specify one of them --- while the passphrase constraint options may be combined in any way. |
|
31 |
+The <var>SERVICE</var> is mandatory (see synopsis #1), unless the `--config` option is specified (see synopsis #2). |
|
32 |
+All character constraints refer to ASCII printable characters only (space (`U+0020`) to tilde (`U+007E`), excluding the grave accent (`U+0060`)). |
|
32 | 33 |
|
33 | 34 |
<b>-p</b>, <b>-</b><b>-phrase</b> |
34 |
-: prompts you for your passphrase |
|
35 |
+: Prompt for a passphrase. |
|
36 |
+ |
|
37 |
+ See also ["Configuration"](#configuration) for how this interacts with a stored passphrase or SSH key. |
|
35 | 38 |
|
36 | 39 |
<b>-k</b>, <b>-</b><b>-key</b> |
37 |
-: uses your SSH private key to generate passwords |
|
40 |
+: Select an SSH key. |
|
41 |
+ |
|
42 |
+ An SSH agent such as OpenSSH’s <i>ssh-agent</i>(1) or PuTTY’s <i>pageant</i>(1) must be running and accessible, and have the desired key loaded. |
|
43 |
+ The SSH key must also be <i>suitable</i> for this purpose; see ["SSH KEY SUITABILITY"](#ssh-key-suitability) for details. |
|
38 | 44 |
|
39 |
-<b>-l</b>, <b>-</b><b>-length</b> <var>NUMBER</var> |
|
40 |
-: emits password of length <var>NUMBER</var> |
|
45 |
+ See also ["Configuration"](#configuration) for how this interacts with a stored passphrase or SSH key. |
|
41 | 46 |
|
42 |
-<b>-r</b>, <b>-</b><b>-repeat</b> <var>NUMBER</var> |
|
43 |
-: allows maximum of <var>NUMBER</var> repeated adjacent chars |
|
47 |
+<b>-l</b> <var>n</var>, <b>-</b><b>-length</b> <var>n</var> |
|
48 |
+: Force the passphrase to have the length <var>n</var>. |
|
49 |
+ Defaults to the length <b>20</b> if not specified, or if explicitly specified as <code>0</code>. |
|
44 | 50 |
|
45 |
-<b>-</b><b>-lower</b> <var>NUMBER</var> |
|
46 |
-: includes at least <var>NUMBER</var> lowercase letters |
|
51 |
+<b>-r</b> <var>n</var>, <b>-</b><b>-repeat</b> <var>n</var> |
|
52 |
+: Permit only runs of up to <var>n</var> consecutive occurrences of the same character. |
|
53 |
+ Alternatively, forbid immediate additional repetitions of length <var>n</var> (or more) for any character in the derived passphrase. |
|
54 |
+ Setting <var>n</var> = `0` disables repetition constraints, which is the default. |
|
47 | 55 |
|
48 |
-<b>-</b><b>-upper</b> <var>NUMBER</var> |
|
49 |
-: includes at least <var>NUMBER</var> uppercase letters |
|
56 |
+<b>-</b><b>-lower</b> <var>n</var> |
|
57 |
+: Include at least <var>n</var> lowercase characters in the derived passphrase. |
|
58 |
+ Setting <var>n</var> = `0` forbids these characters entirely. |
|
59 |
+ The default is to not constrain the occurrences in any manner. |
|
50 | 60 |
|
51 |
-<b>-</b><b>-number</b> <var>NUMBER</var> |
|
52 |
-: includes at least <var>NUMBER</var> digits |
|
61 |
+<b>-</b><b>-upper</b> <var>n</var> |
|
62 |
+: Include at least <var>n</var> uppercase characters in the derived passphrase. |
|
63 |
+ Setting <var>n</var> = `0` forbids these characters entirely. |
|
64 |
+ The default is to not constrain the occurrences in any manner. |
|
53 | 65 |
|
54 |
-<b>-</b><b>-space</b> <var>NUMBER</var> |
|
55 |
-: includes at least <var>NUMBER</var> spaces |
|
66 |
+<b>-</b><b>-number</b> <var>n</var> |
|
67 |
+: Include at least <var>n</var> digits in the derived passphrase. |
|
68 |
+ Setting <var>n</var> = `0` forbids these characters entirely. |
|
69 |
+ The default is to not constrain the occurrences in any manner. |
|
56 | 70 |
|
57 |
-<b>-</b><b>-dash</b> <var>NUMBER</var> |
|
58 |
-: includes at least <var>NUMBER</var> `-` or `_` |
|
71 |
+<b>-</b><b>-space</b> <var>n</var> |
|
72 |
+: Include at least <var>n</var> spaces in the derived passphrase. |
|
73 |
+ Setting <var>n</var> = `0` forbids these characters entirely. |
|
74 |
+ The default is to not constrain the occurrences in any manner. |
|
59 | 75 |
|
60 |
-<b>-</b><b>-symbol</b> <var>NUMBER</var> |
|
61 |
-: includes at least <var>NUMBER</var> symbol chars |
|
76 |
+<b>-</b><b>-dash</b> <var>n</var> |
|
77 |
+: Include at least <var>n</var> "dashes" (`-` or `_`) in the derived passphrase. |
|
78 |
+ Setting <var>n</var> = `0` forbids these characters entirely. |
|
79 |
+ The default is to not constrain the occurrences in any manner. |
|
62 | 80 |
|
63 |
-Use <var>NUMBER</var>=0, e.g. `--symbol 0`, to exclude a character type from |
|
64 |
-the output. |
|
81 |
+<b>-</b><b>-symbol</b> <var>n</var> |
|
82 |
+: Include at least <var>n</var> symbols (any of `!"#$%&'()*+,./:;<=>?@[\]^{|}~-_`) in the derived passphrase. |
|
83 |
+ Setting <var>n</var> = `0` forbids these characters entirely, effectively also implying `--dash 0`. |
|
84 |
+ The default is to not constrain the occurrences in any manner. |
|
65 | 85 |
|
66 | 86 |
### Configuration |
67 | 87 |
|
88 |
+The configuration options directly modify the stored settings: default settings, known services, and service-specific settings. |
|
89 |
+They are mutually exclusive; you may only specify one of them. |
|
90 |
+The <var>SERVICE</var> is mandatory for `--notes` and `--delete`, optional for `--config`, and forbidden for `--delete-globals` and `--clear` (see synopsis #2 and synopsis #3). |
|
91 |
+ |
|
68 | 92 |
<b>-n</b>, <b>-</b><b>-notes</b> |
69 |
-: spawn an editor to edit notes for <var>SERVICE</var> |
|
93 |
+: Spawn an editor to edit notes for <var>SERVICE</var>. |
|
94 |
+ Use the `VISUAL` or `EDITOR` environment variables to configure the spawned editor. |
|
70 | 95 |
|
71 | 96 |
<b>-c</b>, <b>-</b><b>-config</b> |
72 |
-: saves the given settings for <var>SERVICE</var> or global |
|
97 |
+: Save the given settings for <var>SERVICE</var> (if given), or save the given settings as global default settings. |
|
98 |
+ |
|
99 |
+ See the ["Passphrase generation"](#passphrase-generation) and ["Compatibility and extension options"](#compatibility-and-extension-options) sections for other options compatible with `--config`. |
|
100 |
+ |
|
101 |
+ !!! danger |
|
102 |
+ |
|
103 |
+ Do **not** use the `--phrase` and `--config` options together. |
|
104 |
+ The configuration is assumed to *not contain sensitive contents*, and is *not encrypted*. |
|
73 | 105 |
|
74 | 106 |
<b>-x</b>, <b>-</b><b>-delete</b> |
75 |
-: deletes settings for <var>SERVICE</var> |
|
107 |
+: Delete all stored settings for <var>SERVICE</var>. |
|
76 | 108 |
|
77 | 109 |
<b>-</b><b>-delete-globals</b> |
78 |
-: deletes the global shared settings |
|
110 |
+: Delete all stored global default settings. |
|
79 | 111 |
|
80 | 112 |
<b>-X</b>, <b>-</b><b>-clear</b> |
81 |
-: deletes all settings |
|
82 |
- |
|
83 |
-Use `$VISUAL` or `$EDITOR` to configure the spawned editor. |
|
113 |
+: Delete all stored settings. |
|
84 | 114 |
|
85 | 115 |
### Storage management |
86 | 116 |
|
87 |
-<b>-e</b>, <b>-</b><b>-export</b> <var>PATH</var> |
|
88 |
-: export all saved settings into file <var>PATH</var> |
|
117 |
+The storage management options deal with importing and exporting the stored settings. |
|
118 |
+They are mutually exclusive; you may only specify one of them. |
|
119 |
+Using `-` as <var>PATH</var> for standard input/standard output is supported. |
|
120 |
+ |
|
121 |
+<b>-e</b> <var>PATH</var>, <b>-</b><b>-export</b> <var>PATH</var> |
|
122 |
+: Export all saved settings into file <var>PATH</var>. |
|
89 | 123 |
|
90 |
-<b>-i</b>, <b>-</b><b>-import</b> <var>PATH</var> |
|
91 |
-: import saved settings from file <var>PATH</var> |
|
124 |
+<b>-i</b> <var>PATH</var>, <b>-</b><b>-import</b> <var>PATH</var> |
|
125 |
+: Import saved settings from file <var>PATH</var>. |
|
92 | 126 |
|
93 |
-Using `-` as <var>PATH</var> for standard input/standard output is supported. |
|
127 |
+### Compatibility and extension options |
|
128 |
+ |
|
129 |
+By default, <b>derivepassphrase vault</b> behaves in a manner compatible with <i>vault</i>(1). |
|
130 |
+The compatibility and extension options modify the behavior to enable additional functionality, or specifically to force compatibility. |
|
131 |
+ |
|
132 |
+<i>vault</i>(1) supports none of these options, and behaves as if the option had not been given or had been left in its default state. |
|
133 |
+ |
|
134 |
+<b>-</b><b>-overwrite-existing</b> / <b>-</b><b>-merge-existing</b> |
|
135 |
+: When importing a configuration via `--import`, or configuring the settings via `--config`, overwrite or merge (<em>default</em>) the existing configuration. |
|
136 |
+ |
|
137 |
+ If overwriting the configuration, then the whole configuration (for `--import`) or the respective section (service-specific or global, for `--config`), will be written from scratch. |
|
138 |
+ If merging, then each section (service-specific or global, for `--import`) or each singular setting (for `--config`) will be overwritten, but other unaffected settings/sections will not. |
|
139 |
+ |
|
140 |
+ (<i>vault</i>(1) behaves as if `--merge-existing` were always given.) |
|
141 |
+ |
|
142 |
+<b>-</b><b>-unset</b> <var>setting</var> |
|
143 |
+: When configuring via `--config`, also unset the specified <var>setting</var>, where <var>setting</var> is one of the passphrase generation settings (<code>phrase</code>, <code>key</code>, <code>lower</code>, …). |
|
144 |
+ May be specified multiple times. |
|
145 |
+ Must not overlap with any of the settings being set afterwards. |
|
146 |
+ |
|
147 |
+ (vault(1) does not support this option.) |
|
148 |
+ |
|
149 |
+<b>-</b><b>-export-as</b> \{ <b>json</b> | <b>sh</b> \} |
|
150 |
+: When exporting the configuration via `--export`, export as JSON (default) or as a shell script in <i>sh</i>(1) format. |
|
151 |
+ |
|
152 |
+ The JSON format is compatible with <i>vault</i>(1). |
|
153 |
+ For the shell script format, see the ["SHELL SCRIPT EXPORT FORMAT"](#shell-script-export-format) section for details. |
|
154 |
+ |
|
155 |
+ (vault(1) behaves as if `--export-as json` were always given.) |
|
94 | 156 |
|
95 | 157 |
### Other Options |
96 | 158 |
|
97 |
-<b>--version</b> |
|
159 |
+<b>-</b><b>-version</b> |
|
98 | 160 |
: Show the version and exit. |
99 | 161 |
|
100 | 162 |
<b>-h</b>, <b>-</b><b>-help</b> |
101 |
-: Show this message and exit. |
|
163 |
+: Show a help message and exit. |
|
164 |
+ |
|
165 |
+## SHELL SCRIPT EXPORT FORMAT |
|
166 |
+ |
|
167 |
+If the shell script export format is selected, the configuration will be exported as a POSIX <i>sh</i>(1) script, containing calls to <b>derivepassphrase vault</b> to reconstruct the current configuration from scratch. |
|
168 |
+The script assumes a conforming <i>sh</i>(1), with support for "here" documents. |
|
169 |
+ |
|
170 |
+!!! danger |
|
171 |
+ |
|
172 |
+ **Do not run these emitted shell scripts directly without double-checking their output first!** |
|
173 |
+ |
|
174 |
+## SSH KEY SUITABILITY |
|
175 |
+ |
|
176 |
+An SSH key is <dfn>suitable</dfn> for use with <b>derivepassphrase vault</b> if the SSH agent guarantees that signatures produced with this key will be <em>deterministic</em>, given the same message to be signed. |
|
177 |
+This is a property specific to the key type, and sometimes the agent used: |
|
178 |
+ |
|
179 |
+ * RSA, Ed25519 and Ed448 keys are always suitable. |
|
180 |
+ OpenSSH’s <i>ssh-agent</i>(1) supports only these keys as suitable keys. |
|
181 |
+ |
|
182 |
+ * DSA and ECDSA keys are suitable if the SSH agent supports deterministic DSA signatures, e.g. by implementing RFC 6979. |
|
183 |
+ PuTTY’s <i>pageant</i>(1) supports this, in addition to the always-suitable keys mentioned above. |
|
184 |
+ |
|
185 |
+## ENVIRONMENT |
|
186 |
+ |
|
187 |
+`VISUAL`, `EDITOR` |
|
188 |
+: <b>derivepassphrase vault</b> uses this editor to edit service notes when called with `--notes`. |
|
189 |
+ `VISUAL` has higher precedence than `EDITOR`. |
|
102 | 190 |
|
103 |
-## WARNINGS |
|
191 |
+`DERIVEPASSPHRASE_PATH` |
|
192 |
+: <b>derivepassphrase</b> stores its configuration files and data in this directory. |
|
193 |
+ Defaults to `~/.derivepassphrase`. |
|
104 | 194 |
|
105 |
-There is **no way** to retrieve the generated passphrases if the master |
|
106 |
-passphrase, the SSH key, or the exact passphrase settings are lost, |
|
107 |
-short of trying out all possible combinations. You are **strongly** |
|
108 |
-advised to keep independent backups of the settings and the SSH key, if |
|
109 |
-any. |
|
195 |
+## FILES |
|
110 | 196 |
|
111 |
-The configuration is **not** encrypted, and you are **strongly** |
|
112 |
-discouraged from using a stored passphrase. |
|
197 |
+`$DERIVEPASSPHRASE_PATH/vault.json` |
|
198 |
+: The stored configuration for <b>derivepassphrase vault</b>: the default passphrase generation settings, the known service names, and the service-specific settings. |
|
199 |
+ This file is <em>not</em> intended for the user to edit. |
|
200 |
+ |
|
201 |
+## SECURITY |
|
202 |
+ |
|
203 |
+!!! danger |
|
204 |
+ |
|
205 |
+ * There is **no way** to retrieve the generated passphrases if the master passphrase, the SSH key, or the exact passphrase settings are lost, short of trying out all possible combinations. |
|
206 |
+ You are **strongly** advised to keep independent backups of the settings and the SSH key, if any. |
|
207 |
+ |
|
208 |
+ * The configuration is **not** encrypted, and you are **strongly** discouraged from using a stored passphrase. |
|
209 |
+ |
|
210 |
+ * You are **strongly** advised to avoid the (shell script) configuration export format if possible, and use the JSON format instead. |
|
211 |
+ If you *must* use the shell script format, then **always** validate the export before attempting to interpret or run it. |
|
212 |
+ |
|
213 |
+## EXAMPLES |
|
214 |
+ |
|
215 |
+??? example "`derivepassphrase vault --phrase email`" |
|
216 |
+ |
|
217 |
+ Prompt for a master passphrase, then generate a standard passphrase (length 20, no character or repetition constraints) for the "email" service. |
|
218 |
+ |
|
219 |
+??? example "`derivepassphrase vault --key --upper 9 --lower 9 example.com`" |
|
220 |
+ |
|
221 |
+ Select an SSH key from the available suitable SSH keys in the running SSH agent, then generate a passphrase for the `example.com` service using the previously selected SSH key. |
|
222 |
+ The passphrase will have (standard) length 20, and at least nine characters will be uppercase characters and at least another nine characters will be lowercase characters. |
|
223 |
+ |
|
224 |
+??? example "`derivepassphrase example.com vault --key --upper 9 --lower 9 --number 9`" |
|
225 |
+ |
|
226 |
+ Attempt to generate a passphrase as in the previous example. |
|
227 |
+ This example will <em>error out</em>, because the passphrase constraints require at least 27 characters and the standard passphrase length 20 cannot accomodate this. |
|
228 |
+ |
|
229 |
+??? example "`derivepassphrase --config vault --key --upper 9 --lower 9 --space 2`" |
|
230 |
+ |
|
231 |
+ After selecting an SSH key, configure the default settings to use exactly nine uppercase characters, nine lowercase characters, and two spaces for each generated passphrase. |
|
232 |
+ (The specific service settings, or the command-line invocation, can still override these settings.) |
|
233 |
+ |
|
234 |
+??? example "`derivepassphrase vault example.com`" |
|
235 |
+ |
|
236 |
+ Because of the previous setting, the generated passphrase for the `example.com` service will behave as if `--key --upper 9 --lower 9 --space 2` had been specified during invocation (with the SSH key already having been selected). |
|
237 |
+ In particular, it is neither necessary to specify `--phrase` or `--key` nor is it necessary to actually select an SSH key or to type in a master passphrase. |
|
238 |
+ |
|
239 |
+## DIAGNOSTICS |
|
240 |
+ |
|
241 |
+The derivepassphrase vault utility exits 0 on success, and >0 if an error occurs. |
|
242 |
+ |
|
243 |
+## COMPATIBILITY |
|
244 |
+ |
|
245 |
+### With other software |
|
246 |
+ |
|
247 |
+<b>derivepassphrase vault</b> is <em>almost</em> drop-in compatible with James Coglan’s <i>vault</i>(1), version 0.3.0 (including "storeroom" support), meaning that each tool supports the same file formats and command-line arguments/options as the other one. |
|
248 |
+ |
|
249 |
+Exceptions: |
|
250 |
+ |
|
251 |
+ * <i>vault</i>(1) does not support the ["Compatibility and extension options"](#compatibility-and-extension-options) listed above. |
|
252 |
+ |
|
253 |
+ * <b>derivepassphrase vault</b> can import and generate configuration exports in the same format as <i>vault</i>(1), but it cannot <em>natively</em> read or write <i>vault</i>(1)'s configuration file (non-storeroom) or configuration directory (storeroom). |
|
254 |
+ (The sister command <i>derivepassphrase-export</i>(1) can read both these formats and export the contents.) |
|
255 |
+ |
|
256 |
+### Forward and backward compatibility |
|
257 |
+ |
|
258 |
+ * [Since v0.2.0.] |
|
259 |
+ In v1.0, the commands <b>derivepassphrase</b> and <b>derivepassphrase export</b> will require an explicit subcommand name. |
|
260 |
+ Both default to the subcommand <b>vault</b>. |
|
261 |
+ * [Since v0.2.0.] |
|
262 |
+ In v1.0, the configuration data file for the <b>vault</b> subcommand will be named `vault.json`, instead of `config.json`. |
|
263 |
+ * [Since v0.2.0, to be removed in v1.0.] |
|
264 |
+ An existing configuration data file `config.json` will be attempted to be renamed to `vault.json`. |
|
113 | 265 |
|
114 | 266 |
## SEE ALSO |
115 | 267 |
|
116 |
-[derivepassphrase(1)](derivepassphrase.1.md), |
|
117 |
-[vault(1)](https://www.npmjs.com/package/vault) |
|
268 |
+[<i>derivepassphrase</i>(1)](derivepassphrase.1.md), |
|
269 |
+[<i>pageant</i>(1)](https://www.chiark.greenend.org.uk/~sgtatham/putty/), |
|
270 |
+[<i>ssh-agent</i>(1)](https://www.openssh.com/), |
|
271 |
+[<i>vault</i>(1)](https://www.npmjs.com/package/vault "James Coglan's 'vault'"). |
|
272 |
+ |
|
273 |
+## AUTHOR |
|
274 |
+ |
|
275 |
+[Marco Ricci](https://the13thletter.info) (`software` at `the13thletter` dot `info`) |
|
276 |
+ |
|
277 |
+## BUGS |
|
278 |
+ |
|
279 |
+ * The defaults are dictated by <i>vault</i>(1), necessitating the ["Compatibility and extension options"](#compatibility-and-extension-options). (WONTFIX.) |
|
280 |
+ |
|
281 |
+ * The Windows version does not support SSH keys because Python on Windows does not support the predominant type of inter-process communication used by SSH agents on Windows. |
... | ... |
@@ -1438,10 +1438,10 @@ def _print_config_as_sh_script( |
1438 | 1438 |
|
1439 | 1439 |
|
1440 | 1440 |
# Concrete option groups used by this command-line interface. |
1441 |
-class PasswordGenerationOption(OptionGroupOption): |
|
1442 |
- """Password generation options for the CLI.""" |
|
1441 |
+class PassphraseGenerationOption(OptionGroupOption): |
|
1442 |
+ """Passphrase generation options for the CLI.""" |
|
1443 | 1443 |
|
1444 |
- option_group_name = 'Password generation' |
|
1444 |
+ option_group_name = 'Passphrase generation' |
|
1445 | 1445 |
epilog = """ |
1446 | 1446 |
Use NUMBER=0, e.g. "--symbol 0", to exclude a character type |
1447 | 1447 |
from the output. |
... | ... |
@@ -1470,7 +1470,7 @@ class StorageManagementOption(OptionGroupOption): |
1470 | 1470 |
class CompatibilityOption(OptionGroupOption): |
1471 | 1471 |
"""Compatibility and incompatibility options for the CLI.""" |
1472 | 1472 |
|
1473 |
- option_group_name = 'Options concerning compatibility with other tools' |
|
1473 |
+ option_group_name = 'Compatibility and extension options' |
|
1474 | 1474 |
|
1475 | 1475 |
|
1476 | 1476 |
def _validate_occurrence_constraint( |
... | ... |
@@ -1582,7 +1582,7 @@ DEFAULT_NOTES_MARKER = '# - - - - - >8 - - - - -' |
1582 | 1582 |
'use_phrase', |
1583 | 1583 |
is_flag=True, |
1584 | 1584 |
help='prompts you for your passphrase', |
1585 |
- cls=PasswordGenerationOption, |
|
1585 |
+ cls=PassphraseGenerationOption, |
|
1586 | 1586 |
) |
1587 | 1587 |
@click.option( |
1588 | 1588 |
'-k', |
... | ... |
@@ -1590,7 +1590,7 @@ DEFAULT_NOTES_MARKER = '# - - - - - >8 - - - - -' |
1590 | 1590 |
'use_key', |
1591 | 1591 |
is_flag=True, |
1592 | 1592 |
help='uses your SSH private key to generate passwords', |
1593 |
- cls=PasswordGenerationOption, |
|
1593 |
+ cls=PassphraseGenerationOption, |
|
1594 | 1594 |
) |
1595 | 1595 |
@click.option( |
1596 | 1596 |
'-l', |
... | ... |
@@ -1598,7 +1598,7 @@ DEFAULT_NOTES_MARKER = '# - - - - - >8 - - - - -' |
1598 | 1598 |
metavar='NUMBER', |
1599 | 1599 |
callback=_validate_length, |
1600 | 1600 |
help='emits password of length NUMBER', |
1601 |
- cls=PasswordGenerationOption, |
|
1601 |
+ cls=PassphraseGenerationOption, |
|
1602 | 1602 |
) |
1603 | 1603 |
@click.option( |
1604 | 1604 |
'-r', |
... | ... |
@@ -1606,49 +1606,49 @@ DEFAULT_NOTES_MARKER = '# - - - - - >8 - - - - -' |
1606 | 1606 |
metavar='NUMBER', |
1607 | 1607 |
callback=_validate_occurrence_constraint, |
1608 | 1608 |
help='allows maximum of NUMBER repeated adjacent chars', |
1609 |
- cls=PasswordGenerationOption, |
|
1609 |
+ cls=PassphraseGenerationOption, |
|
1610 | 1610 |
) |
1611 | 1611 |
@click.option( |
1612 | 1612 |
'--lower', |
1613 | 1613 |
metavar='NUMBER', |
1614 | 1614 |
callback=_validate_occurrence_constraint, |
1615 | 1615 |
help='includes at least NUMBER lowercase letters', |
1616 |
- cls=PasswordGenerationOption, |
|
1616 |
+ cls=PassphraseGenerationOption, |
|
1617 | 1617 |
) |
1618 | 1618 |
@click.option( |
1619 | 1619 |
'--upper', |
1620 | 1620 |
metavar='NUMBER', |
1621 | 1621 |
callback=_validate_occurrence_constraint, |
1622 | 1622 |
help='includes at least NUMBER uppercase letters', |
1623 |
- cls=PasswordGenerationOption, |
|
1623 |
+ cls=PassphraseGenerationOption, |
|
1624 | 1624 |
) |
1625 | 1625 |
@click.option( |
1626 | 1626 |
'--number', |
1627 | 1627 |
metavar='NUMBER', |
1628 | 1628 |
callback=_validate_occurrence_constraint, |
1629 | 1629 |
help='includes at least NUMBER digits', |
1630 |
- cls=PasswordGenerationOption, |
|
1630 |
+ cls=PassphraseGenerationOption, |
|
1631 | 1631 |
) |
1632 | 1632 |
@click.option( |
1633 | 1633 |
'--space', |
1634 | 1634 |
metavar='NUMBER', |
1635 | 1635 |
callback=_validate_occurrence_constraint, |
1636 | 1636 |
help='includes at least NUMBER spaces', |
1637 |
- cls=PasswordGenerationOption, |
|
1637 |
+ cls=PassphraseGenerationOption, |
|
1638 | 1638 |
) |
1639 | 1639 |
@click.option( |
1640 | 1640 |
'--dash', |
1641 | 1641 |
metavar='NUMBER', |
1642 | 1642 |
callback=_validate_occurrence_constraint, |
1643 | 1643 |
help='includes at least NUMBER "-" or "_"', |
1644 |
- cls=PasswordGenerationOption, |
|
1644 |
+ cls=PassphraseGenerationOption, |
|
1645 | 1645 |
) |
1646 | 1646 |
@click.option( |
1647 | 1647 |
'--symbol', |
1648 | 1648 |
metavar='NUMBER', |
1649 | 1649 |
callback=_validate_occurrence_constraint, |
1650 | 1650 |
help='includes at least NUMBER symbol chars', |
1651 |
- cls=PasswordGenerationOption, |
|
1651 |
+ cls=PassphraseGenerationOption, |
|
1652 | 1652 |
) |
1653 | 1653 |
@click.option( |
1654 | 1654 |
'-n', |
... | ... |
@@ -1883,8 +1883,8 @@ def derivepassphrase_vault( # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915 |
1883 | 1883 |
if isinstance(param, click.Option): |
1884 | 1884 |
group: type[click.Option] |
1885 | 1885 |
# Use match/case here once Python 3.9 becomes unsupported. |
1886 |
- if isinstance(param, PasswordGenerationOption): |
|
1887 |
- group = PasswordGenerationOption |
|
1886 |
+ if isinstance(param, PassphraseGenerationOption): |
|
1887 |
+ group = PassphraseGenerationOption |
|
1888 | 1888 |
elif isinstance(param, ConfigurationOption): |
1889 | 1889 |
group = ConfigurationOption |
1890 | 1890 |
elif isinstance(param, StorageManagementOption): |
... | ... |
@@ -2006,7 +2006,7 @@ def derivepassphrase_vault( # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915 |
2006 | 2006 |
for group in (ConfigurationOption, StorageManagementOption): |
2007 | 2007 |
for opt in options_in_group[group]: |
2008 | 2008 |
if opt != params_by_str['--config']: |
2009 |
- for other_opt in options_in_group[PasswordGenerationOption]: |
|
2009 |
+ for other_opt in options_in_group[PassphraseGenerationOption]: |
|
2010 | 2010 |
check_incompatible_options(opt, other_opt) |
2011 | 2011 |
|
2012 | 2012 |
for group in (ConfigurationOption, StorageManagementOption): |
... | ... |
@@ -2015,7 +2015,7 @@ def derivepassphrase_vault( # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915 |
2015 | 2015 |
check_incompatible_options(opt, other_opt) |
2016 | 2016 |
for other_opt in options_in_group[StorageManagementOption]: |
2017 | 2017 |
check_incompatible_options(opt, other_opt) |
2018 |
- sv_or_global_options = options_in_group[PasswordGenerationOption] |
|
2018 |
+ sv_or_global_options = options_in_group[PassphraseGenerationOption] |
|
2019 | 2019 |
for param in sv_or_global_options: |
2020 | 2020 |
if is_param_set(param) and not ( |
2021 | 2021 |
service or is_param_set(params_by_str['--config']) |
... | ... |
@@ -70,7 +70,7 @@ class OptionCombination(NamedTuple): |
70 | 70 |
check_success: bool |
71 | 71 |
|
72 | 72 |
|
73 |
-PASSWORD_GENERATION_OPTIONS: list[tuple[str, ...]] = [ |
|
73 |
+PASSPHRASE_GENERATION_OPTIONS: list[tuple[str, ...]] = [ |
|
74 | 74 |
('--phrase',), |
75 | 75 |
('--key',), |
76 | 76 |
('--length', '20'), |
... | ... |
@@ -292,7 +292,7 @@ class TestCLI: |
292 | 292 |
) |
293 | 293 |
result = tests.ReadableResult.parse(_result) |
294 | 294 |
assert result.clean_exit( |
295 |
- empty_stderr=True, output='Password generation:\n' |
|
295 |
+ empty_stderr=True, output='Passphrase generation:\n' |
|
296 | 296 |
), 'expected clean exit, and option groups in help text' |
297 | 297 |
assert result.clean_exit( |
298 | 298 |
empty_stderr=True, output='Use NUMBER=0, e.g. "--symbol 0"' |
... | ... |
@@ -2593,7 +2593,7 @@ class TestCLITransition: |
2593 | 2593 |
) |
2594 | 2594 |
result = tests.ReadableResult.parse(_result) |
2595 | 2595 |
assert result.clean_exit( |
2596 |
- empty_stderr=True, output='Password generation:\n' |
|
2596 |
+ empty_stderr=True, output='Passphrase generation:\n' |
|
2597 | 2597 |
), 'expected clean exit, and option groups in help text' |
2598 | 2598 |
assert result.clean_exit( |
2599 | 2599 |
empty_stderr=True, output='Use NUMBER=0, e.g. "--symbol 0"' |
2600 | 2600 |