Commit 868842f
doc: guide towards x509.fingerprint256
Recommend using x509.fingerprint256 instead of x509.fingerprint and
x509.fingerprint512 and suggest using it instead of x509.serialNumber
in order to uniquely identify certificates.
PR-URL: #42516
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Tierney Cyren <hello@bnb.im>1 parent 2c70f14 commit 868842f
1 file changed
Lines changed: 15 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -2621,6 +2621,10 @@ added: v15.6.0 | |||
| 2621 | 2621 | ||
| 2622 | 2622 | The SHA-1 fingerprint of this certificate. | |
| 2623 | 2623 | ||
| 2624 | + Because SHA-1 is cryptographically broken and because the security of SHA-1 is | ||
| 2625 | + significantly worse than that of algorithms that are commonly used to sign | ||
| 2626 | + certificates, consider using [`x509.fingerprint256`][] instead. | ||
| 2627 | + | ||
| 2624 | 2628 | ### `x509.fingerprint256` | |
| 2625 | 2629 | ||
| 2626 | 2630 | <!-- YAML | |
@@ -2641,6 +2645,12 @@ added: v16.14.0 | |||
| 2641 | 2645 | ||
| 2642 | 2646 | The SHA-512 fingerprint of this certificate. | |
| 2643 | 2647 | ||
| 2648 | + Because computing the SHA-256 fingerprint is usually faster and because it is | ||
| 2649 | + only half the size of the SHA-512 fingerprint, [`x509.fingerprint256`][] may be | ||
| 2650 | + a better choice. While SHA-512 presumably provides a higher level of security in | ||
| 2651 | + general, the security of SHA-256 matches that of most algorithms that are | ||
| 2652 | + commonly used to sign certificates. | ||
| 2653 | + | ||
| 2644 | 2654 | ### `x509.infoAccess` | |
| 2645 | 2655 | ||
| 2646 | 2656 | <!-- YAML | |
@@ -2728,6 +2738,10 @@ added: v15.6.0 | |||
| 2728 | 2738 | ||
| 2729 | 2739 | The serial number of this certificate. | |
| 2730 | 2740 | ||
| 2741 | + Serial numbers are assigned by certificate authorities and do not uniquely | ||
| 2742 | + identify certificates. Consider using [`x509.fingerprint256`][] as a unique | ||
| 2743 | + identifier instead. | ||
| 2744 | + | ||
| 2731 | 2745 | ### `x509.subject` | |
| 2732 | 2746 | ||
| 2733 | 2747 | <!-- YAML | |
@@ -6029,6 +6043,7 @@ See the [list of SSL OP Flags][] for details. | |||
| 6029 | 6043 | [`util.promisify()`]: util.md#utilpromisifyoriginal | |
| 6030 | 6044 | [`verify.update()`]: #verifyupdatedata-inputencoding | |
| 6031 | 6045 | [`verify.verify()`]: #verifyverifyobject-signature-signatureencoding | |
| 6046 | + [`x509.fingerprint256`]: #x509fingerprint256 | ||
| 6032 | 6047 | [caveats when using strings as inputs to cryptographic APIs]: #using-strings-as-inputs-to-cryptographic-apis | |
| 6033 | 6048 | [certificate object]: tls.md#certificate-object | |
| 6034 | 6049 | [encoding]: buffer.md#buffers-and-character-encodings | |
0 commit comments