From 4a7dece3fbc65b0806fa31df91e676ddde3f8473 Mon Sep 17 00:00:00 2001 From: Steven Clark Date: Tue, 19 Oct 2021 09:30:06 -0400 Subject: [PATCH] Update website docs regarding ssh role allowed_extensions parameter (#12857) * Update website docs regarding ssh role allowed_extensions parameter - Add note within the upgrading to 1.9.0 about behaviour change - Prefix the important note block within the main documentation about signed ssh certificates that it applies pre-vault 1.9 - Update api docs for the allowed_extensions parameter within the ssh role parameter. * Apply suggestions from code review Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> --- website/content/api-docs/secret/ssh.mdx | 7 ++++--- .../docs/secrets/ssh/signed-ssh-certificates.mdx | 6 +++--- website/content/docs/upgrading/upgrade-to-1.9.0.mdx | 13 +++++++++++++ 3 files changed, 20 insertions(+), 6 deletions(-) diff --git a/website/content/api-docs/secret/ssh.mdx b/website/content/api-docs/secret/ssh.mdx index a5087d0ca8..41bfc70a32 100644 --- a/website/content/api-docs/secret/ssh.mdx +++ b/website/content/api-docs/secret/ssh.mdx @@ -161,9 +161,10 @@ This endpoint creates or updates a named role. 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 any extensions, - set this to an empty string. Will default to allowing any extensions. +- `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](https://man.openbsd.org/sshd#AUTHORIZED_KEYS_FILE_FORMAT) `AUTHORIZED_KEYS FILE FORMAT` section. You should add a `permit-` before the diff --git a/website/content/docs/secrets/ssh/signed-ssh-certificates.mdx b/website/content/docs/secrets/ssh/signed-ssh-certificates.mdx index 4e6cfa05a5..da11fce94c 100644 --- a/website/content/docs/secrets/ssh/signed-ssh-certificates.mdx +++ b/website/content/docs/secrets/ssh/signed-ssh-certificates.mdx @@ -99,9 +99,9 @@ team, or configuration management tooling. 1. Create a named Vault role for signing client keys. - ~> **IMPORTANT NOTE:** If `"allowed_extensions"` is either empty or not specified in the role, - [Vault will assume permissive defaults](/api/secret/ssh#allowed_extensions): any user assigned - to the role would be able to specify any arbitrary extension values as part of the certificate request to the Vault server. + ~> **IMPORTANT NOTE:** Prior to Vault-1.9, if `"allowed_extensions"` is either empty or not specified in the role, + Vault will assume permissive defaults: any user assigned to the role may specify any arbitrary + extension values as part of the certificate request to the Vault server. This may have significant impact on third-party systems that rely on an `extensions` field for security-critical information. In those cases, consider using a template to specify default extensions, and explicitly setting `"allowed_extensions"` to an arbitrary, non-empty string if the field is empty or not set. diff --git a/website/content/docs/upgrading/upgrade-to-1.9.0.mdx b/website/content/docs/upgrading/upgrade-to-1.9.0.mdx index b601082dc3..c88c7eaec9 100644 --- a/website/content/docs/upgrading/upgrade-to-1.9.0.mdx +++ b/website/content/docs/upgrading/upgrade-to-1.9.0.mdx @@ -25,3 +25,16 @@ All calls to [create or update a role](https://www.vaultproject.io/api/secret/id must be checked to ensure that roles are not being created or updated with non-existent keys. +### SSH Role Parameter `allowed_extensions` Behavior Change + +Prior versions of Vault allowed clients to specify any extension when requesting +SSH certificate [signing requests](https://www.vaultproject.io/api/secret/ssh#sign-ssh-key) +if their role had an `allowed_extensions` set to `""` or was missing. + +Now, Vault will reject a client request that specifies extensions if the role +parameter `allowed_extensions` is empty or missing from the role they are +associated with. + +To re-enable the old behavior, update the roles with a value +of `"*"` to the `allowed_extensions` parameter allowing any/all extensions to be +specified by clients.