PKI: enforce_hostnames=false does not allow underscores in DNS SANs

[aloeenmae]

Describe the bug

The enforce_hostnames=false role parameter does not allow underscores in DNS SANs, contradicting the official PKI API documentation which states:

enforce_hostnames (bool: true) - Specifies if only valid host names are allowed for CNs, DNS SANs, and the host part of email addresses.
The documentation implies that setting enforce_hostnames=false should relax hostname validation (including the "no underscores" rule) for DNS SANs. In practice, DNS SANs containing underscores are always rejected regardless of this setting:

• In v1.20.3 (and earlier): the invalid SAN is silently dropped from the issued certificate with no warning or error.
• In the current main branch: the request errors out with "subject alternate name <name> is not a valid DNS name and cannot be included as a SAN".
  Neither behavior matches the documentation's promise.
  Root cause: the hostnameRegex in issue_common.go does not allow underscores, and the regex check at SAN extraction is independent of role.EnforceHostnames. The EnforceHostnames flag is only consulted later in ValidateNames, which is after the underscore SAN has already been stripped or rejected.

To Reproduce

Steps to reproduce the behavior:

1. Enable PKI and generate a root CA
2. Create a role with the most permissive settings:

allow_any_name=true
enforce_hostnames=false
allow_wildcard_certificates=true
max_ttl=168h

3. Verify role settings:

vault read pki/roles/test -format=json | jq '.data | {enforce_hostnames, allow_any_name}'
{
  "enforce_hostnames": false,
  "allow_any_name": true
}

4. Issue a certificate with an underscore in alt_names:

vault write pki/issue/test
common_name="test.example.com"
alt_names="with-hyphen.example.com,with_underscore.example.com"
-format=json | jq -r '.data.certificate' | openssl x509 -noout -text | grep -A3 "Subject Alternative Name"

output:

            X509v3 Subject Alternative Name:
                DNS:test.example.com, DNS:with-hyphen.example.com

Expected behavior

With enforce_hostnames=false (and allow_any_name=true, allow_wildcard_certificates=true), DNS SANs containing underscores should be accepted and included in the issued certificate, per the documentation.
Alternatively, if this is intentional, the documentation should be updated to clarify that hostname format validation (specifically the hostnameRegex check at SAN extraction) is always enforced on DNS SANs regardless of enforce_hostnames.

Environment:

• Vault Server Version (retrieve with vault status): Vault v1.20.3
• Vault CLI Version (retrieve with vault version): v1.20.3
• Server Operating System/Architecture: Linux amd64

Additional context

• Underscores in the CN work correctly (fixed in PKI Secrets Engine: underscores not permitted in common_name value #3876 for Vault 0.9.4), but that fix was not extended to DNS SANs.

• The current main branch changed the behavior from silent drop to explicit error (see issue_common.go), but the core issue — that enforce_hostnames=false does not actually relax DNS SAN hostname validation as documented — remains unaddressed.

• Workaround: names with underscores can be placed in the CN (which is then automatically copied to SANs only if it's a valid hostname, so underscore-containing CNs don't appear in SANs either), or passed via uri_sans with a URI scheme prefix.

[dosubot]

This is a well-investigated bug report — I can confirm the root cause analysis is accurate based on the code.

The issue is a validation ordering problem. DNS SANs go through two stages of validation:

1. Stage 1 (always active): During SAN extraction, every name is checked against wildHostnameRegex [1], which only allows [a-zA-Z0-9-] in labels — no underscores. Names that fail this check are immediately rejected [2] before any role settings are consulted.

2. Stage 2 (role-aware): ValidateNames() is called afterward [3], where enforce_hostnames=false combined with allow_any_name=true would correctly bypass hostname validation via a continue statement [4]. But by this point, underscore-containing names have already been filtered out in Stage 1.

So enforce_hostnames=false never gets a chance to do its job for DNS SANs — the early regex filter runs unconditionally. This matches the original issue #3876 [5], which fixed underscores in the CN path, but the fix was not extended to DNS SANs.

A potential fix would be to make the wildHostnameRegex check in Stage 1 conditional on role.EnforceHostnames, or to use a more permissive regex at that stage that still validates basic DNS label structure (e.g., no spaces, proper dot-separation) while deferring the strict hostname rules to ValidateNames() where role settings are respected.

Tagging @heatherezell to flag this for product and engineering review.

Written by @dosu, approved by heatherezell

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[aloeenmae]

The same underscore DNS SAN is handled differently depending on how it's provided:

1. Via alt_names API parameter → silently dropped (v1.20.3) or rejected (main branch)
2. Via a CSR with use_csr_sans=true (default for pki/sign/) → accepted and included in the issued certificate
   This confirms the underscore SAN is not fundamentally rejected by Vault's issuance logic — only the alt_names path applies the restrictive hostnameRegex filter before ValidateNames / EnforceHostnames is consulted. The CSR path skips hostnameRegex and goes straight to ValidateNames, where enforce_hostnames=false correctly relaxes the validation.

Reproduction showing the inconsistency:

openssl req -new -newkey ec:<(openssl ecparam -name prime256v1) -nodes -keyout key.pem -out csr.pem -subj "/CN=test.example.com" -addext "subjectAltName=DNS:with_underscore.example.com"

Sign via CSR path - underscore SAN is preserved

vault write pki/sign/test csr=@csr.pem \
  -format=json | jq -r '.data.certificate' | \
  openssl x509 -noout -text | grep -A3 "Subject Alternative Name"

output:

            X509v3 Subject Alternative Name:
                DNS:test.example.com, DNS:with_underscore.example.com