Skip to content

Conversation

@aarongable
Copy link
Contributor

@aarongable aarongable commented Sep 8, 2025

Add a new page to the website with the sole purpose of documenting what OIDs even are, and the OIDs we've allocated under our 1.3.6.1.4.1.44947 "ISRG" arc.

One of these OIDs, namely 1.3.6.1.4.1.44947.1.1.1 "ISRG Domain Validated", has existed for a long time but was never explicitly documented and is no longer in use.

The rest of these OIDs, namely those under the new 1.3.6.1.4.1.44947.2 "Let's Encrypt Trust Anchor IDs" arc, are brand new. We're allocating them for the purpose of being used in the "Trust Anchor Identifiers" and "Merkle Tree Certificates" internet drafts, which use OIDs as a way to compress references to CA keypairs and certificates. See https://datatracker.ietf.org/doc/draft-ietf-tls-trust-anchor-ids/ and https://datatracker.ietf.org/doc/draft-davidben-tls-merkle-tree-certs/ for more details.

Fixes #2028

@aarongable aarongable force-pushed the oid-doc branch 2 times, most recently from cb9a9ce to a568695 Compare September 8, 2025 22:44
@mcpherrinm
Copy link
Contributor

One thing we did on the CT logs page is use a JSON file of the actual data, and then template it in, so that we don't have as much translation lift.

Should we do that here, too? (I'd also like to do it on the Certificates page)

@aarongable
Copy link
Contributor Author

aarongable commented Sep 8, 2025

Yeah, it's a good idea. For now I'm just playing with presentation and layout. If this deeply-nested bulleted list looks terrible, I want to figure that out now.

Unfortunately we don't have a way to combine markdown and templating.

@mcpherrinm
Copy link
Contributor

Oof, yeah, then let's just do Markdown. I expect this page won't drift too much.

As for how it looks, I think the ever-lengthening nature of OIDs makes a more natural way to see the structure, and I'd be inclined to use a two-column table instead of a list

@mcpherrinm
Copy link
Contributor

I've tried out a table with monospaced OIDs at https://github.com/mcpherrinm/website/tree/mattm-oid-table and I think it might be a bit easier to comprehend, but I'm not sure it's still the best possible

@aarongable aarongable marked this pull request as ready for review September 25, 2025 00:23
@aarongable
Copy link
Contributor Author

I think the table, using <code> and <b> for the OIDs, ends up looking pretty good as rendered by our website:
deploy-preview-2034--letsencrypt netlify app_docs_oids_

I'm marking this as Ready for Review. At this point I think the two big things to check are:

  1. Are these the OID assignments we want to use?
  2. Have I made any typos / mis-alignments between the new oids page and the certificates page?

@pgporada
Copy link
Member

When we accept and merge this, I'll see about adding these OIDs as children to https://oid-base.com/cgi-bin/display?oid=1.3.6.1.4.1.44947&a=display

@beautifulentropy beautifulentropy self-requested a review September 25, 2025 16:57
Copy link
Member

@beautifulentropy beautifulentropy left a comment

Choose a reason for hiding this comment

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

Looks good to me. Please update the description to reflect your changes.

@jsha
Copy link
Contributor

jsha commented Sep 25, 2025

The OID page and the assignment of OIDs on it look good to me.

I'd prefer to document these on just the OID page for now, to avoid the chance of mismatches between that page and the certificates / Chain of Trust page.

@aarongable
Copy link
Contributor Author

That's a good point. I've removed the OIDs from the certificates page, and replaced them with one sentence at the top linking readers to the new doc.

@aarongable aarongable requested a review from jsha September 25, 2025 17:16
Copy link
Contributor

@jsha jsha left a comment

Choose a reason for hiding this comment

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

Looks great.

I was looking for the official standard for OIDs and am again annoyed that the ISO/IEC standards are not freely available: https://www.iso.org/standard/81417.html. Probably not useful to link because of that.

@jsha
Copy link
Contributor

jsha commented Sep 25, 2025

Also, a question: why are these OIDs described as representing "trust anchors" rather than "issuers"? I think the latter is more general as it can encompass the roles of both roots and intermediates.

@aarongable aarongable merged commit 5d2223e into main Sep 25, 2025
5 checks passed
@aarongable aarongable deleted the oid-doc branch September 25, 2025 17:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Assign OIDs to our trust anchors for Photosynthesis

6 participants