derivepassphrase.git

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) .Pp
605) .
606) .Ss Fatal error messages on standard error
607) .
608) .Pq Li %s Ns No " indicates a variable part of the message."
609) .
610) .Bl -diag
611) .
612) .It %s is mutually exclusive with %s.
613) The two indicated options must not be used at the same time.
614) .
615) .It %s requires a SERVICE or \-\-config.
616) Using the indicated passphrase generation option requires the
617) .Ar SERVICE
618) argument or the
619) .Fl \-config
620) option.
621) .
622) .It %s requires a SERVICE.
623) Using the indicated option requires the
624) .Ar SERVICE
625) argument.
626) .
627) .It %s does not take a SERVICE argument.
628) The indicated option must not be specified together with the
629) .Ar SERVICE
630) argument.
631) .
632) .It Cannot load vault settings: %s.
633) There was a fatal problem loading the stored vault configuration data.
634) Further details are contained in the variable part of the message.
635) .
636) .It Cannot store vault settings: %s.
637) There was a fatal problem saving the vault configuration data.
638) Further details are contained in the variable part of the message.
639) .
640) .It Cannot import vault settings: %s.
641) There was a fatal problem loading the imported vault configuration data.
642) Further details are contained in the variable part of the message.
643) .
644) .It Cannot export vault settings: %s.
645) There was a fatal problem saving the exported vault configuration data.
646) Further details are contained in the variable part of the message.
647) .
648) .It Cannot load user config: %s.
649) There was a fatal problem loading the central user configuration file.
650) Further details are contained in the variable part of the message.
651) .
652) .It The user configuration file is invalid.
653) (Exactly what it says.)
654) .
655) .It No usable SSH keys were found
656) The running SSH agent does not contain any suitable SSH keys.
657) .
658) .It No valid SSH key selected
659) We requested that an SSH key be selected, but we got an invalid selection.
660) .
661) .It The requested SSH key is not loaded into the agent.
662) The running SSH agent does not contain the necessary SSH key.
663) .
664) .It Cannot find any running SSH agent because SSH_AUTH_SOCK is not set.
665) We require a running SSH agent, but cannot locate its communication channel,
666) which is normally indicated by the
667) .Ev SSH_AUTH_SOCK
668) environment variable.
669) .
670) .It Cannot connect to an SSH agent because this Python version does not support UNIX domain sockets.
671) This Python installation does not support the communication mechanism
672) necessary to talk to SSH agents.
673) .
674) .It Cannot connect to the SSH agent: %s.
675) We cannot connect to the SSH agent indicated by the
676) .Ev SSH_AUTH_SOCK
677) environment variable.
678) Further details are contained in the variable part of the message.
679) .
680) .It The SSH agent failed to complete the request
681) The SSH agent \(em while responsive in principle \(em failed to or refused
682) to supply a list of loaded keys.
683) .
684) .It Error communicating with the SSH agent
685) There was a system error communicating with the SSH agent.
686) .
687) .It Not saving any new notes: the user aborted the request.
688) (Exactly what it says.)
689) .
690) .It Cannot update %s settings without actual settings.
691) Using
692) .Fl \-config
693) requires at least one of the
694) .Fl \-phrase , \-key , \-length , No etc.\&
695) options.
696) .
697) .It Attempted to unset and set %s at the same time.
698) While handling
699) .Fl \-config ,
700) the same configuration setting was passed as an option and as an argument to
701) .Fl \-unset .
702) .
703) .It Generating a passphrase requires a SERVICE.
704) (Exactly what it says.)
705) .
706) .It No passphrase or key was given in the configuration.
707) .Nm derivepassphrase vault
708) does not know whether to use a master SSH key or a master passphrase.
709) .
710) .It No passphrase was given: the user aborted the request.
711) (Exactly what it says.)
712) .
713) .It No SSH key was selected: the user aborted the request.
714) (Exactly what it says.)
715) .
716) .El
717) .Pp
718) .
719) .Ss Non-fatal warning and info messages on standard error
720) .
721) .Pq Li %s Ns No " indicates a variable part of the message."
722) .
723) .Bl -diag
724) .
725) .It The %s passphrase is not %s-normalized.
726) The indicated passphrase \(em as a Unicode string \(em is not properly
727) normalized according to the preferred Unicode normalization form
728) .Pq as specified in the central configuration file .
729) It is therefore possible that the passphrase \(em as a byte string \(em is
730) not the same byte string as you expect it to be
731) .Pq even though it Em looks No correct ,
732) and that the derived passphrases thus do not match their expected values
733) either.
734) Please double-check.
735) .
736) .It An empty SERVICE is not supported by vault(1).
737) .Xr vault 1
738) does not support the empty string as a value for
739) .Ar SERVICE ;
740) it will treat the
741) .Ar SERVICE
742) as missing.
743) For compatibility,
744) .Nm derivepassphrase vault
745) will do the same.
746) In particular, if the empty service is imported in a configuration via
747) .Fl \-import ,
748) then this service cannot be accessed via the
749) .Nm derivepassphrase vault
750) command-line.
751) .
752) .It Replacing invalid value %s for key %s with %s.
753) When importing a configuration, the indicated invalid value has been
754) replaced with the indicated replacement value.
755) .Pq The Do interpretation Dc of the configuration doesn't change .
756) .
757) .It Removing ineffective setting %s = %s.
758) When importing a configuration, the indicated ineffective setting has been
759) removed.
760) .Pq The Do interpretation Dc of the configuration doesn't change .
761) .
762) .It Setting a %s passphrase is ineffective because a key is also set.
763) The configuration (global or key-specific) contains both a stored master
764) passphrase and an SSH key.
765) The master passphrase will not take effect.
766) .
767) .It A subcommand will be required in v1.0.
768) .Bo
769) Since v0.2.0, until v1.0.
770) .Bc
771) This command now requires a subcommand.
772) For compatibility, it currently defaults to
773) .Dq vault .
774) .
775) .It Using deprecated v0.1-style config file %s, instead of v0.2-style %s.
776) .Bo
777) Since v0.2.0, until v1.0.
778) .Bc
779) A configuration file has been renamed.
780) .Nm derivepassphrase vault
781) will attempt to rename the file itself
782) .Pq Qq Li Successfully migrated to %s. ,
783) or complain if it cannot rename it
784) .Pq Qq Li Failed to migrate to %s: %s .
785) .
786) .El