Commit b819af6
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 f2355e4 commit b819af6
1 file changed
Lines changed: 15 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -2617,6 +2617,10 @@ added: v15.6.0 | |||
| 2617 | 2617 | ||
| 2618 | 2618 | The SHA-1 fingerprint of this certificate. | |
| 2619 | 2619 | ||
| 2620 | + Because SHA-1 is cryptographically broken and because the security of SHA-1 is | ||
| 2621 | + significantly worse than that of algorithms that are commonly used to sign | ||
| 2622 | + certificates, consider using [`x509.fingerprint256`][] instead. | ||
| 2623 | + | ||
| 2620 | 2624 | ### `x509.fingerprint256` | |
| 2621 | 2625 | ||
| 2622 | 2626 | <!-- YAML | |
@@ -2637,6 +2641,12 @@ added: v17.2.0 | |||
| 2637 | 2641 | ||
| 2638 | 2642 | The SHA-512 fingerprint of this certificate. | |
| 2639 | 2643 | ||
| 2644 | + Because computing the SHA-256 fingerprint is usually faster and because it is | ||
| 2645 | + only half the size of the SHA-512 fingerprint, [`x509.fingerprint256`][] may be | ||
| 2646 | + a better choice. While SHA-512 presumably provides a higher level of security in | ||
| 2647 | + general, the security of SHA-256 matches that of most algorithms that are | ||
| 2648 | + commonly used to sign certificates. | ||
| 2649 | + | ||
| 2640 | 2650 | ### `x509.infoAccess` | |
| 2641 | 2651 | ||
| 2642 | 2652 | <!-- YAML | |
@@ -2724,6 +2734,10 @@ added: v15.6.0 | |||
| 2724 | 2734 | ||
| 2725 | 2735 | The serial number of this certificate. | |
| 2726 | 2736 | ||
| 2737 | + Serial numbers are assigned by certificate authorities and do not uniquely | ||
| 2738 | + identify certificates. Consider using [`x509.fingerprint256`][] as a unique | ||
| 2739 | + identifier instead. | ||
| 2740 | + | ||
| 2727 | 2741 | ### `x509.subject` | |
| 2728 | 2742 | ||
| 2729 | 2743 | <!-- YAML | |
@@ -6056,6 +6070,7 @@ See the [list of SSL OP Flags][] for details. | |||
| 6056 | 6070 | [`util.promisify()`]: util.md#utilpromisifyoriginal | |
| 6057 | 6071 | [`verify.update()`]: #verifyupdatedata-inputencoding | |
| 6058 | 6072 | [`verify.verify()`]: #verifyverifyobject-signature-signatureencoding | |
| 6073 | + [`x509.fingerprint256`]: #x509fingerprint256 | ||
| 6059 | 6074 | [caveats when using strings as inputs to cryptographic APIs]: #using-strings-as-inputs-to-cryptographic-apis | |
| 6060 | 6075 | [certificate object]: tls.md#certificate-object | |
| 6061 | 6076 | [encoding]: buffer.md#buffers-and-character-encodings | |
0 commit comments