EasyOCSP

EasyOCSP is an easy-to-use OCSP client for Node.js that can be used to check the revocation status of X.509 TLS certificates using the Online Certificate Status Protocol (OCSP). It's based on PKI.js but provides a much simpler API and additional features like OCSP nonce verification (RFC 8954).

A complete documentation can be found at ocsp.tkoessler.de.

Getting started

You can install EasyOCSP using npm:

npm install easy-ocsp

The following example shows how to use EasyOCSP to check the revocation status of a certificate:

import { getCertStatus } from 'easy-ocsp';

try {
    const ocspResult = await getCertStatus(/* PEM string, DER Buffer, X509Certificate */);

    if (ocspResult.status === 'revoked') {
        // Certificate is revoked
    } else if (ocspResult.status === 'good') {
        // Certificate is valid
    } else {
        // Certificate status is unknown
    }
} catch (e) {
    // Handle errors ...
}

Get cert status by domain

EasyOCSP also provides a function to check the revocation status of a certificate by domain. This function will automatically download the certificate from the given domain and check its revocation status:

import { getCertStatusByDomain } from 'easy-ocsp';

try {
    const ocspResult = await getCertStatusByDomain('example.com');
    // ...
} catch (e) {
    // Handle errors ...
}

Advanced usage

Get cert urls

You can use the getCertUrls function to get the URLs of the OCSP responder and the issuer certificate of a certificate. This is extracted from the certificate's authorityInfoAccess extension:

import { getCertUrls } from 'easy-ocsp';

try {
    const { ocspUrl, issuerUrl } = getCertUrls(/* PEM string, DER Buffer, X509Certificate */);
    // ...
} catch (e) {
    // Handle errors ...
}

Download cert

You can use the downloadCert function to download the certificate of a domain. This function will return the certificate as a DER buffer:

import { downloadCert } from 'easy-ocsp';

try {
    const cert = await downloadCert('example.com');
    // ...
} catch (e) {
    // Handle errors ...
}

Get raw OCSP response

You can use the getRawOCSPResponse function to get the OCSP response bytes. This function will return the OCSP response and the nonce as a buffer and the issuer certificate as pem string. The response is not parsed or validated.

import { getRawOCSPResponse } from 'easy-ocsp';

try {
    const { rawResponse, nonce, issuerCert } = await getRawOCSPResponse(/* PEM string, DER Buffer, X509Certificate */);
    // ...
} catch (e) {
    // Handle errors ...
}

Advanced options

You can pass an options object to the getCertStatus and getCertStatusByDomain functions to configure the OCSP request. You can find a complete list of all options in the documentation.

Contact

If a public GitHub issue or discussion is not the right choice for your concern, you can contact me directly:

• E-Mail: [email protected]

Sources

• RFC 6960: X.509 Internet Public Key Infrastructure Online Certificate Status Protocol - OCSP
• RFC 8954: Online Certificate Status Protocol (OCSP) Nonce Extension
• pkijs Docs

License

© Timo Kössler 2024
Released under the MIT license