derivepassphrase.git

Add an actual derivepassphrase-vault(1) manpage, plus better manpage contents
Parent 2084290
Marco Ricci

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.
docs/reference/derivepassphrase-vault.1
Zeige Datei @ 8154b0f
... ... 
@@ -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 
+.
docs/reference/derivepassphrase-vault.1.md
Zeige Datei @ 8154b0f
... ... 
@@ -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.
src/derivepassphrase/cli.py
Zeige Datei @ 8154b0f
... ... 
@@ -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'])
tests/test_derivepassphrase_cli.py
Zeige Datei @ 8154b0f
... ... 
@@ -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