derivepassphrase.git

Demonstrate config storing and SSH agent use in README
Parent 24ec5f4
Marco Ricci

Marco Ricci commited on 2024-09-15 00:05:31
Zeige 1 geänderte Dateien mit 47 Einfügungen und 3 Löschungen. 

The README now shows a session where the user stores passphrase
derivation settings for a service, and where the user uses an SSH key
for passphrase derivation.

This also makes for a good opportunity to highlight the flaky Windows
support for the SSH agent: because `derivepassphrase` expects to talk to
the SSH agent directly, via a UNIX domain socket, it is unlikely to work
on Windows out of the box because (a) support for UNIX domain sockets is
only available in Windows 10 and higher (ca. 2021), and (b) the two
major SSH agent implementations Pageant (PuTTY) and OpenSSH for Windows
(via the Windows Subsystem for Linux) do not use UNIX domain sockets on
Windows.  See https://github.com/the-13th-letter/issues/13 for details.
README.md
Zeige Datei @ 7aa5f56
... ... 
@@ -44,9 +44,13 @@ Using the `export vault` subcommand additionally requires the [cryptography pack
44 44
45 45 
 ## Quick Usage
46 46
47 
+`derivepassphrase` is designed to principally support multiple passphrase derivation schemes, but currently only the "[vault][VAULT]" scheme is implemented.
48 
+
49 
+Using the passphrase `This passphrase is for demonstration purposes only.` when prompted:
50 
+
47 51 
 ```` shell-session
48 52 
 $ derivepassphrase vault -p --length 30 --upper 3 --lower 1 --number 2 --space 0 --symbol 0 my-email-account
49 
-Passphrase: This passphrase is for demonstration purposes only.
53 
+Passphrase:
50 54 
 JKeet7GeBpxysOgdCEJo6UzmP8A0Ih
51 55 
 ````
52 56
... ... 
@@ -54,11 +58,51 @@ Some time later…
54 58
55 59 
 ```` shell-session
56 60 
 $ derivepassphrase vault -p --length 30 --upper 3 --lower 1 --number 2 --space 0 --symbol 0 my-email-account
57 
-Passphrase: This passphrase is for demonstration purposes only.
61 
+Passphrase:
58 62 
 JKeet7GeBpxysOgdCEJo6UzmP8A0Ih
59 63 
 ````
60 64
61 
-(The user input `This passphrase is for demonstration purposes only.` for the passphrase prompt is not actually displayed on-screen.)
65 
+### Storing settings
66 
+
67 
+`derivepassphrase` can store the length and character constraint settings in its configuration file so that you do not have to re-enter them each time.
68 
+
69 
+```` shell-session
70 
+$ derivepassphrase vault --config --length 30 --upper 3 --lower 1 --number 2 --space 0 --symbol 0 my-email-account
71 
+$ derivepassphrase vault -p my-email-account
72 
+Passphrase:
73 
+JKeet7GeBpxysOgdCEJo6UzmP8A0Ih
74 
+````
75 
+
76 
+### SSH agent support
77 
+
78 
+On UNIX-like systems with OpenSSH or PuTTY installed, you can use an Ed25519, Ed448 or RSA key from the agent instead of a master passphrase.
79 
+([On Windows there are problems establishing communication channels with the agent.][#13])
80 
+
81 
+```` shell-session
82 
+$ derivepassphrase vault -k my-email-account
83 
+Suitable SSH keys:
84 
+[1] ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQ... test key
85 
+[2] ssh-ed448 AAAACXNzaC1lZDQ0OAAAADni9nLTT1... test key
86 
+[3] ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIF4gW... test key
87 
+Your selection? (1-3, leave empty to abort): 1
88 
+oXDGCvMhLWPQyCzYtaobOq2Wh9olYj
89 
+````
90 
+
91 
+`derivepassphrase` can store the SSH key selection in its configuration file so you do not have to re-select it each time.
92 
+This choice can be made either specifically for the service (in this case, `my-email-account`), or globally.
93 
+
94 
+```` shell-session
95 
+$ derivepassphrase vault --config -k  # global setting
96 
+Suitable SSH keys:
97 
+[1] ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQ... test key
98 
+[2] ssh-ed448 AAAACXNzaC1lZDQ0OAAAADni9nLTT1... test key
99 
+[3] ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIF4gW... test key
100 
+Your selection? (1-3, leave empty to abort): 1
101 
+$ derivepassphrase vault my-email-account
102 
+oXDGCvMhLWPQyCzYtaobOq2Wh9olYj
103 
+````
104 
+
105 
+[#13]: https://github.com/the-13th-letter/derivepassphrase/issues/13 "Issue 13: Support PuTTY/Pageant (and maybe OpenSSH/ssh-agent) on Windows"
62 106
63 107 
 ## License
64 108
65 109