luxolus/open-vault
2
0
Fork 0
Code Issues 1 Pull requests Releases Activity

Merge pull request #3166 from hashicorp/sethvargo/ssh_ca_expanse

Browse source 
Refactor SSH CA backend docs
This commit is contained in:
Seth Vargo 2017-08-16 18:39:19 -04:00 committed by GitHub
parent ea6a1382ff b4bec62d47
commit 4beb12fc88
1 changed files with 281 additions and 150 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

431
website/source/docs/secrets/ssh/signed-ssh-certificates.html.md
View file

@ -12,195 +12,326 @@ description: |-
# Signed SSH Certificates
The signed SSH certificates is the simplest and most powerful in terms of setup
complexity and in terms of being platform agnostic.
complexity and in terms of being platform agnostic. By leveraging Vault's
powerful CA capabilities and functionality built into OpenSSH, clients can SSH
into target hosts using their own local SSH keys.
When using this type, an SSH CA signing key is generated or configured at the
backend's mount. This key will be used to sign other SSH keys. The private half
of the signing key always stays within Vault and the public half is exposed via
the API. Each mount of this backend represents a unique signing key pair. It is
recommended that the host keys and client keys are signed using different mounts
of this backend.
In this section, the term "**client**" refers to the person or machine
performing the SSH operation. The "**host**" refers to the target machine. If
this is confusing, substitute "client" with "user".
This page will show a quick start for this backend. For detailed documentation
on every path, use `vault path-help` after mounting the backend.
### Mount a backend's instance for signing host keys
## Client Key Signing
```text
vault mount -path ssh-host-signer ssh
Successfully mounted 'ssh' at 'ssh-host-signer'!
```
Before a client can request their SSH key be signed, the Vault SSH backend must
be configured. Usually a Vault administrator or security team performs these
steps. It is also possible to automate these actions using a configuration
management tool like Chef, Puppet, Ansible, or Salt.
### Mount a backend's instance for signing client keys
### Signing Key & Role Configuration
```text
vault mount -path ssh-client-signer ssh
Successfully mounted 'ssh' at 'ssh-client-signer'!
```
The following steps are performed in advance by a Vault administrator, security
team, or configuration management tooling.
### Configure the host CA certificate
1. Mount the backend. Like all secret backends in Vault, the SSH secret backend
must be mounted before use.
```text
vault write -f ssh-host-signer/config/ca
Key Value
--- -----
public_key ssh-rsa
AAAAB3NzaC1yc2EAAAADAQABAAACAQDB7lbQ4ub8/7AbfnF4zntCxPGijXzdo50MrUz0I1Vz/n98pBPyrUEcNqFeCr6Qs9kRL8J8Bu48W/DtSxAiScIIlzyezulH+wxdZnCN3sxDUhFbTUosWstSt6P5BZbJsMTpfHfuYbOexewX9ljw636fUrRtU3/0Emq2FkOcKEv9v7z+Qwdaom+8R6CvRA0Kit0yyh6DXD+IjPnOmhYFoNH6ZhPU2xJ+7M16vLpCmH6OO1krHlDK+ZUvVKD2ZjfmbegoYEV/9FETSzVnQ/pOrP0SdwpmGhei7VO7hQwa6zOWIah66TYYdaIopHFha60rZPybliZFAi/CcUO7NYldq7Q2ty68RKp+Im2ROPbXLKYc2N+PThWwbxA1yQ7shvgSy/JEbAcYQuDLGn6tA6n5sXpvFcJe+vlf75w+laXIPUXTVHr2g1O5Irzwunpg03Pa+Kab8Hp8uq61XfTfNtCwHYr/K5YO27rHcpMA/gBKkOFmBbcI3VlUbi266HiyFANz0JMObzXS5hEGm90NevMD2nEFvZHYHx4hXRtoox7Bh4CCj2fUPaThnuTvv1hLBgryWxwDXL7OwHGx6wd/dpXo/1fG1DRUotfVcJP7k7FG9MUAB6tOR2RCuXEaTF6bv3tCpbsdzzzyhs/aIa6IeYRV4HUo3nW5g/IRT+6F/MLd63Cq5w==
```
```text
$ vault mount -path=ssh-client-signer ssh
Successfully mounted 'ssh' at 'ssh-client-signer'!
```
The returned host CA public key should be added to `known_hosts` file in all
client machines with a `@cert-authority <domain>` prefix, where `<domain>` can
be any value (single host, wildcard domain, wildcard) SSH accepts to define
hosts (e.g. `@cert-authority *.example.com ssh-rsa AAAA...`). This public key
can also be retrieved using `vault read ssh-host-signer/config/ca`.
This mounts the SSH backend at the path "ssh-client-signer". It is possible
to mount the same secret backend multiple times using different `-path`
arguments. The name "ssh-client-signer" is not special - it can be any name,
but this documentation will assume "ssh-client-signer".
### Configure the client CA certificate
1. Configure Vault with a CA for signing client keys using the `/config/ca`
endpoint. If you do not have an internal CA, Vault can generate a keypair for
you.
```text
vault write -f ssh-client-signer/config/ca
Key Value
--- -----
public_key ssh-rsa
AAAAB3NzaC1yc2EAAAADAQABAAACAQDoYiTm0QrK+NGkv8H/Sq1Q9l2PQwxY1ROSPpRqOoFAgCM7vtEZSGchm8j3/Da6Vj84sUg+09N+dwMZ6z3HG57dBWyfHGCbEt+fIJtRcCV7KkQ4xktBdapq5PychBg0bYIP0+JWXe7yOAR6s+DWJgUUHwmYiY0GlrzoztvtYcU/pvj4zWY/EWcCAYRiZThqJOJ9rDzhEzmVHVYelZ8dlehKZsUOQ3dY5fCHgWJ5/IKSfGUI1w1h/3ENAToBKInbW2J/Wy0mbsfUJhha84zgqSeHd4gZ9YqaSpzYffVvDz6Ud+KtPWt4ejJDyvJVFAVnVIvVUCkuXVefBlC10Ww6l52DXex/rdxQW+46ZNV5zlFOUi4VWFPT6bOlIEj1hgHG0cfFKARQXcVlp03xTi5DRJp3jlBf/QLeUy4kZEFUdQl+gkVLwySrOh+1kHwE15JQWpNHxfxWzYnNnjokT2RCW2ANO4Y8vfMPCVM5OKSVNISHm3UurNkJNTAomK/ElnXQgP23UcVgbF3mNRBPx9U3/+9HHkXcqDefSI7XBC7npIBFdetCxFt3nW/cX4l1zfq6ZExCVde+/40V1U+TOoLZVLIZZzEuA40J4H99oK7QN5/MtCGaSr7kgAx+7ymfSY37rXB6wOVi5HTBlhyh+VFGU+Wmy+q5sxfr6+ZLGwoGpvNh0Q==
```
```text
$ vault write ssh-client-signer/config/ca generate_signing_key=true
Key Value
--- -----
public_key ssh-rsa AAAAB3NzaC1yc2EA...
```
The returned client CA public key should be saved in a file that is added to
the `TrustedUserCAKeys` list in the `sshd_config` file on the host machine:
If you already have a keypair, specify the public and private key parts as
part of the payload:
```text
cat /etc/ssh/sshd_config
...
...
TrustedUserCAKeys /etc/ssh/trusted-user-ca-keys.pem
```
```text
$ vault write ssh-client-signer/config/ca \
private_key="..." \
public_key="..."
```
The client CA public key can also be retrieved later using `vault read
ssh-client-signer/config/ca`.
Regardless of whether it is generated or uploaded, the client signer public
key is accessible via the API at the `/public_key` endpoint.
### Allow host certificate to have longer TTLs
1. Add the public key to all target host's SSH configuration. This process can
be manual or automated using a configuration management tool. The public key is
accessible via the API and does not require authentication.
```text
vault mount-tune -max-lease-ttl=87600h ssh-host-signer
Successfully tuned mount 'ssh-host-signer'!
```
```text
$ curl -o /etc/ssh/trusted-user-ca-keys.pem https://vault.rocks/v1/ssh-client-signer/public_key
```
### Create a role to sign host keys
```text
$ vault read -field=public_key ssh-client-signer/config/ca > /etc/ssh/trusted-user-ca-keys.pem
```
You'll want to add in some allowed domains and either the `allow_subdomains`
flag, the `allow_bare_domains` flag, or both.
Add the path where the public key contents are stored to the SSH
configuration file as the `TrustedUserCAKeys` option.
```text
vault write ssh-host-signer/roles/hostrole ttl=87600h allow_host_certificates=true key_type=ca allowed_domains="localdomain,example.com" allow_subdomains=true
Success! Data written to: ssh-host-signer/roles/hostrole
```
```text
# /etc/ssh/sshd_config
# ...
TrustedUserCAKeys /etc/ssh/trusted-user-ca-keys.pem
```
### Create a role to sign client keys
Restart the SSH service to pick up the changes.
Because of the way that some SSH certificate features are implemented, some
common options to this call must be passed in as a map. Vault's CLI does not
currently have a native way to pass in map values, so the easiest way to do
this is to create a JSON file and use it as the input. In the following example
this is used to add the `permit-pty` extension to the certificate.
1. Create a named Vault role for signing client keys.
```json
{
"allow_user_certificates": true,
"allowed_users": "*",
"default_extensions": [
Because of the way some SSH certificate features are implemented, options
are passed as a map. The following example adds the `permit-pty` extension
to the certificate.
```text
$ vault write ssh-client-signer/roles/my-role -<<"EOH"
{
"permit-pty": ""
"allow_user_certificates": true,
"allowed_users": "*",
"default_extensions": [
{
"permit-pty": ""
}
],
"key_type": "ca",
"default_user": "ubuntu",
"ttl": "30m0s"
}
],
"key_type": "ca",
"default_user": "icecream",
"ttl": "30m0s"
}
```
EOH
```
### Client SSH Authentication
The following steps are performed by the client (user) that wants to
authenticate to machines managed by Vault. These commands are usually run from
the client's local workstation.
1. Locate or generate the SSH public key. Usually this is `~/.ssh/id_rsa.pub`.
If you do not have an SSH keypair, generate one:
```text
$ ssh-keygen -t rsa -C "user@example.com"
```
1. Ask Vault to sign your **public key**. This file usually ends in `.pub` and
the contents begin with `ssh-rsa ...`.
```text
$ vault write ssh-client-signer/sign/my-role \
public_key=@$HOME/.ssh/id_rsa.pub
Key Value
--- -----
serial_number c73f26d2340276aa
signed_key ssh-rsa-cert-v01@openssh.com AAAAHHNzaC1...
```
The result will include the serial and the signed key. This signed key is
another public key.
1. Save the resulting signed, public key to disk. Limit permissions as needed.
```text
$ vault write -field=signed_key ssh-client-signer/sign/my-role \
public_key=@$HOME/.ssh/id_rsa.pub > signed-cert.pub
```
If you are saving the certificate directly beside your SSH keypair, suffix
the name with `-cert.pub` (`~/.ssh/id_rsa-cert.pub`). With this naming
scheme, OpenSSH will automatically use it during authentication.
1. (Optional) View enabled extensions, principals, and metadata of the signed
key.
```text
$ ssh-keygen -Lf ~/.ssh/signed-cert.pub
```
1. SSH into the host machine using the signed key.
```text
$ ssh -i signed-cert.pub username@10.0.23.5
```
## Host Key Signing
For an added layers of security, we recommend enabling host key signing. This is
used in conjunction with client key signing to provide an additional integrity
layer. When enabled, the SSH agent will verify the target host is valid and
trusted before attempting to SSH. This will reduce the probability of a user
accidentally SSHing into an unmanaged or malicious machine.
### Signing Key Configuration
1. Mount the backend. For the most security, mount at a different path from the
client signer.
```text
$ vault mount -path=ssh-host-signer ssh
Successfully mounted 'ssh' at 'ssh-host-signer'!
```
1. Configure Vault with a CA for signing host keys using the `/config/ca`
endpoint. If you do not have an internal CA, Vault can generate a keypair for
you.
```text
$ vault write ssh-host-signer/config/ca generate_signing_key=true
Key Value
--- -----
public_key ssh-rsa AAAAB3NzaC1yc2EA...
```
If you already have a keypair, specify the public and private key parts as
part of the payload:
```text
$ vault write ssh-host-signer/config/ca \
private_key="..." \
public_key="..."
```
Regardless of whether it is generated or uploaded, the host signer public
key is accessible via the API at the `/public_key` endpoint.
1. Extend host key certificate TTLs.
```text
$ vault mount-tune -max-lease-ttl=87600h ssh-host-signer
```
1. Create a role for signing host keys. Be sure to fill in the list of allowed
domains, set `allow_bare_domains`, or both.
```text
$ vault write ssh-host-signer/roles/hostrole \
key_type=ca \
ttl=87600h \
allow_host_certificates=true \
allowed_domains="localdomain,example.com" \
allow_subdomains=true
```
1. Sign the host's SSH public key.
```text
$ vault write ssh-host-signer/sign/hostrole \
cert_type=host \
public_key=@/etc/ssh/ssh_host_rsa_key.pub
Key Value
--- -----
serial_number 3746eb17371540d9
signed_key ssh-rsa-cert-v01@openssh.com AAAAHHNzaC1y...
```
1. Set the resulting signed certificate as `HostCertificate` in the SSH
configuration on the host machine.
```text
$ vault write -field=signed_key ssh-host-signer/sign/hostrole \
cert_type=host \
public_key=@/etc/ssh/ssh_host_rsa_key.pub > /etc/ssh/ssh_host_rsa_key-cert.pub
```
Set permissions on the certificate to be `0640`:
```text
$ chmod 0640 /etc/ssh/ssh_host_rsa_key-cert.pub
```
Add host key and host certificate to the SSH configuration file.
```text
# /etc/ssh/sshd_config
# ...
# For client keys
TrustedUserCAKeys /etc/ssh/trusted-user-ca-keys.pem
# For host keys
HostKey /etc/ssh/ssh_host_rsa_key
HostCertificate /etc/ssh/ssh_host_rsa_key-cert.pub
```
Restart the SSH service to pick up the changes.
### Client-Side Host Verification
1. Retrieve the host signing CA public key to validate the host signature of
target machines.
```text
$ curl https://vault.rocks/v1/ssh-host-signer/public_key
```
```text
$ vault -field=public_key read ssh-host-signer/config/ca
```
1. Add the resulting public key to the `known_hosts` file with authority.
```text
# ~/.ssh/known_hosts
@cert-authority *.example.com ssh-rsa AAAAB3NzaC1yc2EAAA...
```
1. SSH into target machines as usual.
## Troubleshooting
When initially configuring this type of key signing, enable `VERBOSE` SSH
logging to help annotate any errors in the log.
```text
vault write ssh-client-signer/roles/clientrole @clientrole.json
Success! Data written to: ssh-client-signer/roles/clientrole
# /etc/ssh/sshd_config
# ...
LogLevel VERBOSE
```
### Sign the host key
Restart SSH after making these changes.
You can generate a new key, or you can sign one of the host keys that was
autogenerated when SSH was first started up, e.g.
`/etc/ssh/ssh_host_rsa_key.pub`.
By default, SSH logs to `/var/log/auth.log`, but so do many other things. To
extract just the SSH logs, use the following:
```text
cat /etc/ssh/ssh_host_rsa_key.pub | vault write ssh-host-signer/sign/hostrole public_key=- cert_type=host
Key Value
--- -----
serial_number 3746eb17371540d9
signed_key ssh-rsa-cert-v01@openssh.com
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
```sh
$ tail -f /var/log/auth.log | grep --line-buffered "sshd"
```
Set the signed certificate as `HostCertificate` in `sshd_config` on the host
machine. In order to make things work more automagically (e.g. if you don't
want to specifically pick the host key/cert) it's a good idea to call this
`<key>-cert.pub`, e.g. `/etc/ssh/ssh_host_rsa_key-cert.pub`. It's also not a
bad idea to specifically pick the `HostKey` that will be used:
If you are unable to make a connection to the host, the SSH server logs may
provide guidance and insights.
```text
cat /etc/ssh/sshd_config
...
...
TrustedUserCAKeys /etc/ssh/trusted-user-ca-keys.pem
HostKey /etc/ssh/ssh_host_rsa_key
HostCertificate /etc/ssh/ssh_host_rsa_key-cert.pub
```
### Known Issues
It's also a good idea to make sure that the permissions on the
`HostCertificate` file are `0640` (on most systems).
- On SELinux-enforcing systems, you may need to adjust related types so that the
SSH daemon is able to read it. For example, adjust the signed host certificate
to be an `sshd_key_t` type.
- On some versions of SSH, you may get the following error:
### Sign the client key
```text
no separate private key for certificate
```
This is any key you want to use, e.g. `~/.ssh/id_rsa.pub`:
```text
cd ~/.ssh
cat id_rsa.pub | vault write ssh-client-signer/sign/clientrole public_key=-
Key Value
--- -----
serial_number c73f26d2340276aa
signed_key ssh-rsa-cert-v01@openssh.com
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
```
Save the signed key in a file (make sure you set the permissions to only be
writeable by the owner); if you're saving it along with your public/private key
(e.g. `~/.ssh/id_rsa(.pub)`), saving it with `-cert.pub` (e.g.
`~/.ssh/id_rsa-cert.pub`) allows SSH to automatically discover it. Otherwise,
you can tell the SSH client where to find it (and the associated private key)
by using `-i` such as `ssh -i ~/.ssh/id_rsa -i my-signed-cert.pub localhost`.
If you want to see the configured extensions, principals, etc., you can use the
`-L` flag to `ssh-keygen`, e.g. `ssh-keygen -Lf ~/.ssh/id_rsa-cert.pub`.
### SSH into the host machine
```text
ssh -i signed-client-cert.pub username@<IP of remote host>
username@<IP of remote host>:~$
```
### Troubleshooting
If you are not able to successfully make a client connection, looking at SSH server logs is likely to be your best bet. Some known potential issues:
* If on an SELinux-enforcing system, you may need to adjust related types so
that the SSH daemon is able to read it, for instance by adjusting the signed
host certificate to be an `sshd_key_t` type.
* If you encounter an error on the client indicating `"no separate private key
for certificate"` you may be hitting a bug introduced into OpenSSH version
7.2 and fixed in 7.5. See [OpenSSH bug
2617](https://bugzilla.mindrot.org/show_bug.cgi?id=2617) for details. If you
are able to find a workaround without patching OpenSSH, please submit a PR to
update this documentation!
This is a bug introduced in OpenSSH version 7.2 and fixed in 7.5. See
[OpenSSH bug 2617](https://bugzilla.mindrot.org/show_bug.cgi?id=2617) for
details.
## API