Clarify documentation around certificate issuance (#14236)

We note that:

 - allow_bare_domains, allow_glob_domains, and allow_subdomains are all
   independent,
 - enforce_hostnames and allow_wildcard_certificates take precedence over
   allow_any_name,
 - We limit to RFC 6125 wildcards.
 - Clarify that both allow_bare_domains and allow_glob_domains will permit
   wildcard issuance in certain scenarios.

Co-authored-by: mickael-hc <86245626+mickael-hc@users.noreply.github.com>
Co-authored-by: Kit Haines <kit.haines@hashicorp.com>
Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

Co-authored-by: mickael-hc <86245626+mickael-hc@users.noreply.github.com>
Co-authored-by: Kit Haines <kit.haines@hashicorp.com>

website/content/api-docs/secret/pki.mdx

@@ -800,10 +800,27 @@ request is denied.
   certificates for `localhost` as one of the requested common names. This is
   useful for testing and to allow clients on a single host to talk securely.
 
-- `allowed_domains` `(list: [])` – Specifies the domains of the role. This is
-  used with the `allow_bare_domains` and `allow_subdomains` options.
+~> **Note**: This strictly applies to `localhost` and `localdomain` when this
+   option is enabled. Additionally, even if this option is disabled, if either
+   name is included in `allowed_domains`, the match rules for that option
+   could permit issuance of a certificate for `localhost`.
 
-- `allowed_domains_template` `()bool: false)` – When set, `allowed_domains`
+- `allowed_domains` `(list: [])` – Specifies the domains of the role. This is
+  used with the `allow_bare_domains`, `allow_subdomains`, and `allow_glob_domains`
+  options to determine the type of matching between these domains and the
+  values of common name, DNS-typed SAN entries, and Email-typed SAN entries.
+  When `allow_any_name` is used, this attribute has no effect.
+
+~> **Note**: The three options `allow_bare_domains`, `allow_subdomains`, and
+   `allow_glob_domains` are each independent of each other. That is, at least
+   one type of allowed matching must describe the relationship between the
+   `allowed_domains` list and the names on the issued certificate. For example,
+   given `allowed_domain=foo.*.example.com` and `allow_subdomains=true` and
+   `allow_glob_domains=true`, a request for `bar.foo.baz.example.com` won't
+   be permitted, even though it `foo.baz.example.com` matches the glob
+   `foo.*.example.com` and `bar` is a subdomain of that.
+
+- `allowed_domains_template` `(bool: false)` – When set, `allowed_domains`
   may contain templates, as with [ACL Path Templating](/docs/concepts/policies).
 
 - `allow_bare_domains` `(bool: false)` – Specifies if clients can request
@@ -811,23 +828,51 @@ request is denied.
   configured domain set with `allowed_domains` is `example.com`, this allows
   clients to actually request a certificate containing the name `example.com` as
   one of the DNS values on the final certificate. In some scenarios, this can be
-  considered a security risk.
+  considered a security risk. Note that when an `allowed_domain` field contains
+  a potential wildcard character (for example, `allowed_domains=*.example.com`)
+  and `allow_bare_domains` and `allow_wildcard_certificates` are both enabled,
+  issuance of a wildcard certificate for `*.example.com` will be permitted.
 
 - `allow_subdomains` `(bool: false)` – Specifies if clients can request
   certificates with CNs that are subdomains of the CNs allowed by the other role
   options. _This includes wildcard subdomains._ For example, an
   `allowed_domains` value of `example.com` with this option set to true will
-  allow `foo.example.com` and `bar.example.com` as well as `*.example.com`. This
-  is redundant when using the `allow_any_name` option.
+  allow `foo.example.com` and `bar.example.com` as well as `*.example.com`. To
+  restrict issuance of wildcards by this option, see `allow_wildcard_certificates`
+  below. This option is redundant when using the `allow_any_name` option.
 
 - `allow_glob_domains` `(bool: false)` - Allows names specified in
   `allowed_domains` to contain glob patterns (e.g. `ftp*.example.com`). Clients
   will be allowed to request certificates with names matching the glob
   patterns.
 
+~> **Note**: These globs behave like shell-style globs and can match
+  across multiple domain parts. For example, `allowed_domains=*.example.com`
+  with `allow_glob_domains` enabled will match not only `foo.example.com` but
+  also `baz.bar.foo.example.com`.
+
+~> **Warning**: Glob patterns will match wildcard domains and permit their
+   issuance unless otherwise restricted by `allow_wildcard_certificates`. For
+   instance, with `allowed_domains=*.*.example.com` and both `allow_glob_domains`
+   and `allow_wildcard_certificates` enabled, we will permit the issuance of
+   a wildcard certificate for `*.foo.example.com`.
+
+- `allow_wildcard_certificates` `(bool: true)` - Allows the issuance of
+  certificates with [RFC 6125](https://tools.ietf.org/html/rfc6125) wildcards
+  in the CN field. When set to `false`, this prevents wildcards from being
+  issued even if they would've been allowed by an option above. We support
+  the following four wildcard types:
+
+  - `*.example.com`, a single wildcard as the entire left-most label,
+  - `foo*.example.com`, a single suffixed wildcard in the left-most label,
+  - `*foo.example.com`, a single prefixed wildcard in the left-most label, and
+  - `f*o.example.com`, a single interior wildcard in the left-most label.
+
 - `allow_any_name` `(bool: false)` – Specifies if clients can request any CN.
   Useful in some circumstances, but make sure you understand whether it is
-  appropriate for your installation before enabling it.
+  appropriate for your installation before enabling it. Note that both
+  `enforce_hostnames` and `allow_wildcard_certificates` are still checked,
+  which may introduce limitations on issuance with this option.
 
 - `enforce_hostnames` `(bool: true)` – Specifies if only valid host names are
   allowed for CNs, DNS SANs, and the host part of email addresses.