doc: improve Web Crypto headings related to ECC #41542
Conversation
tniessen
commented
Jan 15, 2022
tniessen
commented
- The heading "Elliptic curve key pairs" is much less specific than the code in the section with that title is. ECDSA is just one algorithm that uses elliptic curves. Unlike other crypto standards, Web Crypto does not represent ECC keys independent of the associated algorithm.
- ED25519/ED448/X25519/X448 are not curves (the curve names are Curve25519 and Curve448), so remove the words "Elliptic curves" to avoid confusion. Again, these are specific algorithms.
nodejs-github-bot
added
the
crypto
| @@ -48,7 +48,7 @@ async function generateAesKey(length = 256) { | |||
| } | |||
| ``` | |||
|
|
|||
| #### Elliptic curve key pairs | |||
| #### ECDSA key pairs | |||
There was a problem hiding this comment.
I would prefer if the whole acronym was mentioned here. IIRC that's "Elliptic Curve Digital Signature Algorithm" but I am not sure.
There was a problem hiding this comment.
We could maybe use Elliptic Curve Digital Signature Algorithm (ECDSA), but it would make the heading very long and we also don't spell out slightly more commonly used acronyms (AES, RSA, HMAC, ...). Maybe we should add a sentence or two under each heading in a follow-up PR, explaining what algorithms the acronyms are referring to?
There was a problem hiding this comment.
Yeah or even just links to Wikipedia
| @@ -66,7 +66,7 @@ async function generateEcKey(namedCurve = 'P-521') { | |||
| } | |||
| ``` | |||
|
|
|||
| #### ED25519/ED448/X25519/X448 Elliptic curve key pairs | |||
| #### ED25519/ED448/X25519/X448 key pairs | |||
There was a problem hiding this comment.
I'm wondering if it would make sense to elaborate here but honestly if you don't know what ES25519 is before reading these docs it probably won't help and if you did it won't help either..
|
Landed in d0d8320, thanks for reviewing. |
PR-URL: #41542 Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Filip Skokan <panva.ip@gmail.com>
PR-URL: nodejs#41542 Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Filip Skokan <panva.ip@gmail.com>
PR-URL: #41542 Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Filip Skokan <panva.ip@gmail.com>
PR-URL: nodejs#41542 Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Filip Skokan <panva.ip@gmail.com>
PR-URL: #41542 Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Filip Skokan <panva.ip@gmail.com>
