Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Glossary: Fix #380 #415

Merged
merged 47 commits into from Jan 7, 2019

Conversation

Projects
None yet
3 participants
@tdelmas
Copy link
Contributor

commented Nov 10, 2018

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:

  • They are used in other definitions
  • Helps to contrast some definitions (such as "Web server"/"Web client" to contrast with "ACME server"/"ACME client")

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)
And if somebody have more knowledge about accessibility please step in!

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 glossary.md:

  • I had to add beforeColon in config.toml for i18n.
  • glossary.css to add an highlight on the defined word when switching from a definition to another by clicking on an internal link (useful to see when the definition starts when clicking on a word to see it's definition)
  • glossary.js to add on internal links pointing to another definition, that definition on the title (useful to see the definition of a word without having to click a word to see it's definition)
  • docs/_index.md to add the link to glossary.md
  • layouts/shortcodes/def.html for the def hugo shortcode

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.
ACME Server: An ACME-compatible server capable to generate certificates. Let’s Encrypt software, Boudler, is ACME-compatible. Boulder divergences from ACME
Automatic Certificate Management Environment (ACME): The protocol implemented by Let’s Encrypt. Softwares compatibles with that protocol can use it to communicate with Let’s Encrypt to ask for a certificate. ACME draft 16 - Wikipedia
Boudler: The software implementing ACME, developed and used by Let’s Encrypt. GitHub

@jmorahan
Copy link
Contributor

left a comment

just some spellings

Show resolved Hide resolved content/en/docs/glossary.md Outdated
Show resolved Hide resolved content/fr/docs/glossary.md Outdated
Show resolved Hide resolved content/fr/docs/glossary.md Outdated
Show resolved Hide resolved content/en/docs/glossary.md Outdated

jmorahan and others added some commits Nov 11, 2018

Update content/en/docs/glossary.md
Co-Authored-By: tdelmas <github@tdelmas.eu>
Update content/fr/docs/glossary.md
Co-Authored-By: tdelmas <github@tdelmas.eu>
Update content/fr/docs/glossary.md
Co-Authored-By: tdelmas <github@tdelmas.eu>
Update content/en/docs/glossary.md
Co-Authored-By: tdelmas <github@tdelmas.eu>

@tdelmas tdelmas changed the title [WIP] Glossary: Fix #380 Glossary: Fix #380 Dec 30, 2018

jsha added some commits Jan 3, 2019

Add root program and Web PKI.
Also correct some broken internal references for "web browser."
Consolidate "property" and "field" to "extension"
Note that Subject and Issuer are still described as "fields" since they
are not extensions.
@jsha

This comment has been minimized.

Copy link
Contributor

commented Jan 3, 2019

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 ...
DANE (DNSSEC-based Authentication of Named Entities): ... definition ...

@tdelmas

This comment has been minimized.

Copy link
Contributor Author

commented Jan 3, 2019

@jsha Thank you! I should have time to write an answer tonight. I put back the "WIP" in the title

@tdelmas tdelmas changed the title Glossary: Fix #380 [WIP] Glossary: Fix #380 Jan 3, 2019

@tdelmas
Copy link
Contributor Author

left a comment

Hi @jsha, here is my feedback, I've read your diff ( tdelmas/website@d2a7422...730d40e ) and I like the additions you made.

I've left a few comments (I don't know if Github will let you merge automatically my suggestions, if not, you can just answer "ok for merge" and I'll do it)

Show resolved Hide resolved content/en/docs/glossary.md Outdated
Show resolved Hide resolved content/en/docs/glossary.md Outdated

{{% def id="ISRG" name="Internet Security Research Group" abbr="ISRG" %}} The organization behind [Let's Encrypt](#def-LE): https://www.abetterinternet.org/about/. [Wikipedia](https://en.wikipedia.org/wiki/Internet_Security_Research_Group) {{% /def %}}

{{% def id="Issuer" name="Issuer" %}} A certificate field describing which certificate signed the current one. For instance, the Issuer field of a Let's Encrypt end-entity certificate might be "Issuer: C = US, O = Let's Encrypt, CN = Let's Encrypt Authority X3". It commonly contains fields like [Common Name](#def-CN), Country, and Organization. The Issuer field always matches some certificate's [Subject](#def-Subject) field. For [self-signed](#def-self-signed) certificates like [roots](#def-root), the Issuer is the same as the Subject. The term "issuer" may also be used to indicate a certificate that issues other certificates (an [intermediate](#def-intermediate) or root), or an organization that issues certificates.{{% /def %}}

This comment has been minimized.

Copy link
@tdelmas

tdelmas Jan 4, 2019

Author Contributor

"Issuer" seams too generic for me, I think "Certificate issuer" is better

Suggested change
{{% def id="Issuer" name="Issuer" %}} A certificate field describing which certificate signed the current one. For instance, the Issuer field of a Let's Encrypt end-entity certificate might be "Issuer: C = US, O = Let's Encrypt, CN = Let's Encrypt Authority X3". It commonly contains fields like [Common Name](#def-CN), Country, and Organization. The Issuer field always matches some certificate's [Subject](#def-Subject) field. For [self-signed](#def-self-signed) certificates like [roots](#def-root), the Issuer is the same as the Subject. The term "issuer" may also be used to indicate a certificate that issues other certificates (an [intermediate](#def-intermediate) or root), or an organization that issues certificates.{{% /def %}}
{{% def id="issuer" name="Certificate issuer" %}} A certificate field describing which certificate signed the current one. For instance, the Issuer field of a Let's Encrypt end-entity certificate might be "Issuer: C = US, O = Let's Encrypt, CN = Let's Encrypt Authority X3". It commonly contains fields like [Common Name](#def-CN), Country, and Organization. The Issuer field always matches some certificate's [Subject](#def-Subject) field. For [self-signed](#def-self-signed) certificates like [roots](#def-root), the Issuer is the same as the Subject. The term "issuer" may also be used to indicate a certificate that issues other certificates (an [intermediate](#def-intermediate) or root), or an organization that issues certificates.{{% /def %}}

This comment has been minimized.

Copy link
@jsha

jsha Jan 4, 2019

Contributor

This makes sense, but now I think the text should be:

{{% def id="issuer" name="Certificate issuer" %}} The "Issuer" field of a certificate describes which certificate signed the current one. For instance, the Issuer field of a Let's Encrypt end-entity certificate might be "Issuer: C = US, O = Let's Encrypt, CN = Let's Encrypt Authority X3". It commonly contains fields like [Common Name](#def-CN), Country, and Organization. The Issuer field always matches some certificate's [Subject](#def-Subject) field. For [self-signed](#def-self-signed) certificates like [roots](#def-root), the Issuer is the same as the Subject. The term "issuer" may also be used to indicate a certificate that issues other certificates (an [intermediate](#def-intermediate) or root), or an organization that issues certificates.{{% /def %}}

i.e. start with "The "Issuer" field of a certificate describes"


{{% def id="staging" name="Staging" %}} [Let's Encrypt](#def-LE) provides a staging API to test certificate request without impacting rate limits. Certificates generated by the staging environment are *not* publicly trusted. The staging environment should be used for testing, debugging, and ACME client development purposes. https://letsencrypt.org/docs/staging-environment/ {{% /def %}}

{{% def id="Subject" name="Subject" %}} A certificate field indicating what a certificate is about. This commonly contains fields like [Common Name](#def-CN), Country, and Organization. {{% /def %}}

This comment has been minimized.

Copy link
@tdelmas

tdelmas Jan 4, 2019

Author Contributor

"Subject" seams too generic for me, I think "Certificate subject" is better

Suggested change
{{% def id="Subject" name="Subject" %}} A certificate field indicating what a certificate is about. This commonly contains fields like [Common Name](#def-CN), Country, and Organization. {{% /def %}}
{{% def id="subject" name="Certificate subject" %}} A certificate field indicating what a certificate is about. This commonly contains fields like [Common Name](#def-CN), Country, and Organization. {{% /def %}}

This comment has been minimized.

Copy link
@jsha

jsha Jan 4, 2019

Contributor

Same comment as above.

Show resolved Hide resolved content/en/docs/glossary.md Outdated

{{% def id="Key-pair" name="Key-pair" %}} A combination of a private key and public key used to sign or encrypt. The public key is commonly embedded in a certificate, while the private key is stored on its own and should be kept secret. A key pair can be used to encrypt and decrypt, to sign and verify data, or to negotiate secondary keys, depending on the application. [Wikipedia](https://en.wikipedia.org/wiki/Public-key_cryptography) {{% /def %}}

{{% def id="leaf" name="Leaf certificate (end-entity certificate)" %}} Most commonly, a certificate signed by an [intermediate](#def-intermediate), valid for a set of domains and not able to sign other certificates. This is the type of certificate that [ACME clients](#def-ACME-client) request, and that [web servers](#def-web-server) use. [Wikipedia](https://en.wikipedia.org/wiki/Public_key_certificate#End-entity_or_leaf_certificate) {{% /def %}}

This comment has been minimized.

Copy link
@tdelmas

tdelmas Jan 4, 2019

Author Contributor

"end-entity certificate" is the correct term but "end-user certificate" seams commonly used too, maybe we can have both? (I'm not convinced it's better than only "end-entity", but...)

Suggested change
{{% def id="leaf" name="Leaf certificate (end-entity certificate)" %}} Most commonly, a certificate signed by an [intermediate](#def-intermediate), valid for a set of domains and not able to sign other certificates. This is the type of certificate that [ACME clients](#def-ACME-client) request, and that [web servers](#def-web-server) use. [Wikipedia](https://en.wikipedia.org/wiki/Public_key_certificate#End-entity_or_leaf_certificate) {{% /def %}}
{{% def id="leaf" name="Leaf certificate (end-entity/end-user certificate)" %}} Most commonly, a certificate signed by an [intermediate](#def-intermediate), valid for a set of domains and not able to sign other certificates. This is the type of certificate that [ACME clients](#def-ACME-client) request, and that [web servers](#def-web-server) use. [Wikipedia](https://en.wikipedia.org/wiki/Public_key_certificate#End-entity_or_leaf_certificate) {{% /def %}}

This comment has been minimized.

Copy link
@jsha

jsha Jan 4, 2019

Contributor

Interesting! I had never seen "end-user certificate" before. Do you have examples?

I'm not opposed to adding it, though the name field is now getting pretty long. Maybe we should make "Leaf certificate" the canonical name, and mention in the definition text that it has synonyms, and also create entries for those synonyms that direct to "leaf certificate?"

Show resolved Hide resolved content/en/docs/glossary.md Outdated
Show resolved Hide resolved content/en/docs/glossary.md Outdated
@tdelmas

This comment has been minimized.

Copy link
Contributor Author

commented Jan 4, 2019

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?

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?)
Can I update this PR in that direction?

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
Copy link
Contributor

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.

tdelmas added some commits Jan 5, 2019

@tdelmas

This comment has been minimized.

Copy link
Contributor Author

commented Jan 6, 2019

Hi @jsha, here are my changes: tdelmas/website@730d40e...3e83f4e

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
Examples:
https://ssl.comodo.com/articles/understanding-an-ssl-certificate-chain.php
https://support.dnsimple.com/articles/what-is-ssl-certificate-chain/

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)

@jsha

This comment has been minimized.

Copy link
Contributor

commented Jan 7, 2019

I've seen it a lot, for example a google search for the exact term "end-entity certificate"+"certificate authority" gives 9 200 results

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).

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)

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).

@tdelmas

This comment has been minimized.

Copy link
Contributor Author

commented Jan 7, 2019

I'd prefer to leave out "end-user certificate."

Done :-)

I noticed a small bug in the JS

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".

I'm doing what will probably be my last round of review before merging.

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.

@tdelmas tdelmas changed the title [WIP] Glossary: Fix #380 Glossary: Fix #380 Jan 7, 2019

@jsha

This comment has been minimized.

Copy link
Contributor

commented Jan 7, 2019

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".

I also can't reproduce this. Cool!

Merging now.

@jsha jsha merged commit ec84bdb into letsencrypt:master Jan 7, 2019

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details

@tdelmas tdelmas deleted the tdelmas:glossary branch Jan 7, 2019

@tdelmas tdelmas referenced this pull request Jan 8, 2019

Closed

Add a glossary #380

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.