Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท crypto

Node.js X509Certificate class

Reference for the X509Certificate class in Node.js: parsing PEM certificates, reading subject, issuer, validity and fingerprints, and checking hosts and signatures.

crypto.X509Certificate parses an X.509 certificate, the format used by TLS, code signing and many other systems, and exposes its fields as properties. You can read the subject and issuer, the validity period, the serial number and fingerprints, the subject alternative names, and the certificate's public key. It can also check whether a certificate matches a host name, whether it was signed by a given key, and whether it issued another certificate.

It does not build or validate whole certificate chains and it does not create certificates. For connections, the tls module does chain validation; X509Certificate is for inspection and targeted checks, such as showing an expiry date or comparing a pinned fingerprint.

NODE
import { X509Certificate } from 'node:crypto';

const cert = new X509Certificate(pemOrDerBuffer);
console.log(cert.subject, cert.validTo);

Try it

Node.js Read a certificate

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Host, signature and issuer checks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
new crypto.X509Certificate(buffer: string | Buffer | TypedArray | DataView)

Selected properties, all read-only:

Property Description
subject, issuer Distinguished names as text with one attribute per line.
subjectAltName The subject alternative names as a comma-separated string, or undefined.
serialNumber Serial number as an uppercase hex string.
validFrom, validTo Validity period as text; validFromDate and validToDate give Date objects.
fingerprint, fingerprint256, fingerprint512 SHA-1, SHA-256 and SHA-512 digests of the DER form, as colon-separated hex.
ca true if the certificate is a certificate authority.
publicKey A public KeyObject.
raw The DER encoding as a Buffer.
keyUsage Array of extended key usage object identifiers.
infoAccess The authority information access extension text.
Method Description
checkHost(name, options?) Returns the matching subject name, or undefined.
checkEmail(email), checkIP(ip) Like checkHost for email addresses and IP addresses.
checkIssued(otherCert) true if otherCert names this certificate's subject as issuer and its key usage allows it.
checkPrivateKey(privateKey) true if the private key matches the certificate.
verify(publicKey) true if the certificate was signed by the key.
toString(), toJSON() The PEM text.
toLegacyObject() The legacy object format used by tls.

Errors: the constructor throws an OpenSSL error for input that is not a certificate (ERR_OSSL_PEM_NO_START_LINE for the text in the example) and ERR_INVALID_ARG_TYPE for wrong argument types.

Usage notes

  • No chain validation. verify() only checks one signature. A certificate that verifies against some key is not thereby trusted; trust comes from a chain to a trusted root.
  • Dates are text. validFrom and validTo are strings in the Oct 7 07:21:12 2126 GMT style. Use validToDate for arithmetic, such as warning thirty days before expiry.
  • checkHost() returns the match, not a boolean. Test the result with !== undefined.
  • Fingerprint pinning. Compare fingerprint256 of the leaf with a stored value to pin a certificate, ideally in constant time.
  • Reading from a TLS socket. socket.getPeerX509Certificate() returns an X509Certificate for the other side of a connection.
  • PEM or DER. Strings must be PEM; Buffer input may be either.
  • Added in Node.js 15.6.0.