derivepassphrase.git

Overhaul all other manpages and copyedit everything for consistency
Parent 50a83cf
Marco Ricci

Marco Ricci commited on 2025-01-11 15:38:02
Zeige 8 geänderte Dateien mit 749 Einfügungen und 84 Löschungen. 

The top-level `derivepassphrase` command, and the subcommands `export`
and `export vault` now have proper manpages (both manpage and online
formats) similar to `derivepassphrase vault`.

All manpages document the `--help`, `--version`, `--debug`, `--verbose`
and `--quiet` options.  If a command only delegates to subcommands,
a SUBCOMMANDS section is now present, and the DESCRIPTION section has
the subcommand listing deduplicated.  The COMPATIBILITY section details
compatibility only for this command, and refers to subcommand manpages
as necessary.

The new manpages do not tabulate their diagnostics yet, nor do they
include examples.
docs/reference/derivepassphrase-export-vault.1.md
Zeige Datei @ a8c8e83
... ... 
@@ -2,53 +2,94 @@
2 2
3 3 
 ## NAME
4 4
5 
-derivepassphrase-export-vault – export a vault-native configuration to
6 
-standard output
5 
+derivepassphrase-export-vault – export a vault-native configuration to standard output
7 6
8 7 
 ## SYNOPSIS
9 8
10 9 
 ````
11 
-derivepassphrase export vault [OPTIONS] PATH
10 
+derivepassphrase export vault [-f FMT] [-k K] PATH
12 11 
 ````
13 12
14 13 
 ## DESCRIPTION
15 14
16 
-Read the <b>vault</b>-native configuration at <i>PATH</i>, extract all
17 
-information from it, and export the resulting configuration to standard
18 
-output. Depending on the configuration format, this may either be a file or
19 
-a directory.  Supports the vault "v0.2", "v0.3" and "storeroom" formats.
15 
+Read the <i>vault</i>(1)-native configuration at <i>PATH</i>, extract all information from it, and export the resulting configuration to standard output (as if using <i>vault</i>(1)'s <b>-</b><b>-export</b> option).
16 
+Depending on the configuration format, this may either be a file or a directory.
17 
+Supports the <i>vault</i>(1) `v0.2`, `v0.3` and `storeroom` formats, all of which inherently use encryption and integrity protection.
20 18
21 
-If <i>PATH</i> is explicitly given as `VAULT_PATH`, then use the
22 
-`VAULT_PATH` environment variable to determine the correct path. (Use
23 
-`./VAULT_PATH` or similar to indicate a file/directory actually named
24 
-`VAULT_PATH`.)
19 
+If <i>PATH</i> is explicitly given as `VAULT_PATH`, then use the `VAULT_PATH` environment variable to determine the correct path.
20 
+(Use `./VAULT_PATH` or similar to indicate a file/directory actually named `VAULT_PATH`.)
25 21
26 22 
 ## OPTIONS
27 23
28 24 
 <b>-f</b>, <b>-</b><b>-format</b> <i>FMT</i>
29 
-:    try the following storage formats, in order (default: `v0.3`, `v0.2`)
25 
+:   Try the storage format <i>FMT</i>.
26 
+    May be given multiple times; the formats will be tried in order.
27 
+
28 
+    By default, we first try `v0.3`, then `v0.2`, and finally `storeroom`.
30 29
31 30 
 <b>-k</b>, <b>-</b><b>-key</b> <i>K</i>
32 
-:    use <i>K</i> as the storage master key (default: check the `VAULT_KEY`,
33 
-     `LOGNAME`, `USER` or `USERNAME` environment variables)
31 
+:   Use <i>K</i> as the storage master key.
32 
+
33 
+    By default, we check the `VAULT_KEY`, `LOGNAME`, `USER` and `USERNAME` environment variables, and use the first one with a proper value (*and only the first one*).
34 
+
35 
+<b>-</b><b>-debug</b>
36 
+:   Emit all diagnostic information to standard error, including progress, warning and error messages.
37 
+
38 
+    Cancels the effect of any previous <b>-</b><b>-quiet</b> or <b>-</b><b>-verbose</b> options.
39 
+
40 
+<b>-v</b>, <b>-</b><b>-verbose</b>
41 
+:   Emit extra/progress information to standard error, on top of warning and error messages.
42 
+
43 
+    Cancels the effect of any previous <b>-</b><b>-debug</b> or <b>-</b><b>-quiet</b> options.
44 
+
45 
+<b>-q</b>, <b>-</b><b>-quiet</b>
46 
+:   Suppress all other diagnostic output to standard error, except error messages.
47 
+    This includes warning messages.
48 
+
49 
+    Cancels the effect of any previous <b>-</b><b>-debug</b> or <b>-</b><b>-verbose</b> options.
50 
+
51 
+<b>-</b><b>-version</b>
52 
+:   Show the version and exit.
34 53
35 54 
 <b>-h</b>, <b>-</b><b>-help</b>
36 
-:    Show this message and exit.
55 
+:   Show a help message and exit.
56 
+
57 
+## ENVIRONMENT
37 58
38 
-## ENVIRONMENT VARIABLES
59 
+`DERIVEPASSPHRASE_PATH`
60 
+:   <b>derivepassphrase</b> stores its configuration files and data in this directory.
61 
+    Defaults to `~/.derivepassphrase` on UNIX-like systems and `C:\Users\<user>\AppData\Roaming\Derivepassphrase` on Windows.
39 62
40 
-<b>VAULT_PATH</b>
41 
-:   A default path, relative to the home directory, where to look for the
42 
-    configuration to load.
63 
+`VAULT_PATH`
64 
+:   A default path, relative to the home directory, where to look for the configuration to load.
43 65
44 
-<b>VAULT\_KEY</b>
45 
-:   A password with which the vault configuration is encrypted.  The
46 
-    password is interpreted as a UTF-8 byte string.
66 
+`VAULT_KEY`
67 
+:   A password with which the vault configuration is encrypted.
68 
+    The password is interpreted as a UTF-8 byte string.
47 69
48 
-<b>LOGNAME</b>, <b>USER</b>, <b>USERNAME</b>
70 
+`LOGNAME`, `USER`, `USERNAME`
49 71 
 :   Fallback values for `VAULT_KEY`.
50 72
73 
+## COMPATIBILITY
74 
+
75 
+### With other software
76 
+
77 
+<b>derivepassphrase export vault</b> fully supports reading the configuration formats used by <i>vault</i>(1) v0.3 and lower (formats `v0.2` and `v0.3`), as well as the `storeroom` format used in development builds after <i>vault</i>(1) v0.3 (`storeroom` version 1).
78 
+
79 
+There is no corresponding "import" subcommand, nor is there support for writing configuration files or directories in any of the aforementioned formats.
80 
+
51 81 
 ## SEE ALSO
52 82
53 
-[derivepassphrase(1)](derivepassphrase.1.md),
54 
-[vault(1)](https://www.npmjs.com/package/vault)
83 
+[<i>derivepassphrase</i>(1)](derivepassphrase.1.md),
84 
+[<i>vault</i>(1)](https://www.npmjs.com/package/vault).
85 
+
86 
+## AUTHOR
87 
+
88 
+[Marco Ricci](https://the13thletter.info) (`software` at `the13thletter` dot `info`)
89 
+
90 
+## BUGS
91 
+
92 
+  * There is no support for writing <i>vault</i>(1) configuration files or directories in any of the aforementioned formats.
93 
+
94 
+    WONTFIX: two-way interoperability of configuration file disk formats is currently out of scope.
95 
+    Use the standard `--import` and `--export` options of both <i>vault</i>(1) and <b>derivepassphrase vault</b>.
docs/reference/derivepassphrase-export.1.md
Zeige Datei @ a8c8e83
... ... 
@@ -2,37 +2,76 @@
2 2
3 3 
 ## NAME
4 4
5 
-derivepassphrase-export – export a foreign configuration to standard
6 
-output
5 
+derivepassphrase-export – export a foreign configuration to standard output
7 6
8 7 
 ## SYNOPSIS
9 8
10 9 
 ````
11 
-derivepassphrase export [SUBCOMMAND_ARGS]...
10 
+derivepassphrase export SUBCOMMAND_ARGS ...
12 11 
 ````
13 12
14 13 
 ## DESCRIPTION
15 14
16 
-Read a foreign system configuration, extract all information from
17 
-it, and export the resulting configuration to standard output.
18 
-
19 
-The only available subcommand is <b>vault</b>, which implements the
20 
-vault-native configuration scheme.  If no subcommand is given, we
21 
-default to <b>vault</b>.
15 
+Read a foreign system configuration, extract all information from it, and export the resulting configuration to standard output.
22 16
23 17 
 ## SUBCOMMANDS
24 18
25 19 
 [<b>vault</b>][VAULT_SUBCMD]
26 
-:    Export a vault-native configuration to standard output.
20 
+:    Export a <i>vault</i>(1)-native configuration to standard output.
21 
+
22 
+If no subcommand is given, we default to <b>vault</b>.
23 
+
24 
+## OPTIONS
25 
+
26 
+<b>-</b><b>-debug</b>
27 
+:   Emit all diagnostic information to standard error, including progress, warning and error messages.
28 
+
29 
+    Cancels the effect of any previous <b>-</b><b>-quiet</b> or <b>-</b><b>-verbose</b> options.
30 
+    Also applies to subcommands.
31 
+
32 
+<b>-v</b>, <b>-</b><b>-verbose</b>
33 
+:   Emit extra/progress information to standard error, on top of warning and error messages.
34 
+
35 
+    Cancels the effect of any previous <b>-</b><b>-debug</b> or <b>-</b><b>-quiet</b> options.
36 
+    Also applies to subcommands.
37 
+
38 
+<b>-q</b>, <b>-</b><b>-quiet</b>
39 
+:   Suppress all other diagnostic output to standard error, except error messages.
40 
+    This includes warning messages.
41 
+
42 
+    Cancels the effect of any previous <b>-</b><b>-debug</b> or <b>-</b><b>-verbose</b> options.
43 
+    Also applies to subcommands.
27 44
28 
-## DEPRECATION NOTICE
45 
+<b>-</b><b>-version</b>
46 
+:   Show the version and exit.
29 47
30 
-Defaulting to <b>vault</b> is deprecated.  Starting in v1.0, the
31 
-subcommand must be specified explicitly.
48 
+<b>-h</b>, <b>-</b><b>-help</b>
49 
+:   Show a help message and exit.
50 
+
51 
+## ENVIRONMENT
52 
+
53 
+`DERIVEPASSPHRASE_PATH`
54 
+:   <b>derivepassphrase</b> stores its configuration files and data in this directory.
55 
+    Defaults to `~/.derivepassphrase` on UNIX-like systems and `C:\Users\<user>\AppData\Roaming\Derivepassphrase` on Windows.
56 
+
57 
+## COMPATIBILITY
58 
+
59 
+### With other software
60 
+
61 
+See the respective subcommand's manpage for compatibility information.
62 
+
63 
+### Forward and backward compatibility
64 
+
65 
+  * [Since v0.2.0.] In v1.0, <b>derivepassphrase export</b> will require an explicit subcommand name.
66 
+    Defaults to the subcommand <b>vault</b>.
32 67
33 68 
 ## SEE ALSO
34 69
35 
-[derivepassphrase(1)](derivepassphrase.1.md),
36 
-[derivepassphrase-export-vault(1)]
70 
+[<i>derivepassphrase</i>(1)](derivepassphrase.1.md),
71 
+[<i>derivepassphrase-export-vault</i>(1)][VAULT_SUBCMD].
72 
+
73 
+## AUTHOR
74 
+
75 
+[Marco Ricci](https://the13thletter.info) (`software` at `the13thletter` dot `info`)
37 76
38 77 
 [VAULT_SUBCMD]: derivepassphrase-export-vault.1.md
docs/reference/derivepassphrase-vault.1.md
Zeige Datei @ a8c8e83
... ... 
@@ -158,6 +158,22 @@ The compatibility and extension options modify the behavior to enable additional
158 158
159 159 
 ### Other Options
160 160
161 
+<b>-</b><b>-debug</b>
162 
+:   Emit all diagnostic information to standard error, including progress, warning and error messages.
163 
+
164 
+    Cancels the effect of any previous <b>-</b><b>-quiet</b> or <b>-</b><b>-verbose</b> options.
165 
+
166 
+<b>-v</b>, <b>-</b><b>-verbose</b>
167 
+:   Emit extra/progress information to standard error, on top of warning and error messages.
168 
+
169 
+    Cancels the effect of any previous <b>-</b><b>-debug</b> or <b>-</b><b>-quiet</b> options.
170 
+
171 
+<b>-q</b>, <b>-</b><b>-quiet</b>
172 
+:   Suppress all other diagnostic output to standard error, except error messages.
173 
+    This includes warning messages.
174 
+
175 
+    Cancels the effect of any previous <b>-</b><b>-debug</b> or <b>-</b><b>-verbose</b> options.
176 
+
161 177 
 <b>-</b><b>-version</b>
162 178 
 :   Show the version and exit.
163 179
... ... 
@@ -427,9 +443,6 @@ Exceptions:
427 443
428 444 
 ### Forward and backward compatibility
429 445
430 
-  * [Since v0.2.0.]
431 
-    In v1.0, the commands <b>derivepassphrase</b> and <b>derivepassphrase export</b> will require an explicit subcommand name.
432 
-    Both default to the subcommand <b>vault</b>.
433 446 
   * [Since v0.2.0.]
434 447 
     In v1.0, the configuration data file for the <b>vault</b> subcommand will be named `vault.json`, instead of `config.json`.
435 448 
   * [Since v0.2.0, to be removed in v1.0.]
... ... 
@@ -448,6 +461,7 @@ Exceptions:
448 461
449 462 
 ## BUGS
450 463
451 
-  * The defaults are dictated by <i>vault</i>(1), necessitating the ["Compatibility and extension options"](#compatibility-and-extension-options). (WONTFIX.)
464 
+  * The defaults are dictated by <i>vault</i>(1), necessitating the ["Compatibility and extension options"](#compatibility-and-extension-options).
465 
+    (WONTFIX.)
452 466
453 467 
   * 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.
docs/reference/derivepassphrase.1.md
Zeige Datei @ a8c8e83
... ... 
@@ -2,31 +2,21 @@
2 2
3 3 
 ## NAME
4 4
5 
-derivepassphrase – derive a strong passphrase, deterministically, from
6 
-a master secret
5 
+derivepassphrase – derive a strong passphrase, deterministically, from a master secret
7 6
8 7 
 ## SYNOPSIS
9 8
10 9 
 ````
11 
-derivepassphrase [SUBCOMMAND_ARGS]...
10 
+derivepassphrase SUBCOMMAND_ARGS ...
12 11 
 ````
13 12
14 13 
 ## DESCRIPTION
15 14
16 
-Using a master secret, derive a passphrase for a named service,
17 
-subject to constraints e.g. on passphrase length, allowed
18 
-characters, etc.  The exact derivation depends on the selected
19 
-derivation scheme.  For each scheme, it is computationally
20 
-infeasible to discern the master secret from the derived passphrase.
21 
-The derivations are also deterministic, given the same inputs, thus
22 
-the resulting passphrases need not be stored explicitly.  The
23 
-service name and constraints themselves also generally need not be
24 
-kept secret, depending on the scheme.
25 
-
26 
-The currently implemented subcommands are <b>vault</b> (for the scheme
27 
-used by vault) and <b>export</b> (for exporting foreign configuration
28 
-data).  See the respective `--help` output for instructions.  If no
29 
-subcommand is given, we default to <b>vault</b>.
15 
+Using a master secret, derive a passphrase for a named service, subject to constraints e.g. on passphrase length, allowed characters, etc.
16 
+The exact derivation depends on the selected derivation scheme.
17 
+Each scheme derives *strong* passphrases by design: the derived passphrases have as much entropy as permitted by the master secret and the passphrase constraints (whichever is more restrictive), and even if multiple derived passphrases are compromised, the master secret remains cryptographically difficult to discern from those compromised passphrases.
18 
+The derivations are also deterministic, given the same inputs, thus the resulting passphrases need not be stored explicitly.
19 
+The service name and constraints themselves also generally need not be kept secret, depending on the scheme.
30 20
31 21 
 ## SUBCOMMANDS
32 22
... ... 
@@ -34,24 +24,65 @@ subcommand is given, we default to <b>vault</b>.
34 24 
 :   Export a foreign configuration to standard output.
35 25
36 26 
 [<b>vault</b>][VAULT_SUBCMD]
37 
-:   Derive a passphrase using the vault(1) derivation scheme.
27 
+:   Derive a passphrase using the <i>vault</i>(1) derivation scheme.
38 28
39 
-## DEPRECATION NOTICE
29 
+If no subcommand is given, we default to <b>vault</b>.
40 30
41 
-Defaulting to <b>vault</b> is deprecated.  Starting in v1.0, the
42 
-subcommand must be specified explicitly.
31 
+## OPTIONS
43 32
44 
-## CONFIGURATION
33 
+<b>-</b><b>-debug</b>
34 
+:   Emit all diagnostic information to standard error, including progress, warning and error messages.
45 35
46 
-Configuration is stored in a directory according to the
47 
-`$DERIVEPASSPHRASE_PATH` variable, which defaults to
48 
-`~/.derivepassphrase` on UNIX-like systems and
49 
-`C:\Users\<user>\AppData\Roaming\Derivepassphrase` on Windows.
36 
+    Cancels the effect of any previous <b>-</b><b>-quiet</b> or <b>-</b><b>-verbose</b> options.
37 
+    Also applies to subcommands.
38 
+
39 
+<b>-v</b>, <b>-</b><b>-verbose</b>
40 
+:   Emit extra/progress information to standard error, on top of warning and error messages.
41 
+
42 
+    Cancels the effect of any previous <b>-</b><b>-debug</b> or <b>-</b><b>-quiet</b> options.
43 
+    Also applies to subcommands.
44 
+
45 
+<b>-q</b>, <b>-</b><b>-quiet</b>
46 
+:   Suppress all other diagnostic output to standard error, except error messages.
47 
+    This includes warning messages.
48 
+
49 
+    Cancels the effect of any previous <b>-</b><b>-debug</b> or <b>-</b><b>-verbose</b> options.
50 
+    Also applies to subcommands.
51 
+
52 
+<b>-</b><b>-version</b>
53 
+:   Show the version and exit.
54 
+
55 
+<b>-h</b>, <b>-</b><b>-help</b>
56 
+:   Show a help message and exit.
57 
+
58 
+## ENVIRONMENT
59 
+
60 
+`DERIVEPASSPHRASE_PATH`
61 
+:   <b>derivepassphrase</b> stores its configuration files and data in this directory.
62 
+    Defaults to `~/.derivepassphrase` on UNIX-like systems and `C:\Users\<user>\AppData\Roaming\Derivepassphrase` on Windows.
63 
+
64 
+## COMPATIBILITY
65 
+
66 
+### With other software
67 
+
68 
+Some derivation schemes are based on other software.
69 
+See their respective manpages for compatibility information.
70 
+
71 
+Affected derivation schemes: <b>vault</b>.
72 
+
73 
+### Forward and backward compatibility
74 
+
75 
+  * [Since v0.2.0.] In v1.0, <b>derivepassphrase</b> will require an explicit subcommand name.
76 
+    Defaults to the subcommand <b>vault</b>.
50 77
51 78 
 ## SEE ALSO
52 79
53 
-[derivepassphrase-export(1)][EXPORT_SUBCMD],
54 
-[derivepassphrase-vault(1)][VAULT_SUBCMD]
80 
+[<i>derivepassphrase-export</i>(1)][EXPORT_SUBCMD],
81 
+[<i>derivepassphrase-vault</i>(1)][VAULT_SUBCMD].
82 
+
83 
+## AUTHOR
84 
+
85 
+[Marco Ricci](https://the13thletter.info) (`software` at `the13thletter` dot `info`)
55 86
56 87 
 [EXPORT_SUBCMD]: derivepassphrase-export.1.md
57 
-[VAULT_SUBCMD]: derivepassphrase-export.1.md
88 
+[VAULT_SUBCMD]: derivepassphrase-vault.1.md
man/derivepassphrase-export-vault.1
Zeige Datei @ a8c8e83
... ... 
@@ -0,0 +1,221 @@
1 
+.Dd 2025-01-11
2 
+.Dt DERIVEPASSPHRASE-EXPORT-VAULT 1
3 
+.Os derivepassphrase 0.4.0
4 
+.
5 
+.Sh NAME
6 
+.
7 
+.Nm derivepassphrase-export-vault
8 
+.Nd export a vault-native configuration to standard output
9 
+.
10 
+.Sh SYNOPSIS
11 
+.
12 
+.Bd -ragged
13 
+.Nm derivepassphrase export vault
14 
+.Op Fl f Ar FMT
15 
+.Op Fl k Ar K
16 
+.Ar PATH
17 
+.Ed
18 
+.
19 
+.Sh DESCRIPTION
20 
+.
21 
+Read the
22 
+.Xr vault 1 Ns -native
23 
+configuration at
24 
+.Ar PATH ,
25 
+extract all information from it, and export the resulting configuration to
26 
+standard output (as if using
27 
+.Xr vault 1 Ns 's
28 
+.Fl \-export
29 
+option).
30 
+Depending on the configuration format, this may either be a file or a
31 
+directory.
32 
+Supports the
33 
+.Xr vault 1
34 
+.Li v0.2 ,
35 
+.Li v0.3
36 
+and
37 
+.Li storeroom
38 
+formats, all of which inherently use encryption and integrity protection.
39 
+.Pp
40 
+.
41 
+If
42 
+.Ar PATH
43 
+is explicitly listed as
44 
+.Li VAULT_PATH ,
45 
+then use the
46 
+.Ev VAULT_PATH
47 
+environment variable to determine the correct path.
48 
+.Po
49 
+Use
50 
+.Pa ./VAULT_PATH
51 
+or similar to indicate a file/directory actually named
52 
+.Pa VAULT_PATH .
53 
+.Pc
54 
+.
55 
+.Sh OPTIONS
56 
+.
57 
+.Bl -tag -width ".Fl p , \-phrase"
58 
+.
59 
+.It Fl f , \-format Ar FMT
60 
+Try the storage format
61 
+.Ar FMT .
62 
+May be given multiple times; the formats will be tried in order.
63 
+.Pp
64 
+.
65 
+By default, we first try
66 
+.Li v0.3 ,
67 
+then
68 
+.Li v0.2 ,
69 
+and finally
70 
+.Li storeroom .
71 
+.
72 
+.It Fl k , \-key Ar K
73 
+Use
74 
+.Ar K
75 
+as the storage master key.
76 
+.Pp
77 
+.
78 
+By default, we check the
79 
+.Ev VAULT_KEY ,
80 
+.Ev LOGNAME ,
81 
+.Ev USER
82 
+and
83 
+.Ev USERNAME
84 
+environment variables, and use the first one with a proper value
85 
+.Pq Em and only the first one .
86 
+.
87 
+.It Fl \-debug
88 
+Emit all diagnostic information to standard error, including progress,
89 
+warning and error messages.
90 
+.Pp
91 
+.
92 
+Cancels the effect of any previous
93 
+.Fl \-quiet
94 
+or
95 
+.Fl \-verbose
96 
+options.
97 
+Also applies to subcommands.
98 
+.
99 
+.It Fl v , \-verbose
100 
+Emit extra/progress information to standard error, on top of warning and
101 
+error messages.
102 
+.Pp
103 
+.
104 
+Cancels the effect of any previous
105 
+.Fl \-debug
106 
+or
107 
+.Fl \-quiet
108 
+options.
109 
+Also applies to subcommands.
110 
+.
111 
+.It Fl q , \-quiet
112 
+Suppress all other diagnostic output to standard error, except error
113 
+messages.
114 
+.Pp
115 
+.
116 
+Cancels the effect of any previous
117 
+.Fl \-debug
118 
+or
119 
+.Fl \-verbose
120 
+options.
121 
+Also applies to subcommands.
122 
+.
123 
+.It Fl \-version
124 
+Show the version and exit.
125 
+.
126 
+.It Fl h , \-help
127 
+Show a help message and exit.
128 
+.
129 
+.El
130 
+.
131 
+.Sh ENVIRONMENT
132 
+.
133 
+.Bl -tag -width ".Fl p , \-phrase"
134 
+.
135 
+.It Ev DERIVEPASSPHRASE_PATH
136 
+.Nm derivepassphrase
137 
+stores its configuration files and data in this directory.
138 
+Defaults to
139 
+.Pa \(ti/.derivepassphrase
140 
+on UNIX-like systems and
141 
+.Pa C:\[rs]Users\[rs]<user>\[rs]AppData\[rs]Roaming\[rs]Derivepassphrase
142 
+on Windows.
143 
+.
144 
+.It Ev VAULT_PATH
145 
+A default path, relative to the home directory, where to look for the
146 
+configuration to load.
147 
+.
148 
+.It Ev VAULT_KEY
149 
+A password with which the vault configuration is encrypted.
150 
+The password is interpreted as a UTF-8 byte string.
151 
+.
152 
+.It Ev LOGNAME , USER , USERNAME
153 
+Fallback values for
154 
+.Ev VAULT_KEY .
155 
+.
156 
+.El
157 
+.
158 
+.Sh COMPATIBILITY
159 
+.
160 
+.Ss With other software
161 
+.
162 
+.Nm derivepassphrase export vault
163 
+fully supports reading the configuration formats used by
164 
+.Xr vault 1
165 
+v0.3 and lower
166 
+.Pq formats Li v0.2 No and Li v0.3 ,
167 
+as well as the
168 
+.Li storeroom
169 
+format used in development builds after
170 
+.Xr vault 1
171 
+v0.3
172 
+.Pq Li storeroom No version 1 .
173 
+.Pp
174 
+.
175 
+There is no corresponding
176 
+.Dq import
177 
+subcommand, nor is there support for writing configuration files or
178 
+directories in any of the aforementioned formats.
179 
+.
180 
+.Sh SEE ALSO
181 
+.
182 
+.Xr derivepassphrase 1 .
183 
+.Rs
184 
+.%A "James Coglan"
185 
+.%T "vault(1)"
186 
+.%U https://www.npmjs.com/package/vault
187 
+.Re
188 
+.Pp
189 
+.
190 
+Further online documentation for
191 
+.Xr derivepassphrase 1
192 
+.Pq tutorials, how-tos, reference and design documentation
193 
+is available at
194 
+.Lk https://the13thletter.info/derivepassphrase/ .
195 
+.
196 
+.Sh AUTHOR
197 
+.
198 
+.Lk mailto:software@the13thletter.info "Marco Ricci"
199 
+.
200 
+.Sh BUGS
201 
+.
202 
+.Bl -bullet
203 
+.It
204 
+There is no support for writing
205 
+.Xr vault 1
206 
+configuration files or directories in any of the aforementioned formats.
207 
+.Pp
208 
+WONTFIX: two-way interoperability of configuration file disk formats is
209 
+currently out of scope.
210 
+Use the standard
211 
+.Fl \-import
212 
+and
213 
+.Fl \-export
214 
+options of both
215 
+.Xr vault 1
216 
+and
217 
+.Nm derivepassphrase vault
218 
+.Ns .
219 
+.
220 
+.El
221 
+.
man/derivepassphrase-export.1
Zeige Datei @ a8c8e83
... ... 
@@ -0,0 +1,136 @@
1 
+.Dd 2025-01-11
2 
+.Dt DERIVEPASSPHRASE-EXPORT 1
3 
+.Os derivepassphrase 0.4.0
4 
+.
5 
+.Sh NAME
6 
+.
7 
+.Nm derivepassphrase-export
8 
+.Nd export a foreign configuration to standard output
9 
+.
10 
+.Sh SYNOPSIS
11 
+.
12 
+.Bd -ragged
13 
+.Nm derivepassphrase export
14 
+.Ar SUBCOMMAND_ARGS No .\|.\|.
15 
+.Ed
16 
+.
17 
+.Sh DESCRIPTION
18 
+.
19 
+Read a foreign system configuration, extract all information from it,
20 
+and export the resulting configuration to standard output.
21 
+.
22 
+.Sh SUBCOMMANDS
23 
+.
24 
+.Bl -tag -width ".Fl p , \-phrase"
25 
+.
26 
+.It Ar vault
27 
+Export a
28 
+.Xr vault 1
29 
+.Ns -native
30 
+configuration to standard output.
31 
+.
32 
+.El
33 
+.Pp
34 
+.
35 
+If no subcommand is given, we default to
36 
+.Ar vault .
37 
+.
38 
+.Sh OPTIONS
39 
+.
40 
+.Bl -tag -width ".Fl p , \-phrase"
41 
+.
42 
+.It Fl \-debug
43 
+Emit all diagnostic information to standard error, including progress,
44 
+warning and error messages.
45 
+.Pp
46 
+.
47 
+Cancels the effect of any previous
48 
+.Fl \-quiet
49 
+or
50 
+.Fl \-verbose
51 
+options.
52 
+Also applies to subcommands.
53 
+.
54 
+.It Fl v , \-verbose
55 
+Emit extra/progress information to standard error, on top of warning and
56 
+error messages.
57 
+.Pp
58 
+.
59 
+Cancels the effect of any previous
60 
+.Fl \-debug
61 
+or
62 
+.Fl \-quiet
63 
+options.
64 
+Also applies to subcommands.
65 
+.
66 
+.It Fl q , \-quiet
67 
+Suppress all other diagnostic output to standard error, except error
68 
+messages.
69 
+.Pp
70 
+.
71 
+Cancels the effect of any previous
72 
+.Fl \-debug
73 
+or
74 
+.Fl \-verbose
75 
+options.
76 
+Also applies to subcommands.
77 
+.
78 
+.It Fl \-version
79 
+Show the version and exit.
80 
+.
81 
+.It Fl h , \-help
82 
+Show a help message and exit.
83 
+.
84 
+.El
85 
+.
86 
+.Sh ENVIRONMENT
87 
+.
88 
+.Bl -tag -width ".Fl p , \-phrase"
89 
+.
90 
+.It Ev DERIVEPASSPHRASE_PATH
91 
+.Nm derivepassphrase
92 
+stores its configuration files and data in this directory.
93 
+Defaults to
94 
+.Pa \(ti/.derivepassphrase
95 
+on UNIX-like systems and
96 
+.Pa C:\[rs]Users\[rs]<user>\[rs]AppData\[rs]Roaming\[rs]Derivepassphrase
97 
+on Windows.
98 
+.
99 
+.El
100 
+.
101 
+.Sh COMPATIBILITY
102 
+.
103 
+.Ss With other software
104 
+.
105 
+See the respective subcommand's manpage for compatibility information.
106 
+.
107 
+.Ss Forward and backward compatibility
108 
+.
109 
+.Bl -bullet
110 
+.
111 
+.It
112 
+.Bo Since v0.2.0 . Bc
113 
+In v1.0,
114 
+.Nm derivepassphrase export
115 
+will require an explicit subcommand name.
116 
+Defaults to the subcommand
117 
+.Ic vault .
118 
+.
119 
+.El
120 
+.
121 
+.Sh SEE ALSO
122 
+.
123 
+.Xr derivepassphrase 1 ,
124 
+.Xr derivepassphrase-export-vault 1 .
125 
+.Pp
126 
+.
127 
+Further online documentation for
128 
+.Xr derivepassphrase 1
129 
+.Pq tutorials, how-tos, reference and design documentation
130 
+is available at
131 
+.Lk https://the13thletter.info/derivepassphrase/ .
132 
+.
133 
+.Sh AUTHOR
134 
+.
135 
+.Lk mailto:software@the13thletter.info "Marco Ricci"
136 
+.
man/derivepassphrase-vault.1
Zeige Datei @ a8c8e83
... ... 
@@ -1,4 +1,4 @@
1 
-.Dd 2025-01-07
1 
+.Dd 2025-01-11
2 2 
 .Dt DERIVEPASSPHRASE-VAULT 1
3 3 
 .Os derivepassphrase 0.4.0
4 4 
 .
... ... 
@@ -408,6 +408,42 @@ were always given.)
408 408 
 .
409 409 
 .Bl -tag -width ".Fl p , \-phrase"
410 410 
 .
411 
+.It Fl \-debug
412 
+Emit all diagnostic information to standard error, including progress,
413 
+warning and error messages.
414 
+.Pp
415 
+.
416 
+Cancels the effect of any previous
417 
+.Fl \-quiet
418 
+or
419 
+.Fl \-verbose
420 
+options.
421 
+Also applies to subcommands.
422 
+.
423 
+.It Fl v , \-verbose
424 
+Emit extra/progress information to standard error, on top of warning and
425 
+error messages.
426 
+.Pp
427 
+.
428 
+Cancels the effect of any previous
429 
+.Fl \-debug
430 
+or
431 
+.Fl \-quiet
432 
+options.
433 
+Also applies to subcommands.
434 
+.
435 
+.It Fl q , \-quiet
436 
+Suppress all other diagnostic output to standard error, except error
437 
+messages.
438 
+.Pp
439 
+.
440 
+Cancels the effect of any previous
441 
+.Fl \-debug
442 
+or
443 
+.Fl \-verbose
444 
+options.
445 
+Also applies to subcommands.
446 
+.
411 447 
 .It Fl \-version
412 448 
 Show the version and exit.
413 449 
 .
... ... 
@@ -887,16 +923,6 @@ can read both these formats and export the contents.)
887 923 
 .
888 924 
 .It
889 925 
 .Bo Since v0.2.0 . Bc
890 
-In v1.0, the commands
891 
-.Nm derivepassphrase
892 
-and
893 
-.Nm derivepassphrase export
894 
-will require an explicit subcommand name.
895 
-Both default to the subcommand
896 
-.Ic vault .
897 
-.
898 
-.It
899 
-.Bo Since v0.2.0 . Bc
900 926 
 In v1.0, the configuration data file for the
901 927 
 .Ic vault
902 928 
 subcommand will be named
man/derivepassphrase.1
Zeige Datei @ a8c8e83
... ... 
@@ -0,0 +1,157 @@
1 
+.Dd 2025-01-11
2 
+.Dt DERIVEPASSPHRASE 1
3 
+.Os derivepassphrase 0.4.0
4 
+.
5 
+.Sh NAME
6 
+.
7 
+.Nm derivepassphrase
8 
+.Nd derive a strong passphrase, deterministically, from a master secret
9 
+.
10 
+.Sh SYNOPSIS
11 
+.
12 
+.Bd -ragged
13 
+.Nm derivepassphrase
14 
+.Ar SUBCOMMAND_ARGS No .\|.\|.
15 
+.Ed
16 
+.
17 
+.Sh DESCRIPTION
18 
+.
19 
+Using a master secret, derive a passphrase for a named service, subject to
20 
+constraints e.g.\& on passphrase length, allowed characters, etc.
21 
+The exact derivation depends on the selected derivation scheme.
22 
+Each scheme derives
23 
+.Em strong
24 
+passphrases by design:
25 
+the derived passphrases have as much entropy as permitted by the master secret
26 
+and the passphrase constraints
27 
+.Pq whichever is more restrictive ,
28 
+and even if multiple derived passphrases are compromised, the master secret
29 
+remains cryptographically difficult to discern from those compromised
30 
+passphrases.
31 
+The derivations are also deterministic, given the same inputs, thus the
32 
+resulting passphrsases need not be stored explicitly.
33 
+The service name and constraints themselves also generally need not be kept
34 
+secret, depending on the scheme.
35 
+.
36 
+.Sh SUBCOMMANDS
37 
+.
38 
+.Bl -tag -width ".Fl p , \-phrase"
39 
+.
40 
+.It Ar export
41 
+Export a foreign configuration to standard output.
42 
+.
43 
+.It Ar vault
44 
+Derive a passphrase using the
45 
+.Xr vault 1
46 
+derivation scheme.
47 
+.
48 
+.El
49 
+.Pp
50 
+.
51 
+If no subcommand is given, we default to
52 
+.Ar vault .
53 
+.
54 
+.Sh OPTIONS
55 
+.
56 
+.Bl -tag -width ".Fl p , \-phrase"
57 
+.
58 
+.It Fl \-debug
59 
+Emit all diagnostic information to standard error, including progress,
60 
+warning and error messages.
61 
+.Pp
62 
+.
63 
+Cancels the effect of any previous
64 
+.Fl \-quiet
65 
+or
66 
+.Fl \-verbose
67 
+options.
68 
+Also applies to subcommands.
69 
+.
70 
+.It Fl v , \-verbose
71 
+Emit extra/progress information to standard error, on top of warning and
72 
+error messages.
73 
+.Pp
74 
+.
75 
+Cancels the effect of any previous
76 
+.Fl \-debug
77 
+or
78 
+.Fl \-quiet
79 
+options.
80 
+Also applies to subcommands.
81 
+.
82 
+.It Fl q , \-quiet
83 
+Suppress all other diagnostic output to standard error, except error
84 
+messages.
85 
+.Pp
86 
+.
87 
+Cancels the effect of any previous
88 
+.Fl \-debug
89 
+or
90 
+.Fl \-verbose
91 
+options.
92 
+Also applies to subcommands.
93 
+.
94 
+.It Fl \-version
95 
+Show the version and exit.
96 
+.
97 
+.It Fl h , \-help
98 
+Show a help message and exit.
99 
+.
100 
+.El
101 
+.
102 
+.Sh ENVIRONMENT
103 
+.
104 
+.Bl -tag -width ".Fl p , \-phrase"
105 
+.
106 
+.It Ev DERIVEPASSPHRASE_PATH
107 
+.Nm derivepassphrase
108 
+stores its configuration files and data in this directory.
109 
+Defaults to
110 
+.Pa \(ti/.derivepassphrase
111 
+on UNIX-like systems and
112 
+.Pa C:\[rs]Users\[rs]<user>\[rs]AppData\[rs]Roaming\[rs]Derivepassphrase
113 
+on Windows.
114 
+.
115 
+.El
116 
+.
117 
+.Sh COMPATIBILITY
118 
+.
119 
+.Ss With other software
120 
+.
121 
+Some derivation schemes are based on other software.
122 
+See their respective manpages for compatibility information.
123 
+.Pp
124 
+.
125 
+Affected derivation schemes:
126 
+.Ar vault .
127 
+.
128 
+.Ss Forward and backward compatibility
129 
+.
130 
+.Bl -bullet
131 
+.
132 
+.It
133 
+.Bo Since v0.2.0 . Bc
134 
+In v1.0,
135 
+.Nm derivepassphrase
136 
+will require an explicit subcommand name.
137 
+Defaults to the subcommand
138 
+.Ic vault .
139 
+.
140 
+.El
141 
+.
142 
+.Sh SEE ALSO
143 
+.
144 
+.Xr derivepassphrase-export 1 ,
145 
+.Xr derivepassphrase-vault 1 .
146 
+.Pp
147 
+.
148 
+Further online documentation for
149 
+.Xr derivepassphrase 1
150 
+.Pq tutorials, how-tos, reference and design documentation
151 
+is available at
152 
+.Lk https://the13thletter.info/derivepassphrase/ .
153 
+.
154 
+.Sh AUTHOR
155 
+.
156 
+.Lk mailto:software@the13thletter.info "Marco Ricci"
157 
+.
0 158