Skip to content

Clarify Keyless SSL certificates and add DNS-only key server note#31788

Open
baubuchon-cf wants to merge 2 commits into
productionfrom
keyless-cert-clarity
Open

Clarify Keyless SSL certificates and add DNS-only key server note#31788
baubuchon-cf wants to merge 2 commits into
productionfrom
keyless-cert-clarity

Conversation

@baubuchon-cf

Copy link
Copy Markdown
Collaborator

Improves the Keyless SSL "Public DNS" setup page:

  • Adds a Certificates used in Keyless SSL section with a table distinguishing the edge (Keyless SSL) certificate (SAN = site hostnames) from the key server authentication certificate (SAN = key server hostname).
  • Adds a caution: do not add the key server hostname to the public edge cert SAN — not required, and it leaks internal hostnames into Certificate Transparency logs.
  • Adds a note that a key server hostname on a Cloudflare zone must use a DNS-only (grey-cloud) record, or the edge returns NXDOMAIN and the handshake fails.

…r note

Adds a "Certificates used in Keyless SSL" section to the Public DNS setup page distinguishing the edge (Keyless SSL) certificate from the key server authentication certificate, with a caution against adding the key server hostname to the public edge cert SAN (unnecessary; leaks internal hostnamesinto CT logs). Also adds a note that a key server hostname on a Cloudflare zone
must use a DNS-only (grey-cloud) record to avoid NXDOMAIN handshake failures.
@baubuchon-cf baubuchon-cf requested review from a team and elithrar as code owners June 29, 2026 20:54
@cloudflare-docs-bot

cloudflare-docs-bot Bot commented Jun 29, 2026

Copy link
Copy Markdown
Contributor

Review

⚠️ 1 warning found in full PR diff.

Code Review

This code review is in beta and may not always be helpful — use your judgment.

Warnings (1)
File Issue
ssl/keyless-ssl/configuration/public-dns.mdx line 42 Inaccurate technical claim about proxied DNS records — The note states 'If the record is proxied or missing, Cloudflare's edge resolver returns NXDOMAIN'. A proxied record does not return NXDOMAIN; it resolves to Cloudflare proxy IPs. NXDOMAIN is returned only when the record is missing. Fix: Clarify that a missing DNS record causes NXDOMAIN, while a proxied record resolves to Cloudflare IPs; both break Keyless SSL, but the failure modes differ.

Conventions

Checks PR title, description, and redirect checklist.

No convention issues found.

Style Guide Review

No style-guide issues found.

Redirects

No missing redirect entries found.

Commands

Only codeowners can run commands. Post a comment with the command to trigger it.

Command Description
/review Runs a review now. Incremental if a prior review exists, full if not.
/full-review Re-reviews the entire PR diff from scratch, ignoring incremental history. Useful after a rebase, when you want a fresh review, or if the bot gets out of sync and reports issues that no longer exist.
/ignore-review-limit Permanently lifts the 2-review automatic limit for this PR. Future pushes will trigger reviews as normal.
/disable-auto-review Stops automatic reviews from triggering on future pushes to this PR. Codeowners can still run /review or /full-review manually.

@github-actions

Copy link
Copy Markdown
Contributor

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern Owners
/src/content/docs/ssl/ @baubuchon-cf, @cloudflare/appsec-reviewers, @elithrar, @cloudflare/product-owners

@ask-bonk ask-bonk Bot added the documentation Documentation edits label Jun 29, 2026

@ask-bonk ask-bonk Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good clarifications for a common setup error. 3 inline suggestions for style-guide alignment.

LOW: The new concept section sits between numbered steps 1 and 2, which breaks the procedural flow. Consider placing it before step 1 or within step 2.

Comment thread src/content/docs/ssl/keyless-ssl/configuration/public-dns.mdx Outdated

## Certificates used in Keyless SSL

Keyless SSL involves **two different certificates**. Confusing them is the most common setup error.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Define the acronym before it appears in the table below:

Suggested change
Keyless SSL involves **two different certificates**. Confusing them is the most common setup error.
Keyless SSL involves **two different certificates**, each with a different Subject Alternative Name (SAN). Confusing them is the most common setup error.


Keyless SSL involves **two different certificates**. Confusing them is the most common setup error.

| Certificate | What it is | SAN should contain |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Expand the acronym for accessibility:

Suggested change
| Certificate | What it is | SAN should contain |
| Certificate | What it is | Subject Alternative Name (SAN) should contain |

@ask-bonk

ask-bonk Bot commented Jun 29, 2026

Copy link
Copy Markdown
Contributor

Reviewed PR #31788 and posted suggestions. Here's a summary:

Labels applied

  • Added documentation (existing: product:ssl, size/s)

What the PR changes

  • Adds a :::note admonition warning that a key server hostname on a Cloudflare zone must use a DNS-only record; if proxied or missing, the edge returns NXDOMAIN.
  • Adds a new Certificates used in Keyless SSL section (between steps 1 and 2) with a table distinguishing the edge certificate from the key server authentication certificate.
  • Adds a :::caution admonition: do not add the key server hostname to the public edge cert SAN, because it leaks internal hostnames into Certificate Transparency logs.

Issues flagged

  • MEDIUM: The note uses "certificate SAN" before the acronym is defined. The table header also uses "SAN" without expansion. Suggested spelling out Subject Alternative Name (SAN) on first use in both the prose and the table header.
  • MEDIUM: "Keyless TLS handshake" is inconsistent with the page's use of Keyless SSL everywhere else. Suggested aligning terminology.
  • LOW: "grey-clouded" is non-standard; suggested DNS-only (grey cloud) to match phrasing used elsewhere in the docs.
  • LOW: The new concept section breaks the numbered procedure between steps 1 and 2. Flagged for potential relocation before step 1 or within step 2.

No build-breaking issues (valid frontmatter, no unescaped MDX characters, components already imported).

github run

Co-authored-by: ask-bonk[bot] <249159057+ask-bonk[bot]@users.noreply.github.com>
@baubuchon-cf

Copy link
Copy Markdown
Collaborator Author

/full-review

@github-actions

Copy link
Copy Markdown
Contributor

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Documentation edits product:ssl Related to SSL size/s

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants