`vault_ssh`¶

Added in version 1.2.0.

Manage the Vault (or OpenBao) SSH secret engine, request SSH credentials and certificates.

Added in version 1.6.0: You can specify this module as the backend parameter to the ssh_pki.certificate_managed state introduced in Salt 3008 for stateful management of Vault-issued certificates.

See create_certificate for details.

Important

This module requires the general Vault setup.

saltext.vault.modules.vault_ssh.read_role(name, mount='ssh')[source]¶

Reads an existing SSH role.

CLI Example:

salt '*' vault_ssh.read_role sre

Required policy:

path "<mount>/roles/<name>" {
    capabilities = ["read"]
}

name: Name of the SSH role.
mount: Name of the mount point the SSH secret backend is mounted at. Defaults to ssh.

saltext.vault.modules.vault_ssh.write_role_otp(name, default_user, cidr_list=None, allowed_users=None, exclude_cidr_list=None, port=None, mount='ssh')[source]¶

Create/update an SSH role (OTP type).

CLI Example:

salt '*' vault_ssh.write_role_otp sre sre-user '["1.0.0.0/24"]'

Required policy:

path "<mount>/roles/<name>" {
    capabilities = ["create", "update"]
}

name: Name of the SSH role.
default_user: Default username for which a credential should be generated. Required.
cidr_list: List of CIDR blocks to which the role is applicable. Required, unless the role is registered as a zero-address role.
allowed_users: List of usernames the client can request under this role. By default, any usernames are allowed (*). The default_user is always allowed.
exclude_cidr_list: List of CIDR blocks not accepted by the role.
port: Specifies the port number for SSH connections, which is returned to OTP clients as an informative value. Defaults to 22.
mount: Name of the mount point the SSH secret backend is mounted at. Defaults to ssh.

saltext.vault.modules.vault_ssh.write_role_ca(name, default_user='', default_user_template=None, allowed_users=None, allowed_users_template=None, allowed_domains=None, allowed_domains_template=None, ttl=None, max_ttl=None, allowed_critical_options=None, allowed_extensions=None, default_critical_options=None, default_extensions=None, default_extensions_template=None, allow_user_certificates=None, allow_host_certificates=None, allow_bare_domains=None, allow_subdomains=None, allow_user_key_ids=None, key_id_format=None, allowed_user_key_lengths=None, algorithm_signer=None, not_before_duration=None, mount='ssh')[source]¶

Create/update an SSH role (CA type).

CLI Example:

salt '*' vault_ssh.write_role_ca sre allowed_users=[sre-user] allow_user_certificates=true

Required policy:

path "<mount>/roles/<name>" {
    capabilities = ["create", "update"]
}

name: Name of the SSH role.
default_user: Default username for which a credential should be generated. When default_user_template is true, this can contain an identity template with any prefix or suffix, like ssh-{{identity.entity.id}}-user. If you wish this to be a valid principal, it must also be in allowed_users.
default_user_template: Allow default_users to be specified using identity template values. A non-templated user is also permitted. Defaults to false.
allowed_users: List of usernames the client can request under this role. By default, none are allowed. Set this to * to allow any usernames. If allowed_users_template is true, this list can contain an identity template with any prefix or suffix. The default_user is always allowed.
allowed_users_template: Allow allowed_users to be specified using identity template values. Non-templated users are also permitted. Defaults to false.
allowed_domains: List of domains for which a client can request a host certificate. * allows any domain. See also allow_bare_domains and allow_subdomains.
allowed_domains_template: Allow allowed_domains to be specified using identity template values. Non-templated domains are also permitted. Defaults to false.
ttl: Specifies the Time To Live value provided as a string duration with time suffix. Hour is the largest suffix. If unset, uses the system default value or the value of max_ttl, whichever is shorter
max_ttl: Specifies the maximum Time To Live provided as a string duration with time suffix. Hour is the largest suffix. If unset, defaults to the system maximum lease TTL.
allowed_critical_options: List of critical options that certificates can carry when signed. If unset (default), allows any option.
allowed_extensions: List of extensions that certificates can carry when signed. If unset (default), always takes the extensions from default_extensions only. If set to *, allows any extension to be set. For the list of extensions, take a look at the sshd manual’s AUTHORIZED_KEYS FILE FORMAT section. You should add a permit- before the name of extension to allow it.
default_critical_options: Map of critical options to their values certificates should carry if none are provided when signing.
default_extensions: Map of extensions to their values certificates should carry if none are provided when signing or allowed_extensions is unset.
default_extensions_template: Allow default_extensions to be specified using identity template values. Non-templated values are also permitted. Defaults to false.
allow_user_certificates: Allow certificates to be signed for user use. Defaults to false.
allow_host_certificates: Allow certificates to be signed for host use. Defaults to false.
allow_bare_domains: Allow host certificates to be signed for the base domains listed in allowed_domains. This is a separate option as in some cases this can be considered a security threat. Defaults to false.
allow_subdomains: Allow host certificates to be signed for subdomains of the base domains listed in allowed_domains. Defaults to false.
allow_user_key_ids: Allow users to override the key ID for a certificate. When false (default), the key ID always equals the token display name. The key ID is logged by the SSH server and can be useful for auditing.
key_id_format: Specifies a custom format for the key ID of a signed certificate. See key_id_format for available template values.
allowed_user_key_lengths: Map of ssh key types to allowed sizes when signing with the CA type. Values can be a list of multiple sizes. Keys can both be OpenSSH-style key identifiers and short names (rsa, ecdsa, dsa, or ed25519). If an algorithm has a fixed key size, values are ignored.
algorithm_signer: RSA algorithm to sign keys with. Valid: ssh-rsa, rsa-sha2-256, rsa-sha2-512, or default (which is the default). Ignored when not signing with an RSA key.
not_before_duration: Specifies the duration by which to backdate the ValidAfter property. Defaults to 30s.
mount: Name of the mount point the SSH secret backend is mounted at. Defaults to ssh.

saltext.vault.modules.vault_ssh.delete_role(name, mount='ssh')[source]¶

Deletes an existing SSH role.

CLI Example:

salt '*' vault_ssh.delete_role sre

Required policy:

path "<mount>/roles/<name>" {
    capabilities = ["delete"]
}

name: Name of the SSH role.
mount: Name of the mount point the SSH secret backend is mounted at. Defaults to ssh.

saltext.vault.modules.vault_ssh.list_roles(mount='ssh')[source]¶

Lists existing SSH roles.

CLI Example:

salt '*' vault_ssh.list_roles

Required policy:

path "<mount>/roles" {
    capabilities = ["list"]
}

mount: Name of the mount point the SSH secret backend is mounted at. Defaults to ssh.

saltext.vault.modules.vault_ssh.list_roles_ip(address, mount='ssh')[source]¶

Lists existing SSH roles associated with a given IP address.

CLI Example:

salt '*' vault_ssh.list_roles_ip 10.1.0.1

Required policy:

path "<mount>/lookup" {
    capabilities = ["create", "update"]
}

address: IP address to list roles for.
mount: Name of the mount point the SSH secret backend is mounted at. Defaults to ssh.

saltext.vault.modules.vault_ssh.list_roles_zeroaddr(mount='ssh')[source]¶

Return the list of configured zero-address roles. These are roles that are allowed to request credentials for any IP address.

CLI Example:

salt '*' vault_ssh.list_roles_zeroaddr

Required policy:

path "<mount>/config/zeroaddress" {
    capabilities = ["read"]
}

mount: Name of the mount point the SSH secret backend is mounted at. Defaults to ssh.

saltext.vault.modules.vault_ssh.write_zeroaddr_roles(roles, mount='ssh')[source]¶

Write the list of configured zero-address roles. These are roles that are allowed to request credentials for any IP address.

CLI Example:

salt '*' vault_ssh.write_roles_zeroaddr '[super, admin]'

Required policy:

path "<mount>/config/zeroaddress" {
    capabilities = ["create", "update"]
}

roles: List of role names that should be marked as zero address roles.
mount: Name of the mount point the SSH secret backend is mounted at. Defaults to ssh.

saltext.vault.modules.vault_ssh.delete_zeroaddr_roles(mount='ssh')[source]¶

Delete the list of configured zero-address roles. These are roles that are allowed to request credentials for any IP address.

CLI Example:

salt '*' vault_ssh.delete_roles_zeroaddr

Required policy:

path "<mount>/config/zeroaddress" {
    capabilities = ["delete"]
}

mount: Name of the mount point the SSH secret backend is mounted at. Defaults to ssh.

saltext.vault.modules.vault_ssh.get_creds(name, address, username='', mount='ssh')[source]¶

Generate credentials for a specific IP (and username) using an existing role. Returns a mapping with ip, key, key_type, port and username.

CLI Example:

salt '*' vault_ssh.get_creds sre 10.1.0.1
salt '*' vault_ssh.get_creds sre 10.1.0.1 bob

Required policy:

path "<mount>/creds/<role_name>" {
    capabilities = ["create", "update"]
}

name: Name of the role.
address: IP address of the host to generate credentials for.
username: Username on the remote host to generate credentials for. If empty, the default username of the role is used.
mount: Name of the mount point the SSH secret backend is mounted at. Defaults to ssh.

saltext.vault.modules.vault_ssh.create_ca(private_key=None, public_key=None, key_type='ssh-rsa', key_bits=0, mount='ssh')[source]¶

Create a CA to be used for certificate authentication.

CLI Example:

salt '*' vault_ssh.create_ca

Required policy:

path "<mount>/config/ca" {
    capabilities = ["create", "update"]
}

private_key: Private key part of the SSH CA key pair. Can be a file local to the minion or a PEM-encoded string. If this or public_key is unspecified, generates a pair on the Vault server.
public_key: Public key part of the SSH CA key pair. Can be a file local to the minion or a PEM-encoded string. If this or public_key is unspecified, generates a pair on the Vault server.
key_type: Desired key type for the generated SSH CA key when generating on the Vault server. Valid: ssh-rsa (default), sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, or ssh-ed25519. Can also specify an algorithm: rsa, ec, or ed25519.
key_bits: Desired key bits for the generated SSH CA key when generating on the Vault server. Only used for variable length keys (e.g. ssh-rsa) or when ec was specified as key_type, in which case this selects the NIST P-curve: 256, 384, 521. 0 (default) selects 4096 bits for RSA or NIST P-256 for EC.
mount: Name of the mount point the SSH secret backend is mounted at. Defaults to ssh.

saltext.vault.modules.vault_ssh.destroy_ca(mount='ssh')[source]¶

Destroy an existing CA on the mount.

CLI Example:

salt '*' vault_ssh.destroy_ca

Required policy:

path "<mount>/config/ca" {
    capabilities = ["delete"]
}

mount: Name of the mount point the SSH secret backend is mounted at. Defaults to ssh.

saltext.vault.modules.vault_ssh.read_ca(mount='ssh')[source]¶

Read the public key for an existing CA on the mount. This defaults to reading from the authenticated endpoint, but falls back to the unauthenticated one.

CLI Example:

salt '*' vault_ssh.read_ca

Required policy: None for the unauthenticated endpoint or

path "<mount>/config/ca" {
    capabilities = ["read"]
}

mount: Name of the mount point the SSH secret backend is mounted at. Defaults to ssh.

saltext.vault.modules.vault_ssh.sign_key(name, public_key, ttl=None, valid_principals=None, cert_type='user', key_id=None, critical_options=None, extensions=None, mount='ssh')[source]¶

Sign an SSH public key under an existing role on the mount. Returns a mapping with serial_number and signed_key.

CLI Example:

salt '*' vault_ssh.sign_key sre $HOME/.ssh/id_me.pub

Required policy:

path "<mount>/sign/<role_name>" {
    capabilities = ["create", "update"]
}

name: Name of the SSH role.
public_key: SSH public key that should be signed. Can be a file local to the minion or a PEM-encoded string.
ttl: Request a specific time to live for the certificate, limited by the role’s TTL. If unspecified, defaults to the role’s TTL or system values.
valid_principals: List of usernames/hostnames the certificate should be signed for.
cert_type: Type of certificate to issue, either user or host. Defaults to user.
key_id: Key ID the created certificate should have. If unspecified, the display name of the creating token is used.
critical_options: Map of critical options the certificate should carry.
extensions: Map of extensions the certificate should carry.
mount: Name of the mount point the SSH secret backend is mounted at. Defaults to ssh.

saltext.vault.modules.vault_ssh.generate_key_cert(name, key_type='ssh-rsa', key_bits=0, ttl=None, valid_principals=None, cert_type='user', key_id=None, critical_options=None, extensions=None, mount='ssh')[source]¶

Generate an SSH private key and accompanying signed certificate. Returns a mapping with keys private_key, private_key_type, serial_number, signed_key.

CLI Example:

salt '*' vault_ssh.generate_key_cert sre

Required policy:

path "<mount>/sign/<role_name>" {
    capabilities = ["create", "update"]
}

name: Name of the SSH role.
key_type: Desired key type for the generated SSH CA key. Valid: ssh-rsa (default), sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, or ssh-ed25519. Can also specify an algorithm: rsa, ec, or ed25519.
key_bits: Desired key bits for the generated SSH CA key. Only used for variable length keys (e.g. ssh-rsa) or when ec was specified as key_type, in which case this selects the NIST P-curve: 256, 384, 521. 0 (default) selects 4096 bits for RSA or NIST P-256 for EC.
ttl: Request a specific time to live for the certificate, limited by the role’s TTL. If unspecified, defaults to the role’s TTL or system values.
valid_principals: List of usernames/hostnames the certificate should be signed for.
cert_type: Type of certificate to issue, either user or host. Defaults to user.
key_id: Key ID the created certificate should have. If unspecified, the display name of the creating token is used.
critical_options: Map of critical options the certificate should carry.
extensions: Map of extensions the certificate should carry.
mount: Name of the mount point the SSH secret backend is mounted at. Defaults to ssh.

saltext.vault.modules.vault_ssh.create_certificate(ca_server=None, signing_policy=None, **kwargs)[source]¶

Added in version 1.6.0.

Create an OpenSSH certificate and return an encoded version of it. This functions allows this module to be specified as the backend parameter to the ssh_pki.certificate_managed state introduced in Salt 3008.

Note

The following parameters from ssh_pki.create_certificate are ignored when using this backend: serial_number, not_before, not_after, signing_private_key, signing_private_key_passphrase, copypath, path, overwrite, raw.

Hint

Since this is a compatibility layer, sometimes the parameter names do not describe their expected value.

State example:

Manage host cert:
  ssh_pki.certificate_managed:
    - name: /etc/ssh/host_ed_25519_cert
    - private_key: /etc/ssh/host_ed25519_key
    - backend: vault_ssh
    - signing_policy: ssh_role_name_in_vault
    - ca_server: mount_name_of_ssh_secret_engine
    - require:
      - ssh_pki: /etc/ssh/host_ed25519_key

CLI Example:

salt '*' vault_ssh.create_certificate signing_policy=ssh_role_name private_key='/etc/pki/ssh/my.key'

Required policy:

# To issue the certificate (this function)
path "<ca_server>/sign/<signing_policy>" {
    capabilities = ["create", "update"]
}

# When the certificate exists, to check for changes.
# This is actually required by `get_signing_policy` below.
path "<ca_server>/roles/<signing_policy>" {
        capabilities = ["read"]
}

ca_server

Name of the mount point the SSH secret backend is mounted at. Defaults to ssh.

signing_policy

Name of the SSH role to use for issuance. Required.

Important

This needs to be a role with key_type of ca.

cert_type

Certificate type to generate. Either user or host. Required if not clear from the Vault role definition (either allow_user_certificates or allow_host_certificates set).

private_key

Private key corresponding to the public key the certificate should be issued for. Either this or public_key is required.

private_key_passphrase

If private_key is specified and encrypted, the passphrase to decrypt it.

public_key

Public key the certificate should be issued for. Either this or private_key is required.

critical_options

Mapping of critical option name to option value to set on the certificate. If an option does not take a value, specify it as true.

If the role’s allowed_critical_options is empty, allows any option to be set. Otherwise, only options present in allowed_critical_options are set. In contrast to Vault’s behavior, a role’s default_critical_options are still set when this parameter is specified. To unset a default option, specify its value as false.

Note

Currently, there’s no explicit Vault role parameter that forces the value of an extension. It’s possible to set a critical option in default_critical_options and ensure it is absent from allowed_critical_options though.

extensions

Mapping of extension name to extension value to set on the certificate. If an extension does not take a value, specify it as true.

If the role’s allowed_extensions is empty, this parameter is ignored. Otherwise, only options present in allowed_extensions are set. In contrast to Vault’s behavior, a role’s default_extensions are still set when this parameter is specified. To unset a default extension, specify its value as false.

Note

Currently, there’s no explicit Vault role parameter that forces the value of an extension. It’s possible to set an extension in default_extensions and ensure it is absent from allowed_extensions though.

valid_principals

List of valid principals.

All specified principals must be in allowed_users/allowed_domains. For user certificates, defaults to a role’s default_user. For host certificates, this is required.

Note

If a role specifies allowed_users_template/allowed_domains_template/allowed_subdomains, stateful management via ssh_pki.certificate_managed cannot silently filter invalid principals since the ssh_pki modules cannot render the templates. Invalid principals result in state failure then.

all_principals

Allow any principals. Defaults to false.

To truly allow any principals, requires * in a role’s valid_principals. Otherwise, defaults to all valid ones.

Note

If a role specifies allowed_users_template/allowed_domains_template/allowed_subdomains, this defaulting fails since the ssh_pki modules cannot render the templates.

key_id

Specify a string-valued key ID for the signed public key. When the certificate is used for authentication, this value is logged in plaintext.

Requires allow_user_key_ids to be set in the role.

saltext.vault.modules.vault_ssh.get_signing_policy(signing_policy, ca_server=None)[source]¶

Returns an SSH role formatted as a signing policy. Compatibility layer between ssh_pki and this module. This currently does not support all functionality Vault offers, e.g. dynamic principals (templates/allow_subdomains), so ssh_pki.certificate_managed might always reissue a certificate in case these options are used.

CLI Example:

salt '*' vault_ssh.get_signing_policy www

Required policy:

path "<ca_server>/roles/<signing_policy>" {
        capabilities = ["read"]
}

signing_policy: Name of the SSH role to return.
ca_server: Name of the mount point the SSH secret backend is mounted at. Defaults to ssh.

vault_ssh¶

`vault_ssh`¶