# node-opcua-pki

[![NPM download](https://img.shields.io/npm/dm/node-opcua-pki.svg)](https://www.npmtrends.com/node-opcua-pki)
[![NPM version](https://img.shields.io/npm/v/node-opcua-pki)](https://www.npmjs.com/package/node-opcua-pki?activeTab=versions)
[![install size](https://packagephobia.com/badge?p=node-opcua-pki)](https://packagephobia.com/result?p=node-opcua-pki)

**PKI management for [node-opcua](https://node-opcua.github.io/)** — create and manage OPC UA certificates, Certificate Authorities, and Public Key Infrastructures.

## 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**       | 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](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)

## Support

NodeOPCUA PKI is developed and maintained by [sterfive.com](https://www.sterfive.com).

[![Professional Support](https://img.shields.io/static/v1?style=for-the-badge&label=Professional&message=Support&labelColor=blue&color=green&logo=data:image/svg%2bxml;base64, )](https://support.sterfive.com)

## License

MIT — Copyright (c) 2014-2026 Etienne Rossignon / [Sterfive](https://www.sterfive.com)
