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: info@timokoessler.de

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 2025
Released under the MIT license

Changelog

All notable changes to this project will be documented in this file.

[1.2.2] - 2025-04

Changed

• Update dependencies
• Update Security Policy

[1.2.1] - 2025-02

Changed

• Update dependencies
• Use Node.js 22 in CI
• Migrate tests from Jest to Node.js Test Runner

[1.2.0] - 2024-08

Breaking changes

• The function getCertURLs is no longer async ❗ (was async with no need)

Added

• Export downloadIssuerCert function for usage outside of the module

Changed

• Use biome for linting and formatting instead of eslint and prettier
• Improve code quality and test coverage
• Update dependencies and GitHub Actions

[1.1.0] - 2024-05

Added

• Add getRawOCSPResponse function to get only the bytes of the OCSP response
• New option rawResponse to get the raw OCSP response additionally to the parsed response

Changed

• Update dependencies

[1.0.1] - 2024-01

Changed

• Fix CommonJS import
• Update dependencies

[1.0.0] - 2024-01

Added

• Automatically convert url to domain in getCertStatusByDomain
• Add examples

Changed

• Throw error if the certificate is already expired
• Update dependencies

[0.3.0] - 2023-12

Added

• Return the revocation reason when the certificate is revoked, if available
• Check licenses of dependencies

Changed

• Add VSCode recommended extensions
• Fix failing tests because of expired certificate
• Update dependencies

[0.2.0] - 2023-10

Added

• Publish package via GitHub Actions

Changed

• Fixed downloading issuer cert when the data is pem encoded

[0.1.0] - 2023-09

This is the initial release.