node-opcua-pki
Version:
PKI management for node-opcua
271 lines (203 loc) • 12.9 kB
Markdown
# node-opcua-pki
[](https://www.npmtrends.com/node-opcua-pki)
[](https://www.npmjs.com/package/node-opcua-pki?activeTab=versions)
[](https://packagephobia.com/result?p=node-opcua-pki)
**Production-grade PKI management for [OPC UA](https://node-opcua.github.io/)** — secure your industrial devices with proper certificates in minutes, not days.
## Why node-opcua-pki?
- 🔒 **OPC UA compliant** — PKI directory structure per Part 6 §6.2.6, out of the box
- 🏗️ **Full CA lifecycle** — create, sign, revoke, renew certificates and CRLs
- 🖥️ **Cross-platform** — Windows, Linux, macOS, Alpine, with automatic OpenSSL detection
- 🧩 **CLI + API** — use from the command line or embed in your Node.js application
- 🛡️ **Battle-tested** — 12 years of continuous development, powering production OPC UA deployments worldwide
## Quick Start
```bash
# 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** | Auto-detected from system PATH, or downloaded on first run |
| **Ubuntu/Debian** | `apt install openssl` |
| **Alpine** | `apk add openssl` |
| **macOS** | Pre-installed (LibreSSL) |
## 🏢 Professional Support
node-opcua-pki is developed and maintained by [Sterfive](https://www.sterfive.com), the company behind the [node-opcua](https://github.com/node-opcua/node-opcua) ecosystem.
| | Community | Professional |
|---|:---:|:---:|
| Full documentation & CLI | ✅ | ✅ |
| Bug fixes & security patches | Best effort | **Priority SLA** |
| Security advisories | Public | **Early access** |
| Custom certificate workflows | — | ✅ |
| Dedicated consulting | — | ✅ |
| PKI architecture review | — | ✅ |
[](https://support.sterfive.com)
Or [contact Sterfive](mailto:contact@sterfive.com) for dedicated consulting and enterprise needs.
---
## 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](https://reference.opcfoundation.org/GDS/docs/F.1/)
---
### createPKI
Create a Public Key Infrastructure directory structure.
```bash
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.
```bash
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).
```bash
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:**
```bash
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.
```bash
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).
```bash
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.
```bash
pki demo [--dev] [--silent] [--clean]
```
| Option | Description |
| --------- | --------------------------------------------------------- |
| `--dev` | Create additional certificates for dev testing |
| `--clean` | Purge existing certificate directory (**use with care!**) |
---
## Programmatic Usage
```typescript
import { CertificateManager, CertificateAuthority } from "node-opcua-pki";
```
### [CertificateManager](./docs/certificate-manager.md)
Manages an OPC UA–compliant PKI directory with trust stores, issuer
stores, file watching, and certificate lifecycle.
```typescript
const cm = new CertificateManager({ location: "./my_pki" });
await cm.initialize();
```
### [CertificateAuthority](./docs/certificate-authority.md)
OpenSSL-based CA for issuing, revoking, and tracking certificates.
Supports root CAs, intermediate CAs with manual 3-step workflow,
proactive certificate renewal, and full chain output per OPC UA
Part 6 §6.2.6.
```typescript
// Root CA
const rootCA = new CertificateAuthority({
keySize: 2048,
location: "./my_root_ca",
subject: "/CN=My Root CA",
});
await rootCA.initialize();
// Intermediate CA (3-step workflow)
const intCA = new CertificateAuthority({
keySize: 2048,
location: "./my_intermediate_ca",
subject: "/CN=My Intermediate CA",
});
const result = await intCA.initializeCSR(); // Step 1
await rootCA.signCACertificateRequest( // Step 2
certFile, result.csrPath, { validity: 3650 }
);
await intCA.installCACertificate(certFile); // Step 3
```
## References
- [OPC Foundation GDS File Store](https://reference.opcfoundation.org/GDS/docs/F.1/)
- [RFC 5280 — X.509 PKI Certificate and CRL Profile](https://tools.ietf.org/html/rfc5280)
- [Certification Path Validation](https://en.wikipedia.org/wiki/Certification_path_validation_algorithm)
## License
MIT — Copyright (c) 2014-2026 Etienne Rossignon / [Sterfive](https://www.sterfive.com)