node-opcua-pki

PKI management for node-opcua — create and manage OPC UA certificates, Certificate Authorities, and Public Key Infrastructures.

Quick Start

# Use directly with npx (no install needed)
npx node-opcua-pki --help
npx node-opcua-pki createPKI
npx node-opcua-pki certificate --selfSigned -o my_cert.pem

# Or install globally
npm install -g node-opcua-pki
pki --help

Prerequisites

This module requires OpenSSL or LibreSSL:

| Platform | Installation | | ----------------- | ------------------------------------- | | Windows | Automatically downloaded at first run | | Ubuntu/Debian | apt install openssl | | Alpine | apk add openssl | | macOS | Pre-installed (LibreSSL) |

CLI Commands

| Command | Description | | -------------------- | ------------------------------------------------ | | demo | Create default certificates for node-opcua demos | | createCA | Create a Certificate Authority | | createPKI | Create a Public Key Infrastructure | | certificate | Create a new certificate | | revoke <file> | Revoke an existing certificate | | csr | Create a certificate signing request (CSR) | | sign | Sign a CSR and generate a certificate | | dump <file> | Display a certificate | | toder <file> | Convert a certificate to DER format | | fingerprint <file> | Print the certificate fingerprint | | version | Display the version number |

See also: OPC Foundation GDS spec

createPKI

Create a Public Key Infrastructure directory structure.

pki createPKI [options]

| Option | Description | Default | | --------------- | ------------------------------------------------- | -------------------- | | -r, --root | Certificate folder location | {CWD}/certificates | | --PKIFolder | PKI folder location | {root}/PKI | | -k, --keySize | Private key size in bits (1024|2048|3072|4096) | 2048 | | -s, --silent | Minimize output | false |

Generated structure:

📂 certificates/PKI
├── 📂 issuers
│   ├── 📂 certs       CA certificates
│   └── 📂 crl         Certificate Revocation Lists
├── 📂 own
│   ├── 📂 certs       Generated public certificates
│   └── 📂 private
│       └── 🔐 private_key.pem
├── 📂 rejected        Rejected certificates
└── 📂 trusted
    ├── 📂 certs       Trusted X.509 v3 certificates
    └── 📂 crl         CRLs for trusted certificates

createCA

Create a Certificate Authority.

pki createCA [options]

| Option | Description | Default | | ---------------- | --------------------------- | ------------------------------------------------------------------------------- | | --subject | CA certificate subject | /C=FR/ST=IDF/L=Paris/O=Local NODE-OPCUA Certificate Authority/CN=NodeOPCUA-CA | | -r, --root | Certificate folder location | {CWD}/certificates | | -c, --CAFolder | CA folder location | {root}/CA | | -k, --keySize | Private key size in bits | 2048 |

certificate

Create a new certificate (CA-signed or self-signed).

pki certificate [options]

| Option | Description | Default | | ---------------------- | ------------------------------------ | ---------------------------------- | | -a, --applicationUri | Application URI | urn:{hostname}:Node-OPCUA-Server | | -o, --output | Output certificate filename | my_certificate.pem | | --selfSigned | Create self-signed certificate | false | | -v, --validity | Validity in days | 365 | | --dns | Valid domain names (comma separated) | {hostname} | | --ip | Valid IPs (comma separated) | | | --subject | Certificate subject | | | -r, --root | Certificate folder location | {CWD}/certificates | | -c, --CAFolder | CA folder location | {root}/CA | | --PKIFolder | PKI folder location | {root}/PKI | | -p, --privateKey | Private key to use | {PKIFolder}/own/private_key.pem |

Example — self-signed certificate with SANs:

pki certificate \
  --selfSigned \
  --dns=machine1.com,machine2.com \
  --ip="192.1.2.3;192.3.4.5" \
  -a "urn:{hostname}:My-OPCUA-Server" \
  -o my_self_signed_certificate.pem

csr

Create a certificate signing request.

pki csr [options]

| Option | Description | Default | | ---------------------- | ------------------------------------ | ------------------------------------ | | -a, --applicationUri | Application URI | urn:{hostname}:Node-OPCUA-Server | | -o, --output | Output CSR filename | my_certificate_signing_request.csr | | --dns | Valid domain names (comma separated) | {hostname} | | --ip | Valid IPs (comma separated) | | | --subject | Certificate subject | /CN=Certificate |

sign

Sign a CSR and generate a certificate (requires a CA).

pki sign [options]

| Option | Description | Default | | ---------------- | --------------------------- | ------------------------------------ | | -i, --csr | CSR file to sign | my_certificate_signing_request.csr | | -o, --output | Output certificate filename | my_certificate.pem | | -v, --validity | Validity in days | 365 | | -r, --root | Certificate folder location | {CWD}/certificates | | -c, --CAFolder | CA folder location | {root}/CA |

demo

Create a set of demo certificates for testing.

pki demo [--dev] [--silent] [--clean]

| Option | Description | | --------- | --------------------------------------------------------- | | --dev | Create additional certificates for dev testing | | --clean | Purge existing certificate directory (use with care!) |

Programmatic Usage

import { CertificateManager } from "node-opcua-pki";

const cm = new CertificateManager({
    location: "./my_pki",
    keySize: 2048,
});

await cm.initialize();

// Create a self-signed certificate
await cm.createSelfSignedCertificate({
    applicationUri: "urn:my-server:application",
    subject: "/CN=My Server/O=My Organization",
    dns: ["localhost"],
    startDate: new Date(),
    validity: 365,
});

CertificateManager API

Certificate Trust

| Method | Description | | ----------------------------------------------- | ------------------------------------------------------------------------------------------ | | trustCertificate(cert) | Add a certificate to the trusted store | | rejectCertificate(cert) | Move a certificate to the rejected store | | getCertificateStatus(cert) | Returns "trusted", "rejected", or "unknown" | | removeTrustedCertificate(thumbprint) | Remove a trusted certificate by SHA-1 thumbprint. Returns the certificate buffer or null | | addTrustedCertificateFromChain(certChain) | Validate and trust the leaf certificate from a DER chain | | isIssuerInUseByTrustedCertificate(issuerCert) | Check if any trusted cert was signed by this issuer | | verifyCertificate(cert, options?) | Full certificate chain validation | | reloadCertificates() | Force a full re-scan of all PKI folders |

Issuer (CA) Certificates

| Method | Description | | --------------------------------------------- | ------------------------------------------------------------------------ | | addIssuer(cert, validate?, addInTrustList?) | Add a CA certificate to the issuers store | | hasIssuer(thumbprint) | Check if an issuer exists by SHA-1 thumbprint | | removeIssuer(thumbprint) | Remove an issuer by thumbprint. Returns the certificate buffer or null | | findIssuerCertificate(cert) | Find the issuer certificate for a given certificate |

Certificate Revocation Lists (CRLs)

| Method | Description | | ----------------------------------------------- | --------------------------------------------------------------------------------------------- | | addRevocationList(crl, target?) | Add a CRL. target is "issuers" (default) or "trusted" | | clearRevocationLists(target) | Remove all CRLs from "issuers", "trusted", or "all" | | removeRevocationListsForIssuer(cert, target?) | Remove CRLs issued by a specific CA. target: "issuers", "trusted", or "all" (default) | | isCertificateRevoked(cert, issuerCert?) | Check if a certificate has been revoked |

Folder Accessors

| Getter | Path | | ------------------- | -------------------------- | | trustedFolder | {location}/trusted/certs | | rejectedFolder | {location}/rejected | | crlFolder | {location}/trusted/crl | | issuersCertFolder | {location}/issuers/certs | | issuersCrlFolder | {location}/issuers/crl | | rootDir | {location} |

File Watching

CertificateManager uses chokidar to watch the PKI folders for changes. By default, it uses native OS events (inotify, FSEvents, ReadDirectoryChangesW) for near-real-time detection.

If the PKI folders are on a network file system (NFS, CIFS) or inside a Docker volume where native events don't propagate, set the environment variable:

OPCUA_PKI_USE_POLLING=true

This falls back to filesystem polling, which is slower but works on all file systems.

Note: If external processes modify the PKI folders directly (e.g., CLI tools, OPC UA WriteTrustList), call reloadCertificates() to force an immediate re-scan of the folder state.

References

• OPC Foundation GDS File Store
• RFC 5280 — X.509 PKI Certificate and CRL Profile
• Certification Path Validation

Support

NodeOPCUA PKI is developed and maintained by sterfive.com.

License

MIT — Copyright (c) 2014-2026 Etienne Rossignon / Sterfive