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.
import { X509Certificate } from 'node:crypto'; const cert = new X509Certificate(pemOrDerBuffer); console.log(cert.subject, cert.validTo);
Try it
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.
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
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.
validFromandvalidToare strings in theOct 7 07:21:12 2126 GMTstyle. UsevalidToDatefor arithmetic, such as warning thirty days before expiry. checkHost()returns the match, not a boolean. Test the result with!== undefined.- Fingerprint pinning. Compare
fingerprint256of the leaf with a stored value to pin a certificate, ideally in constant time. - Reading from a TLS socket.
socket.getPeerX509Certificate()returns anX509Certificatefor the other side of a connection. - PEM or DER. Strings must be PEM;
Bufferinput may be either. - Added in Node.js 15.6.0.