# SSH Keys This is realized by ## Vault Plugin: SSH Auth Backend This is a standalone backend plugin for use with[ Vault](https://www.github.com/hashicorp/vault). This plugin allows for SSH public keys and SSH certificates to authenticate with Vault. ### Getting Started This is a [Vault plugin](https://www.vaultproject.io/docs/internals/plugins.html) and is meant to work with Vault. This guide assumes you have already installed Vault and have a basic understanding of how Vault works. Otherwise, first read this guide on how to get started with Vault. ### Usage ``` $ vault auth enable -path=ssh vault-plugin-auth-ssh Success! Enabled vault-plugin-auth-ssh auth method at: ssh/ ``` ### Developing If you wish to work on this plugin, you'll first need [Go](https://www.golang.org/) installed on your machine. Next, clone this repository into `vault-plugin-auth-ssh`. To compile a development version of this plugin, run `make build`. This will put the plugin binary in the `./vault/plugins` folders. Run `make start` to start a development version of vault with this plugin. Enable the auth plugin backend using the SSH auth plugin: ``` $ vault auth enable -path=ssh vault-plugin-auth-ssh Success! Enabled vault-plugin-auth-ssh auth method at: ssh/ ``` #### Dev setup Look into the `devsetup.sh` script, this will build the plugin, build certsig and setup a test environment with ssh-client signing, ssh certificate and public key test. ### Using the plugin #### Global configuration You may optionally set any of the [standard Vault token parameters](https://pkg.go.dev/github.com/hashicorp/vault/sdk/helper/tokenutil#TokenParams) which will be used as defaults if not overridden in a role. **ssh\_ca\_public\_keys** If you want to use ssh certificates you'll need to configure the ssh CA's which the certificates will validate against. sshca in this example is a file containing your SSH CA. You can specify multiple CA's. ``` $ vault write auth/ssh/config ssh_ca_public_keys=@sshca $ vault read auth/ssh/config Key Value --- ----- secure_nonce true ssh_ca_public_keys [ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDrLFN/LCDOjPw327hWfHXMOk9+GmP+pOl2JEG7eSfkzwVhumDU12swjnPQ9H1tZVWzcfufTg+PgMd/hP19ADkRxQ2CTbz7YUPdD6LvJOCRK8TK+tKliaFL9/lWFtlitERyk91ZSqGbROjtCyGlnetxY1+tF5NqLFtQ1tsPrxjjdRQoUMHlF8yv/VUxMOCjAmuqxKrEl5mfZJcnYpnfEBgWoZNTKAXkp6KJWLAxyiHPVTt7azyMzivCTZc8eCKXIInRpOMR7TvHGxPG8tHn2XrI01ni9zXQ+xG1sqxecPBSWU8fekKxwg5bikrWw4/9kCNvxrwBpf1IzlIKhugig8MP3+Jlrjp5BFXFuaQatIk6zLMkzDpE/iZwDZv5qicXdLK/nbKHmGqFWupcvfHUe6rh16TOYFbpnRMOEvTYpR/PfLlnQKcbkQgbDR01N8DfLetxt635C+ANU4N1ebQqjKkwb8ZPr2ryF/Y8Z1PV0x5H25r8UZyoGAXIsP3zkP0Ev40Bx3umlU/jR8nF6QQmXdbs2McfZFO2g0VsXSzUOR0L5s5Sd/uoUCcpz9nmKlgRIqHIhVGF3+FjrIaj3tXT7ucyPAsVVk/l4yhMQSuNtFi0eqZRPcdMiKff5W9PfVyEkpXTcSFweGPdVehZxPnM7DfH7axpg73OLWxvwVzkah31WQ==] token_bound_cidrs [] token_explicit_max_ttl 0s token_max_ttl 0s token_no_default_policy false token_num_uses 0 token_period 0s token_policies [] token_ttl 0s token_type default ``` **secure\_nonce** By default the `secure_nonce` config option is enabled. This means vault will generate a nonce for you with a lifetime of 30 seconds.\ You can get this nonce by doing `vault read auth/ssh/nonce` the resulting nonce must be used to create a signature over. (see [Creating signatures](https://github.com/42wim/vault-plugin-auth-ssh#creating-signatures)) If you disable `secure_nonce` you can use timebased nonces. (this is a possible security risk) #### Roles You can create / list / delete roles which are used to link your certificate or public keys to Vault policies. You may optionally set any of the [standard Vault token parameters](https://pkg.go.dev/github.com/hashicorp/vault/sdk/helper/tokenutil#TokenParams) to override default values. **SSH certificate** Create a role with the policy `ssh-policy` bound to a certificate with the principal `ubuntu`.\ (prerequisite: a SSH CA needs to be configured in auth/ssh/config) ``` $ vault write auth/ssh/role/ubuntu token_policies="ssh-policy" principals="ubuntu" $ vault read auth/ssh/role/ubuntu Key Value --- ----- principals [ubuntu] public_keys token_bound_cidrs [] token_explicit_max_ttl 0s token_max_ttl 0s token_no_default_policy false token_num_uses 0 token_period 0s token_policies [ssh-policy] token_ttl 0s token_type default ``` **SSH public keys** Create a role with the policy `ssh-policy` bound to a specific publickey. ``` $ vault write auth/ssh/role/ubuntu token_policies="ssh-policy" public_keys=@sshkey.pub $ vault read auth/ssh/role/ubuntu Key Value --- ----- principals public_keys [ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGg0xzFrvEYbZGkF5vWlHUutACUTLH7WMUG09NOi6skL] token_bound_cidrs [] token_explicit_max_ttl 0s token_max_ttl 0s token_no_default_policy false token_num_uses 0 token_period 0s token_policies [ssh-policy] token_ttl 0s token_type default ``` **SSH public key self-registration** If your Vault has another authentication method that users can use, perhaps one that requires more user interaction such as [OIDC authentication](https://learn.hashicorp.com/tutorials/vault/oidc-auth), it is possible to use that other authentication method to securely enable users to register their own public keys for SSH authentication. First, configure default standard token parameters for SSH authentication as above, so users do not have to choose them, especially the `token_policies` parameter. Next, configure the other authentication method with a policy that enables writing public keys to the `auth/ssh/role` path but doesn't allow other parameters. For example use a [templated policy](https://www.vaultproject.io/docs/concepts/policies#templated-policies) like this: ``` path "auth/ssh/role/{{identity.entity.aliases..name}}" { capabilities = ["create", "update"] denied_parameters = { "public_keys" = ["@*"] } allowed_parameters = { "public_keys" = [] } } ``` #### Logging in **SSH certificate** ``` nonce=$(vault read -field nonce auth/ssh/nonce) vault write auth/ssh/login role= cert=@ nonce=$nonce signature= ``` For example ``` vault write auth/ssh/login role=ubuntu cert=@id_rsa-cert.pub signature=7ou2bupUMNmMqcorurOnbKnpbh9Kc7aBrF7nk6li0AhgnYAzhgfgGB3qJqI4qmf9TIc/x3JoNzo+Xq7KqXOXCA== nonce=AQAAAA7XdbPVKJn3uwA8 Key Value --- ----- token s.TpHP2eRCZNhuOENZUMas6YmV token_accessor 7FFAcAnxKOyM8BYWEN2KfYzR token_duration 768h token_renewable true token_policies ["default" "ssh-policy"] identity_policies [] policies ["default" "ssh-policy"] token_meta_role ubuntu ``` See [Creating signatures](https://github.com/42wim/vault-plugin-auth-ssh#creating-signatures) about how to create those. **SSH public key** ``` nonce=$(vault read -field nonce auth/ssh/nonce) vault write auth/ssh/login role= public_key=@ nonce=$nonce signature= ``` For example ``` $ vault write auth/ssh/login role=ubuntu public_key=@id_rsa.pub signature=fiEHdDHClYJIlRNWMC6c5QpM3ePi1xJh1KB90NI7CedZh0Siya5SG8ohy6zOk7e5l8Mdhx/FelykL43KH+OwBw== nonce=AQAAAA7XdbTAIytAhQA8 Key Value --- ----- token s.8L1uONTtaLHzZEtNw2oKmurk token_accessor SQ6jWOYKblSBFqywTezcdqVk token_duration 768h token_renewable true token_policies ["default" "ssh-policy"] identity_policies [] policies ["default" "ssh-policy"] token_meta_role ubuntu ``` See [Creating signatures](https://github.com/42wim/vault-plugin-auth-ssh#creating-signatures) about how to create those. **Using templated policies** This plugin makes aliases available for use in Vault [templated policies](https://www.vaultproject.io/docs/concepts/policies#templated-policies). These can be used to limit what secrets a policy makes available while sharing one policy between multiple roles. The defined role is always available in policies as `{{identity.entity.aliases..name}}`. In addition, a login can add any metadata keys with values to further limit secrets paths via the `metadata` parameter available as `{{identity.entity.aliases..metadata.}}`. The metadata parameter is a mapping of keys to values which should be input as JSON, for example: For example ``` echo '{ "metadata": { "key1" : "val1", "key2": "val2" } }' | \ vault write auth/ssh/login role= public_key=@ nonce= signature= - ``` will create the metadata keys "key1" and key2" with values "val1" and "val2", respectively. #### Creating signatures For now you can use the [createsig](https://github.com/42wim/vault-plugin-auth-ssh/blob/master/createsig/README.md) tool to generate your signature and nonce. ``` This tool will print out a signature based on a nonce to be used with vault-plugin-auth-ssh Need createsig eg. createsig 5f780af8-75ff-f209-cd31-500879e18640 id_rsa mypassword If you don't have a password just omit it eg. createsig 5f780af8-75ff-f209-cd31-500879e18640 id_rsa ``` You must get the nonce from `vault read auth/ssh/nonce` For example: ``` $ vault write auth/ssh/login role=ubuntu public_key=@id_rsa.pub $(createsig $(vault read -field nonce auth/ssh/nonce) vaultid_rsa) ``` ``` $ vault write auth/ssh/login role=ubuntu cert=@id_rsa-cert.pub $(createsig $(vault read -field nonce auth/ssh/nonce) id_rsa) ``` With a pass ``` $ vault write auth/ssh/login role=ubuntu public_key=@id_rsa.pub $(createsig $(vault read -field nonce auth/ssh/nonce) id_rsa yourpass) ``` #### Using ssh-agent Signatures can also be created using ssh-agent. See the [vssh README](https://github.com/42wim/vault-plugin-auth-ssh/blob/master/vssh/README.md) and [pylogin README](https://github.com/42wim/vault-plugin-auth-ssh/blob/master/pylogin/README.md) for examples of how to do that. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.enclaive.cloud/vault/tutorials/cli/authentication/ssh-keys.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.