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