Registry / auth-security / node-opcua-pki

node-opcua-pki

JSON →
library6.13.0jsnpmunverified

node-opcua-pki is a comprehensive library for managing Public Key Infrastructures (PKI), Certificate Authorities (CA), and OPC UA certificates, offering both a powerful command-line interface (CLI) and a programmatic API. Designed specifically for the node-opcua ecosystem, it provides full lifecycle management for certificates, including support for intermediate CAs, OpenSSL 3.5.x compatibility, and a robust PFX (PKCS#12) toolbox. The current stable version is 6.13.0, with frequent minor and patch releases demonstrating active maintenance and continuous feature development. Key differentiators include its deep integration with OPC UA standards, a rich set of CLI commands for common PKI operations, and specialized features like an in-memory DER/PEM buffer API for `CertificateAuthority` operations and a certificate database for querying issued certificates. It serves as a critical component for securing OPC UA applications.

npm install node-opcua-pki
INSTALL
IMPORT
SIG · NODE-OPCUA-PKI
N
node-opcua-pki
auth-securityjavascriptv6.13.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

CertificateManager
import { CertificateManager } from 'node-opcua-pki';
const CertificateManager = require('node-opcua-pki').CertificateManager;
While CommonJS `require` is supported by dual-format bundles, ESM `import` is the recommended and preferred pattern for modern Node.js and TypeScript usage since v6.0.0+.
CertificateAuthority
import { CertificateAuthority } from 'node-opcua-pki';
import { CertificateAuthority } from 'node-opcua-pki/dist/pki/certificate_authority';
Import `CertificateAuthority` directly from the main package entry point. Avoid importing from internal `dist` paths, as these are subject to change.
initializeCSR
import { initializeCSR } from 'node-opcua-pki';
import { initializeCSR } from 'node-opcua-pki/lib/pki/certificate_authority';
`initializeCSR` is part of the public API for Subordinate CA support since v6.11.0. Ensure you import it from the root of the package.

This quickstart demonstrates how to use the `node-opcua-pki` CLI to initialize a Public Key Infrastructure and generate a self-signed OPC UA application certificate for development or testing. It includes verification steps.

#!/bin/bash # This script demonstrates how to set up a basic PKI structure and generate a self-signed certificate. # Prerequisites: Node.js (with npx) and OpenSSL (or LibreSSL) installed on your system. # For Debian/Ubuntu, install OpenSSL: `sudo apt install openssl` # Define a root directory for our PKI (relative path). PKI_ROOT="./my_opcua_pki_example" echo "\n--- 1. Creating a new OPC UA PKI directory structure in ${PKI_ROOT} ---" npx node-opcua-pki createPKI \ --root "${PKI_ROOT}" \ --keySize 2048 \ --silent # Check if the PKI root directory was created if [ ! -d "${PKI_ROOT}" ]; then echo "Error: PKI root directory '${PKI_ROOT}' was not created. Exiting." >&2 exit 1 fi echo "\n--- 2. Creating a self-signed OPC UA Application Certificate ---" npx node-opcua-pki certificate \ --root "${PKI_ROOT}" \ --selfSigned \ --applicationUri "urn:my-opcua-server:application" \ --subject "/C=US/ST=CA/L=SF/O=MyCompany/CN=MyOPCUAServer" \ -o "${PKI_ROOT}/own/certs/server_certificate.pem" \ --dns "localhost" \ --ip "127.0.0.1" \ --validity 365 # Valid for 1 year # Check if the certificate was created if [ ! -f "${PKI_ROOT}/own/certs/server_certificate.pem" ]; then echo "Error: Server certificate was not created. Exiting." >&2 exit 1 fi echo "\n--- 3. Dumping the created certificate information for verification ---" npx node-opcua-pki dump "${PKI_ROOT}/own/certs/server_certificate.pem" echo "\nPKI setup and self-signed certificate generation complete in '${PKI_ROOT}'."
node-opcua-pki --version
Debug
Known issues
breakingThe public API was sanitized in v6.5.0, removing previously exported internal helpers like `pki_main`, `g_config`, `mkdirRecursiveSync`, and others. Code directly referencing these internal symbols will break.
fix
Review the v6.5.0 release notes and the current API documentation. Update your code to use the officially exported API for PKI management. For example, use `CertificateManager` and `CertificateAuthority` classes.
affects: >=6.5.0
breakingVersion 6.0.0 introduced a significant architectural overhaul, refactoring the project into a monorepo and modernizing the build toolchain. While the public API was intended to remain stable, underlying changes might affect complex build setups or reliance on specific internal package structures. This release also resolved all known security vulnerabilities.
fix
Upgrade to v6.0.0+ to benefit from security fixes and modern architecture. Review your build configurations and ensure compatibility with the new monorepo structure. Re-test integrations if relying on non-public APIs or file paths.
affects: >=6.0.0
gotchaThis module relies on a system installation of OpenSSL (or LibreSSL) for its cryptographic operations. If OpenSSL is not installed or not accessible in the system's PATH, CLI commands and programmatic functions will fail with 'command not found' or similar errors.
fix
Ensure OpenSSL is installed on your operating system. For Ubuntu/Debian, use `sudo apt install openssl`. On Windows, it's typically auto-downloaded on first run, but manual installation might be required in some environments. macOS usually has LibreSSL pre-installed.
affects: >=1.0.0
gotchaAs of v6.11.0, the package provides robust support for Subordinate (Intermediate) CAs. Improperly handling certificate chains or relying on older, simplified CA workflows might lead to validation issues or incomplete certificate outputs.
fix
Familiarize yourself with the new 3-step workflow for intermediate CAs, including `initializeCSR()`, `installCACertificate()`, and `signCACertificateRequest()` as detailed in the release notes. Ensure full certificate chain output is correctly managed.
affects: >=6.11.0
Errors
Common errors & fixes
Error: Command failed: openssl req -new -key ...
OpenSSL executable is not found in the system's PATH, or there's an issue with the OpenSSL installation itself (e.g., missing dependencies).
fix
Verify that OpenSSL is correctly installed and its executable is accessible from your system's PATH. On Linux, try `openssl version` to check its availability. Install it if missing (e.g., `sudo apt install openssl`). For Windows, ensure automatic download was successful or install manually.
TypeError: CertificateManager is not a constructor
Attempting to `require()` or import the `CertificateManager` class incorrectly in a CommonJS or ESM context, or an incorrect path is used, leading to an undefined or malformed export.
fix
For CommonJS, use `const { CertificateManager } = require('node-opcua-pki');`. For ESM (recommended for modern Node.js and TypeScript), use `import { CertificateManager } from 'node-opcua-pki';`. Ensure your project's `package.json` `type` field is set correctly if mixing module systems.
Error: unable to find 'index.txt' in Certificate Authority folder
The Certificate Authority (CA) folder structure is incomplete or corrupted, missing the OpenSSL `index.txt` file which acts as the certificate database. This often happens if `createCA` was not run or failed.
fix
Ensure you have correctly initialized your Certificate Authority using `npx node-opcua-pki createCA --root <your_pki_root_folder>`. If the directory exists but is corrupt, consider recreating it or manually restoring the `index.txt` file (though recreation is safer).
Upgrade
Version history
6.13.0latest on npm
Audit
Dependencies
opensslrequiredRequired system dependency for cryptographic operations. Automatically downloaded on Windows, but needs manual installation on Linux/macOS.
Agent activity
12 hits · last 30 days
node
10
Amazon
1
OpenAI (training)
1
Resources