derivepassphrase.git

1) # How to set up `derivepassphrase vault` with an SSH key
2) 
3) !!! abstract "See also"
4) 
5)     → Tradeoffs between a master passphrase and a master SSH key (TODO)
6) 

7) ## Prerequisites
8) 
9) !!! abstract "Further reading"
10) 
11)     → Full technical details: [Prerequisites for using `derivepassphrase
12)     vault` with an SSH key][PREREQ]
13) 
14)  1. A running SSH agent; typically provided by OpenSSH or PuTTY.
15)  2. A Python installation that can talk to the SSH agent.
16)  3. A supported SSH key; typically an RSA, Ed25519 or Ed448 key.

17) 
18) ## Configuring `derivepassphrase vault` to use an SSH key
19) 

20) Assuming the prerequisites are satisfied, ensure that the SSH agent is
21) running, the SSH key is loaded into the agent, and the `SSH_AUTH_SOCK`
22) environment variable is correctly set up.  The exact commands depend on
23) the SSH agent in use.

24) 
25) === "OpenSSH"
26) 

27)     ~~~~ console title="Typical setup commands: starting the agent and setting up SSH_AUTH_SOCK"

28)     $ eval `ssh-agent -s`
29)     Agent pid 12345

30)     ~~~~
31) 
32)     (The process ID emitted above is helpful for signalling the agent
33)     later, e.g. for termination.)
34) 
35)     ~~~~ console title="Typical setup commands: loading the key into the agent, with 900s timeout and requiring confirmation"

36)     $ ssh-add -t 900 -c ~/.ssh/my-vault-ed25519-key
37)     Enter passphrase for /home/user/.ssh/my-vault-ed25519-key (will confirm each use): 
38)     Identity added: /home/user/.ssh/my-vault-ed25519-key (vault key)
39)     Lifetime set to 900 seconds
40)     The user must confirm each use of the key
41)     ~~~~
42) 

43)     (Your key filename and key comment will likely differ.)
44) 

45) === "PuTTY"
46) 

47)     ~~~~ console title="Typical setup commands: starting the agent and loading the key"

48)     $ eval `pageant -T ~/.ssh/my-vault-ed25519-key.ppk`
49)     Enter passphrase to load key 'vault key': 
50)     ~~~~
51) 

52)     (Your key filename and key comment will likely differ.  The agent
53)     should automatically shut down once this terminal session is over.)

54) 

55) === "GnuPG"

56) 

57)     ~~~~ console title="Typical setup commands: enabling SSH agent support in GnuPG"
58)     $ # This is equivalent to passing --enable-ssh-support upon agent
59)     $ # startup.

60)     $ echo enable-ssh-support:0:1 | gpgconf --change-options gpg-agent

61)     ~~~~
62) 
63)     (Loading native SSH keys into `gpg-agent` requires a separate SSH
64)     agent client such as OpenSSH; see the [agent-specific notes in the
65)     prerequisites][PREREQ_AGENT_SPECIFIC_NOTES].)
66) 
67)     ~~~~ console title="Typical setup commands: loading the key into the agent with the OpenSSH tools"

68)     $ ssh-add -c ~/.ssh/my-vault-ed25519-key
69)     Enter passphrase for /home/user/.ssh/my-vault-ed25519-key (will confirm each use): 
70)     Identity added: /home/user/.ssh/my-vault-ed25519-key (vault key)
71)     The user must confirm each use of the key
72)     ~~~~
73) 

74)     (Your key filename and key comment may differ.)
75) 
76) Next, configure `derivepassphrase vault` to use the loaded SSH key.

77) 
78) === "global key"
79) 
80)     ~~~~ console

81)     $ derivepassphrase vault --config -k
82)     Suitable SSH keys:

83)     [1] ssh-rsa ...feXycsvJZ2uaYRjMdZeJGNAnHLUGLkBscw5aI8=  test key without passphrase
84)     [2] ssh-ed448 ...BQ72ZgtPMckdzabiz7JbM/b0JzcRzGLMsbwA=  test key without passphrase
85)     [3] ssh-ed25519 ...gJIXw//Mkhv5MEwidwcakUGCekJD/vCEml2  test key without passphrase

86)     Your selection? (1-3, leave empty to abort): 3

87)     ~~~~
88) 

89)     (The prompt text will be "Use this key?" instead if there is only one
90)     suitable key.)
91) 

92)     Now `derivepassphrase vault` will automatically use the configured
93)     key globally, even without the `-k`/`--key` option.
94) 
95) === "key specifically for <var>SERVICE</var>"
96) 
97)     ~~~~ console

98)     $ derivepassphrase vault --config -k SERVICE
99)     Suitable SSH keys:

100)     [1] ssh-rsa ...feXycsvJZ2uaYRjMdZeJGNAnHLUGLkBscw5aI8=  test key without passphrase
101)     [2] ssh-ed448 ...BQ72ZgtPMckdzabiz7JbM/b0JzcRzGLMsbwA=  test key without passphrase
102)     [3] ssh-ed25519 ...gJIXw//Mkhv5MEwidwcakUGCekJD/vCEml2  test key without passphrase

103)     Your selection? (1-3, leave empty to abort): 3

104)     ~~~~
105) 

106)     (The prompt text will be "Use this key?" instead if there is only one
107)     suitable key.)
108) 

109)     Now `derivepassphrase vault` will automatically use the configured
110)     key for <var>SERVICE</var>, even without the `-k`/`--key` option.
111)