derivepassphrase.git

Add rendered man page for derivepassphrase(1)
Parent c35b834
Marco Ricci

Marco Ricci commited on 2024-07-14 10:57:59
Zeige 3 geänderte Dateien mit 134 Einfügungen und 7 Löschungen. 

Converted and formatted by hand from the `--help` output, because
`click-man`, which would generally be used for this purpose, is quasi
abandonware as of July 2024, and generates horrible quality results.
docs/reference.md
Zeige Datei @ 284f2b7
... ... 
@@ -1,13 +1,18 @@
1 
-# API reference
1 
+Man pages:
2 
+
3 
+Item                             | Description
4 
+-------------------------------- | ---------------------------------------------------------------
5 
+[`derivepassphrase(1)`][dpp_man] | A deterministic, stateless password manager: command-line tool.
2 6
3 7 
 Top-level modules:
4 8
5 9 
 Module                           | Description
6 
------------------------ | --------------------------------------------------------------------
7 
-[`derivepassphrase`][]  | Work-alike for vault(1) - deterministic, stateless password manager.
10 
+-------------------------------- | --------------------------------------------------------------------
11 
+[`derivepassphrase`][dpp_module] | Work-alike for vault(1) - deterministic, stateless password manager.
8 12 
 [`sequin`][]                     | Python port of Sequin, a pseudorandom number generator.
9 13 
 [`ssh_agent_client`][]           | A bare-bones SSH agent client supporting signing and key listing.
10 14
11 
-  [derivepassphrase]: reference/derivepassphrase.md
15 
+  [dpp_man]: reference/derivepassphrase.1.md
16 
+  [dpp_module]: reference/derivepassphrase.md
12 17 
   [sequin]: reference/sequin.md
13 18 
   [ssh_agent_client]: reference/ssh_agent_client.md
docs/reference/derivepassphrase.1.md
Zeige Datei @ 284f2b7
... ... 
@@ -0,0 +1,121 @@
1 
+# derivepassphrase(1)
2 
+
3 
+## NAME
4 
+
5 
+derivepassphrase – derive a strong passphrase, deterministically, from
6 
+a master secret
7 
+
8 
+## SYNOPSIS
9 
+
10 
+````
11 
+derivepassphrase [OPTIONS] [SERVICE]
12 
+````
13 
+
14 
+## DESCRIPTION
15 
+
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.
25 
+
26 
+If operating on global settings, or importing/exporting settings, then
27 
+<i>SERVICE</i> must be omitted.  Otherwise it is required.
28 
+
29 
+## OPTIONS
30 
+
31 
+### Password generation
32 
+
33 
+<b>-p</b>, <b>-</b><b>-phrase</b>
34 
+:   prompts you for your passphrase
35 
+
36 
+<b>-k</b>, <b>-</b><b>-key</b>
37 
+:   uses your SSH private key to generate passwords
38 
+
39 
+<b>-l</b>, <b>-</b><b>-length</b> <var>NUMBER</var>
40 
+:   emits password of length <var>NUMBER</var>
41 
+
42 
+<b>-r</b>, <b>-</b><b>-repeat</b> <var>NUMBER</var>
43 
+:   allows maximum of <var>NUMBER</var> repeated adjacent chars
44 
+
45 
+<b>-</b><b>-lower</b> <var>NUMBER</var>
46 
+:   includes at least <var>NUMBER</var> lowercase letters
47 
+
48 
+<b>-</b><b>-upper</b> <var>NUMBER</var>
49 
+:   includes at least <var>NUMBER</var> uppercase letters
50 
+
51 
+<b>-</b><b>-number</b> <var>NUMBER</var>
52 
+:   includes at least <var>NUMBER</var> digits
53 
+
54 
+<b>-</b><b>-space</b> <var>NUMBER</var>
55 
+:   includes at least <var>NUMBER</var> spaces
56 
+
57 
+<b>-</b><b>-dash</b> <var>NUMBER</var>
58 
+:   includes at least <var>NUMBER</var> `-` or `_`
59 
+
60 
+<b>-</b><b>-symbol</b> <var>NUMBER</var>
61 
+:   includes at least <var>NUMBER</var> symbol chars
62 
+
63 
+Use <var>NUMBER</var>=0, e.g. `--symbol 0`, to exclude a character type from
64 
+the output.
65 
+
66 
+### Configuration
67 
+
68 
+<b>-n</b>, <b>-</b><b>-notes</b>
69 
+:   spawn an editor to edit notes for <var>SERVICE</var>
70 
+
71 
+<b>-c</b>, <b>-</b><b>-config</b>
72 
+:   saves the given settings for <var>SERVICE</var> or global
73 
+
74 
+<b>-x</b>, <b>-</b><b>-delete</b>
75 
+:   deletes settings for <var>SERVICE</var>
76 
+
77 
+<b>-</b><b>-delete-globals</b>
78 
+:   deletes the global shared settings
79 
+
80 
+<b>-X</b>, <b>-</b><b>-clear</b>
81 
+:   deletes all settings
82 
+
83 
+Use `$VISUAL` or `$EDITOR` to configure the spawned editor.
84 
+
85 
+### Storage management
86 
+
87 
+<b>-e</b>, <b>-</b><b>-export</b> <var>PATH</var>
88 
+:   export all saved settings into file <var>PATH</var>
89 
+
90 
+<b>-i</b>, <b>-</b><b>-import</b> <var>PATH</var>
91 
+:   import saved settings from file <var>PATH</var>
92 
+
93 
+Using `-` as <var>PATH</var> for standard input/standard output is supported.
94 
+
95 
+### Other Options
96 
+
97 
+<b>--version</b>
98 
+:   Show the version and exit.
99 
+
100 
+<b>-h</b>, <b>-</b><b>-help</b>
101 
+:   Show this message and exit.
102 
+
103 
+## WARNINGS
104 
+
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.
110 
+
111 
+## CONFIGURATION
112 
+
113 
+Configuration is stored in a directory according to the
114 
+`$DERIVEPASSPHRASE_PATH` variable, which defaults to `~/.derivepassphrase` on
115 
+UNIX-like systems and `C:\Users\<user>\AppData\Roaming\Derivepassphrase` on
116 
+Windows. The configuration is **not** encrypted, and you are **strongly**
117 
+discouraged from using a stored passphrase.
118 
+
119 
+## SEE ALSO
120 
+
121 
+[vault(1)](https://github.com/jcoglan/vault)
mkdocs.yml
Zeige Datei @ 284f2b7
... ... 
@@ -79,15 +79,16 @@ plugins:
79 79
80 80 
 nav:
81 81 
   - Overview: index.md
82 
-  #- tutorials.md
82 
+  #- Tutorials & Examples: tutorials.md
83 83 
   #- How-Tos: how-tos.md
84 84 
   - Reference:
85 
-    - API overview: reference.md
85 
+    - Reference overview: reference.md
86 
+    - 'Man page: derivepassphrase': reference/derivepassphrase.1.md
86 87 
     - Module derivepassphrase: reference/derivepassphrase.md
87 88 
     - Module sequin: reference/sequin.md
88 89 
     - Module ssh_agent_client: reference/ssh_agent_client.md
89 90 
     - Coverage: reference/coverage/index.html
90 
-  #- explanation.md
91 
+  #- Design & Background: explanation.md
91 92
92 93 
 markdown_extensions:
93 94 
   - abbr
94 95