Skip to content

Commit

Permalink
doc: guide towards x509.fingerprint256
Browse files Browse the repository at this point in the history
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>
  • Loading branch information
tniessen authored and targos committed Jul 11, 2022
1 parent 5984f1c commit 469da89
Showing 1 changed file with 15 additions and 0 deletions.
15 changes: 15 additions & 0 deletions doc/api/crypto.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -6013,6 +6027,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
Expand Down

0 comments on commit 469da89

Please sign in to comment.