1---
2layout: "docs"
3page_title: "Dynamic SSH Keys - SSH - Secrets Engines"
4sidebar_title: "Dynamic Key"
5sidebar_current: "docs-secrets-ssh-dynamic-ssh-keys"
6description: |-
7  When using this type, the administrator registers a secret key with
8  appropriate sudo privileges on the remote machines. For every authorized
9  credential request, Vault creates a new SSH key pair and appends the
10  newly-generated public key to the authorized_keys file for the configured
11  username on the remote host. Vault uses a configurable install script to
12  achieve this.
13---
14
15# Dynamic SSH Keys
16
17~> **Deprecated**: There are several serious drawbacks and security implications
18inherent in this type. Because of these drawbacks, please use the SSH CA or OTP
19types whenever possible.
20
21When using this type, the administrator registers a secret key with appropriate
22`sudo` privileges on the remote machines; for every authorized credential
23request, Vault creates a new SSH key pair and appends the newly-generated public
24key to the `authorized_keys` file for the configured username on the remote
25host. Vault uses a configurable install script to achieve this.
26
27The secrets engine does not prompt for `sudo` passwords; the `NOPASSWD` option for
28sudoers should be enabled at all remote hosts for the Vault administrative
29user.
30
31The private key returned to the user will be leased and can be renewed if
32desired. Once the key is given to the user, Vault will not know when it gets
33used or how many time it gets used. Therefore, Vault **WILL NOT** and cannot
34audit the SSH session establishments.
35
36When the credential lease expires, Vault removes the secret key from the remote
37machine.
38
39This page will show a quick start for this secrets engine. For detailed documentation
40on every path, use `vault path-help` after mounting the secrets engine.
41
42### Drawbacks
43
44The dynamic key type has several serious drawbacks:
45
461. _Audit logs are unreliable_: Vault can only log when users request
47   credentials, not when they use the given keys. If user A and user B both
48   request access to a machine, and are given a lease valid for five minutes,
49   it is impossible to know whether two accesses to that user account on the
50   remote machine were A, A; A, B; B, A; or B, B.
512. _Generating dynamic keys consumes entropy_: Unless equipped with a hardware
52   entropy generating device, a machine can quickly run out of entropy when
53   generating SSH keys. This will cause further requests for various Vault
54   operations to stall until more entropy is available, which could take a
55   significant amount of time, after which the next request for a new SSH key
56   will use the generated entropy and cause stalling again.
573. This type makes connections to client hosts; when this happens the host key
58   is *not* verified.
59
60### sudo
61
62In order to adjust the `authorized_keys` file for the desired user, Vault
63connects via SSH to the remote machine as a separate user, and uses `sudo` to
64gain the privileges required. An example `sudoers` file is shown below.
65
66File: `/etc/sudoers`
67
68```hcl
69# This is a sample sudoers statement; you should modify it
70# as appropriate to satisfy your security needs.
71vaultadmin   ALL=(ALL)NOPASSWD: ALL
72```
73
74### Configuration
75
76Next, infrastructure configuration must be registered with Vault via roles.
77First, however, the shared secret key must be specified.
78
79### Mount the secrets engine
80
81```text
82$ vault secrets enable ssh
83Successfully mounted 'ssh' at 'ssh'!
84```
85
86#### Registering the shared secret key
87
88Register a key with a name; this key must have administrative capabilities on
89the remote hosts.
90
91```text
92$ vault write ssh/keys/dev_key \
93    key=@dev_shared_key.pem
94```
95
96#### Create a Role
97
98Next, create a role. All of the machines contained within this CIDR block list
99should be accessible using the registered shared secret key.
100
101```text
102$ vault write ssh/roles/dynamic_key_role \
103    key_type=dynamic \
104    key=dev_key \
105    admin_user=username \
106    default_user=username \
107    cidr_list=x.x.x.x/y
108Success! Data written to: ssh/roles/dynamic_key_role
109```
110
111`cidr_list` is a comma separated list of CIDR blocks for which a role can
112generate credentials. If this is empty, the role can only generate credentials
113if it belongs to the set of zero-address roles.
114
115Zero-address roles, configured via `/ssh/config/zeroaddress` endpoint, takes
116comma separated list of role names that can generate credentials for any IP
117address.
118
119Use the `install_script` option to provide an install script if the remote
120hosts do not resemble a typical Linux machine. The default script is compiled
121into the Vault binary, but it is straight forward to specify an alternate.  The
122script takes three arguments which are explained in the comments.
123
124To see the default, see
125[linux_install_script.go](https://github.com/hashicorp/vault/blob/master/builtin/logical/ssh/linux_install_script.go)
126
127### Create a credential
128
129Create a dynamic key for an IP of the remote host that is covered by
130`dynamic_key_role`'s CIDR list.
131
132```text
133$ vault write ssh/creds/dynamic_key_role ip=x.x.x.x
134Key            	Value
135lease_id       	ssh/creds/dynamic_key_role/8c4d2042-23bc-d6a8-42c2-6ff01cb83cf8
136lease_duration 	600
137lease_renewable	true
138ip             	x.x.x.x
139key            	-----BEGIN RSA PRIVATE KEY-----
140MIIEpAIBAAKCAQEA5V/Y95qfGaUXRPkKNK9jgDHXPD2n5Ein+QTNnLSGrHtJUH7+
141pgs/5Hc4//124P9qHNmjIYQVyvcLreFgSrQCq4K8193hmypBYtsvCgvpc+jEwaGA
142zK0QV7uc1z8KL7FuRAxpHJwB6+nubOzzqM03xsViHRhaWhYVHw2Vl4oputSHE7R9
143ugaTRg67wge4Nyi5RRL0RQcmW15/Vop8B6HpBSmZQy3enjg+32KbOWCMMTAPuF9/
144DgxSgZQaFMjGN4RjDreZI8Vv5zIiFJzZ3KVOWy8piI0PblLnDpU4Q0QSQ9A+Vr7b
145JS22Lbet1Zbapl/n947/r1wGObLCc5Lilu//1QIDAQABAoIBAHWLfdO9sETjHp6h
146BULkkpgScpuTeSN6vGHXvUrOFKn1cCfJPNR4tWBuXI6LJM2+9nEccwXs+4IMwjZ0
147ZfVCdI/SKtZxBXmP2PxBGMUMP7G/mn0kN64sDlD3ezOvQZgZVEmZFpCrvixYsG+v
148qlpZ+HhrlJEWds7tvBsyyfNjwWjVIpm08zBmteFj4zu7OEcmGXEHDoxDXxyVP2BG
149eLU/fM5JA2UEjfCQ1MIZ3rBtPePdz4LRpb+ajklqrUj1OHoiDrXa8EAf0/wDP9re
150c1iH4bn7ZjYK0+IhZ+Pmw6gUftzZNWSC2kOLnZLdN/K7hgh0l0r0K/1eeXt43upB
151WALNuiECgYEA8PM2Ob3XXKALF86PUewne4fCz9iixr/cIpvrEGrh9lyQRO8X5Jxb
152ug38jEql4a574C6TSXfzxURza4P6lnfa0LvymmW0bhxZ5nev9kcAVnLKvpOUArTR
15332k9bKXd6zp8Q9ZyVNwHRxcVs4YgwfJlcx8geC4o6YRiIjvcBQ9RVHkCgYEA87OK
154lZDFBeEY/HVOxAQNXS5fgTd4U4DbwEJLv7SPk02v9oDkGHkpgMs4PcsIpCzsTpJ0
155oXMfLSxZ1lmZiuUvAupKj/7RjJ0XyjSMfm1Zs81epWj+boVfM4amZNHVLIWgddmM
156XzXEZKByvi1gs7qFcjQz2DEbZltWO6dX14O4Fz0CgYEAlWSWyHJWZ02r0xT1c7vS
157NxtTxH7zXftzR9oYgtNiStfVc4gy7kGr9c3aOjnGZAlFMRhvpevDrxnj3lO0OTsS
1585rzBjM1mc6cMboLjDPW01eTSpBroeE0Ym0arGQQ2djSK+5yowsixknhTsj2FbfsW
159v6wa+6jTIQY9ujAXGOQIbzECgYAYuXlw7SwgCZNYYappFqQodQD5giAyEJu66L74
160px/96N7WWoNJvFkqmPOOyV+KEIi0/ATbMGvUUHCY36RFRDU9zXldHJQz+Ogl+qja
161VsvIAyj8DSfrHJrpBlsxVVyUVMZPzo+ARVs0flbF1qK9+Ul6qbMs1uaZvuCD0tmF
162ovZ1XQKBgQDB0s7SDmAMgVjG8UBZgUru9vsDrxERT2BloptnnAjSiarLF5M+qeZO
1637L4NLyVP39Z83eerEonzDAHHbvhPyi6n2YmnYhGjeP+lPZIVqGF9cpZD3q48YHZc
1643ePn2/oLZrXKWOMyMwp2Uj+0SArCW+xMnoNp50sYNVR/JK3BPIdkag==
165-----END RSA PRIVATE KEY-----
166key_type       	dynamic
167port           	22
168username       	username
169```
170
171### Establish an SSH session
172
173Save the key to a file (e.g. `dyn_key.pem`) and then use it to establish an SSH
174session.
175
176```text
177$ ssh -i dyn_key.pem username@<IP of remote host>
178username@<IP of remote host>:~$
179```
180
181### Automate it!
182
183Creation of new key, saving to a file, and using it to establish an SSH session
184can all be done with a single Vault CLI command.
185
186```text
187$ vault ssh -role dynamic_key_role username@<IP of remote host>
188username@<IP of remote host>:~$
189```
190
191## API
192
193The SSH secret secrets engine has a full HTTP API. Please see the
194[SSH secret secrets engine API](/api/secret/ssh/index.html) for more
195details.
196