From 868842fe150b5d8cb3c7e05c14deb3b0509cc375 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tobias=20Nie=C3=9Fen?= <tniessen@tnie.de>
Date: Fri, 1 Apr 2022 12:35:27 +0200
Subject: [PATCH] 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: https://github.com/nodejs/node/pull/42516
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Tierney Cyren <hello@bnb.im>
---
 doc/api/crypto.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 9aa0829ac70bc6..ad762efb50fef8 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -2621,6 +2621,10 @@ added: v15.6.0
 
 The SHA-1 fingerprint of this certificate.
 
+Because SHA-1 is cryptographically broken and because the security of SHA-1 is
+significantly worse than that of algorithms that are commonly used to sign
+certificates, consider using [`x509.fingerprint256`][] instead.
+
 ### `x509.fingerprint256`
 
 <!-- YAML
@@ -2641,6 +2645,12 @@ added: v16.14.0
 
 The SHA-512 fingerprint of this certificate.
 
+Because computing the SHA-256 fingerprint is usually faster and because it is
+only half the size of the SHA-512 fingerprint, [`x509.fingerprint256`][] may be
+a better choice. While SHA-512 presumably provides a higher level of security in
+general, the security of SHA-256 matches that of most algorithms that are
+commonly used to sign certificates.
+
 ### `x509.infoAccess`
 
 <!-- YAML
@@ -2728,6 +2738,10 @@ added: v15.6.0
 
 The serial number of this certificate.
 
+Serial numbers are assigned by certificate authorities and do not uniquely
+identify certificates. Consider using [`x509.fingerprint256`][] as a unique
+identifier instead.
+
 ### `x509.subject`
 
 <!-- YAML
@@ -6029,6 +6043,7 @@ See the [list of SSL OP Flags][] for details.
 [`util.promisify()`]: util.md#utilpromisifyoriginal
 [`verify.update()`]: #verifyupdatedata-inputencoding
 [`verify.verify()`]: #verifyverifyobject-signature-signatureencoding
+[`x509.fingerprint256`]: #x509fingerprint256
 [caveats when using strings as inputs to cryptographic APIs]: #using-strings-as-inputs-to-cryptographic-apis
 [certificate object]: tls.md#certificate-object
 [encoding]: buffer.md#buffers-and-character-encodings