Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
Glossary: Fix #380 #415
A glossary of main terms related to Let's Encrypt and PKI
As the objective is to help people with not enough knowledge of the PKI I tried to include most terms that can be found in the Let's Encrypt website.
I assumed a minimal knowledge, so terms such as DNS are not present (It may be a mistake, please tell me if you felt differently)
Some terms with few relation to Let's Encrypt or PKI may be present because:
Please tell me if you feel some terms should be removed.
I may have over engineered the definition macro, but I felt it was important for accessibility (especially for screen readers, to know the language and if it's an acronym)
Terms that could be added: JWS, API, SSL/TLS, QUIC, SPDY, TCP, UDP, DNS, HTTP, HTTP/2, HTTPS, IP, IPv4, IPv6, SSH, NPN, ALPN, CBC, GCM, AES, SHA, MD5, Forward Secrecy, hash function, Cipher Suites.
Some definitions use a small extract from their Wikipedia article or are inspired by it. It's only short extract and there is a link to the Wikipedia in the end of the definition, by maybe I should add a small text in the end of the page indicating it (with full license information), or rewrite them to not be so close of the Wikipedia article?
Changes other than
Here is the paste of the rendered text as an example:
ACME Client: A software capable to communicate with an ACME server to ask for a certificate.
Okay, I've pushed those. There was one other tweak I wanted to get your thoughts on: For some of these terms, the acronym is the more typical way to write it, and the expansion is more rare. So for those I think it makes sense to put the acronym first. For instance, "DANE", "OCSP" and "TLS" would fit into that category, but probably not "Certificate Transparency."
What would you think of just swapping the "name" and "abbr" fields in that case? Or we could change the "abbr" field to "alt" to capture the fact that it wouldn't always be an abbreviation?
E.g. it might look like:
TLS (Transportation Security Layer): ... definition ...
tdelmas left a comment
I think an option for the def macro called "abbr_first" should do it. (If it's not an abbreviation, it should be in the name, so the order is the one we choose for the content of the name, no?)
Another point: to be consistent, I think IDs should be upper-case for abbreviations and lower-case for other, I made the mistake for "Key-pair", can I fix it to be "key-pair"?
jsha left a comment
Great, I like your fixes! Ok to merge.
I also like the idea of incorporating abbr_first into the macro, please do go ahead with that.
And yes, I'm all in favor of making the id capitalization more consistent.
Thanks so much! I'm really excited about this.
I've merge my suggestions with your comments and the key-pair id
I've added the abbr_first argument and used it for SSL, TLS, OCSP, ECDSA, EdDSA
I've added an entry "End-user certificate" that point to "Leaf certificate (end-entity certificate)" (I didn't mentioned end-user in the leaf definition because it's not the "correct" term, but feel free to do it). I've seen it a lot, for example a google search for the exact term "end-entity certificate"+"certificate authority" gives 9 200 results https://www.google.com/search?q=%22end-entity+certificate%22+%22certificate+authority%22 when "end-user certificate"+"certificate authority" gives 17 400 results https://www.google.com/search?q=%22end-user+certificate%22+%22certificate+authority%22
Another point: I feel we should talk about "web client" and not "browser" in the "OCSP Must-Staple" and "OCSP stapling" definitions, should I fix it ? (it may be fixed latter too)
Google's results counts are very approximate, especially for complex queries (e.g. with quotes). I don't think we can deduce popularity from them. I note that the first results for "end-user certificate" by itself is https://en.wikipedia.org/wiki/End-user_certificate, which suggests that the term is about the arms trade.
I think when you search for ["end-user certificate" "certificate authority"] you are seeing sporadic cases of documentation authors making a mistake. For instance, the top result is this DNSimple page, which says "end-user": https://support.dnsimple.com/articles/what-is-ssl-certificate-chain/. But we can't conclude that DNSimple prefers "end-user." Look at these two searches:
I'd prefer to leave out "end-user certificate." I believe it's a term of art in another field, and usually a mistake when written in the PKI world, and I would prefer that we not be responsible for introducing another confusing synonym for end-entity certificate (or leaf certificate or server certificate).
I slightly prefer to talk about "browser" whenever possible. I think it favors clarity over generality. But I don't feel too strongly about this.
I'm doing what will probably be my last round of review before merging. I noticed a small bug in the JS: When I hover over "issuer URI" in the definition "Authority Information Access (AIA): A certificate extension used to indicate to user agents how to obtain information about the issuer of the certificate. It typically specifies the OCSP URI and the issuer URI.", the tooltip is for "Certificate authority" (#def-CA) rather "Certificate Authority Issuer" (#def-CAI).
Fix also fixed a few links, but I didn't succeed to reproduce your title bug... I see the correct (for CAI) tooltip over "issuer URI".
Thank you very much for the time you spent on it!
I think it's good enough to be merged, if somebody wants to add or improve something it always can be done later.
Once this PR is merge, I'll try to work fast on its translation, to give other translators an example.