Skip to content

Files

Latest commit

brewgatorbrewgator
Remove Test Runs from Examples (#176)
Nov 14, 2023
fa4b183 · Nov 14, 2023

History

History
253 lines (198 loc) · 12.3 KB
·

secret-ssh-issue.md

File metadata and controls

253 lines (198 loc) · 12.3 KB
·

Signed SSH Secret Issue Configuration Options

This benchmark tests the performance of Signed SSH Certificate issue operations.

Test Parameters

Role Config role

  • name (string: "benchmark-role") – Specifies the name of the role to create. This is part of the request URL.

  • default_user (string: "") – Specifies the default username for which a credential will be generated. When the endpoint creds/ is used without a username, this value will be used as default username. Its recommended to create individual roles for each username to ensure absolute isolation between usernames. This is required for OTP type roles.

    When default_user_template is set to true, this field can contain an identity template with any prefix or suffix, like ssh-{{identity.entity.id}}-user.

    For the CA type, if you wish this to be a valid principal, it must also be in allowed_users.

  • default_user_template (bool: false) - If set, default_users can be specified using identity template values. A non-templated user is also permitted.

  • cidr_list (string: "") – Specifies a comma separated list of CIDR blocks for which the role is applicable for. It is possible that a same set of CIDR blocks are part of multiple roles. This is a required parameter, unless the role is registered under the /config/zeroaddress endpoint. Note: [Not applicable for CA type]

  • exclude_cidr_list (string: "") – Specifies a comma-separated list of CIDR blocks. IP addresses belonging to these blocks are not accepted by the role. This is particularly useful when big CIDR blocks are being used by the role and certain parts need to be kept out. Note: [Not applicable for CA type]

  • port (int: 22) – Specifies the port number for SSH connection. Port number does not play any role in OTP generation. For the otp secrets engine type, this is just a way to inform the client about the port number to use. The port number will be returned to the client by Vault along with the OTP.

  • key_type (string: "ca") – Specifies the type of credentials generated by this role. This can be either otp or ca.

  • allowed_users (string: "") – If this option is not specified, or if it is *, the client can request a credential for any valid user at the remote host, including the admin user. To only allow an explicit list of users, set this parameter using a comma-separated username list to enforce it. When this parameter is set, the credentials are created only for default_user and usernames listed. Setting this option will enable all the users with access this role to fetch credentials for all other usernames in this list. When allowed_users_template is set to true, this field can contain an identity template with any prefix or suffix, like ssh-{{identity.entity.id}}-user. Use with caution. N.B.: if the type is ca, an empty list does not allow any user; instead you must use * to enable this behavior.

  • allowed_users_template (bool: false) - If set, allowed_users can be specified using identity template policies. Non-templated users are also permitted.

  • allowed_domains (string: "") – A comma-separated list of domains for which a client can request a host certificate. If this option is explicitly set to "*", then credentials can be created for any domain. See also allow_bare_domains and allow_subdomains.

  • allowed_domains_template (bool: false) - If set, allowed_domains can be specified using identity template policies. Non-templated domains are also permitted.

  • ttl (string: "") – Specifies the Time To Live value provided as a string duration with time suffix. Hour is the largest suffix. If not set, uses the system default value or the value of max_ttl, whichever is shorter.

  • max_ttl (string: "") – Specifies the maximum Time To Live provided as a string duration with time suffix. Hour is the largest suffix. If not set, defaults to the system maximum lease TTL.

  • allowed_critical_options (string: "") – Specifies a comma-separated list of critical options that certificates can have when signed. To allow any critical options, set this to an empty string. Will default to allowing any critical options.

  • allowed_extensions (string: "") – Specifies a comma-separated list of extensions that certificates can have when signed. To allow a user to specify any extension, set this to "*". If not set, users will not be allowed to specify extensions and will get the extensions specified within default_extensions. 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<string|string>: "") – Specifies a map of critical options certificates should have if none are provided when signing. This field takes in key value pairs in JSON format. Note that these are not restricted by allowed_critical_options. Defaults to none.

  • default_extensions (map<string|string>: "") – Specifies a map of extensions certificates should have if none are provided when signing. This field takes in key value pairs in JSON format. Note that these are not restricted by allowed_extensions. Defaults to none.

  • allow_user_certificates (bool: true) – Specifies if certificates are allowed to be signed for use as a 'user'.

  • allow_host_certificates (bool: false) – Specifies if certificates are allowed to be signed for use as a 'host'.

  • allow_bare_domains (bool: false) – Specifies if host certificates that are requested are allowed to use the base domains listed in allowed_domains, e.g. "example.com". This is a separate option as in some cases this can be considered a security threat.

  • allow_subdomains (bool: false) – Specifies if host certificates that are requested are allowed to be subdomains of those listed in allowed_domains, e.g. if "example.com" is part of allowed_domains, this allows "foo.example.com".

  • allow_user_key_ids (bool: false) – Specifies if users can override the key ID for a signed certificate with the "key_id" field. When false, the key ID will always be the token display name. The key ID is logged by the SSH server and can be useful for auditing.

  • key_id_format (string: "") – When supplied, this value specifies a custom format for the key id of a signed certificate. The following variables are available for use: '{{token_display_name}}' - The display name of the token used to make the request. '{{role_name}}' - The name of the role signing the request. '{{public_key_hash}}' - A SHA256 checksum of the public key that is being signed. e.g. "custom-keyid-{{token_display_name}}"

  • allowed_user_key_lengths (map<string|(int|[]int|string)>: "") – Specifies a map of ssh key types and their expected sizes which are allowed to be signed by the CA type. To specify multiple sizes, either use a comma-separated list or an array of allowed key widths. We support both OpenSSH-style key identifiers and short names (rsa, ecdsa, dsa, or ed25519) as keys. For example, a valid policy to allow common RSA and ECDSA key lengths might be:

    {
  "rsa": [2048, 3072, 4096],
  "ec": 256,
  "ecdsa-sha2-nistp521": 0
}

    Note that when an algorithm identifier uniquely specifies a key length (such as with ecdsa-sha2-nistp256 or ed25519), the value of the length is ignored (and can be zero).

    ~> Note: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used: ed25519.

  • algorithm_signer (string: "default") - Algorithm to sign keys with. Valid values are ssh-rsa, rsa-sha2-256, rsa-sha2-512, or default. This value may also be left blank to use the signer's default algorithm, and must be left blank or have value default for CA key types other than RSA.

    ~> Note: The value of default may change over time as vulnerabilities in algorithms are discovered. The present value for RSA keys is equivalent to rsa-sha2-256.

    ~> Warning: The algorithm_signer value ssh-rsa uses the SHA-1 hash algorithm. This algorithm is now considered insecure and is not supported by current OpenSSH versions. As a result, Vault has made the new default rsa-sha2-256 for RSA CA keys. It is strongly encouraged for all users to migrate to rsa-sha2-256 or default if the role was created with an explicit algorithm_signer=rsa-sha parameter or has been migrated to such.

  • not_before_duration (duration: "30s") – Specifies the duration by which to backdate the ValidAfter property. Uses duration format strings.

CA Config ca

  • private_key (string: "") – Specifies the private key part the SSH CA key pair; required if generate_signing_key is false.

  • public_key (string: "") – Specifies the public key part of the SSH CA key pair; required if generate_signing_key is false.

  • generate_signing_key (bool: true) – Specifies if Vault should generate the signing key pair internally. If true, an RSA key pair is generated, and the generated public key is returned so you can add it to your configuration. If false, then you must provide private_key and public_key, but these can be of any valid signing key type.

  • key_type (string: "rsa") - Specifies the desired key type for the generated SSH CA key when generate_signing_key is set to true. Valid values are OpenSSH key type identifiers (ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, or ssh-ed25519) or an algorithm (rsa, ec, or ed25519).

    ~> Note: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used: ed25519.

  • key_bits (int: 0) - Specifies the desired key bits for the generated SSH CA key when generate_signing_key is set to true. This is only used for variable length keys (such as ssh-rsa, where the value of key_bits specifies the size of the RSA key pair to generate; with the default 0 value resulting in a 4096-bit key) or when the ec algorithm is specified in key_type (where the value of key_bits identifies which NIST P-curve to use; 256, 384, or 521, with the default 0 value resulting in a NIST P-256 key).

Issued Cert Config issued_cert

  • name (string: "benchmark-key") – Specifies the name of the role to create the certificate against. This is part of the request URL.

  • key_type (string: "rsa") – Specifies the desired key type; must be rsa, ed25519 or ec.

  • key_bits (int: 0) – Specifies the number of bits to use for the generated keys. Allowed values are 0 (universal default); with key_type=rsa, allowed values are: 2048 (default), 3072, or 4096; with key_type=ec, allowed values are: 256 (default), 384, or 521; ignored with key_type=ed25519.

  • ttl (string: "") – Specifies the Requested Time To Live. Cannot be greater than the role's max_ttl value. If not provided, the role's ttl value will be used. Note that the role values default to system values if not explicitly set.

  • valid_principals (string: "") – Specifies valid principals, either usernames or hostnames, that the certificate should be signed for.

  • cert_type (string: "user") – Specifies the type of certificate to be created; either "user" or "host".

  • key_id (string: "") – Specifies the key id that the created certificate should have. If not specified, the display name of the token will be used.

  • critical_options (map<string|string>: "") – Specifies a map of the critical options that the certificate should be signed for. Defaults to none.

  • extensions (map<string|string>: "") – Specifies a map of the extensions that the certificate should be signed for. Defaults to none.

Example Configuration

test "ssh_issue" "ssh_issue_test1" {
        weight = 100
        config {
                role {
                        allow_user_certificates = true
                }
                issued_cert {
                        key_type = "rsa"
                        key_bits = 4096
                }
        }
}