{"id":15148,"library":"node-opcua-pki","title":"PKI Management for node-opcua","description":"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.","status":"active","version":"6.13.0","language":"javascript","source_language":"en","source_url":"https://github.com/node-opcua/node-opcua-pki","tags":["javascript","PKI","node-opcua","typescript"],"install":[{"cmd":"npm install node-opcua-pki","lang":"bash","label":"npm"},{"cmd":"yarn add node-opcua-pki","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-opcua-pki","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required system dependency for cryptographic operations. Automatically downloaded on Windows, but needs manual installation on Linux/macOS.","package":"openssl","optional":false}],"imports":[{"note":"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+.","wrong":"const CertificateManager = require('node-opcua-pki').CertificateManager;","symbol":"CertificateManager","correct":"import { CertificateManager } from 'node-opcua-pki';"},{"note":"Import `CertificateAuthority` directly from the main package entry point. Avoid importing from internal `dist` paths, as these are subject to change.","wrong":"import { CertificateAuthority } from 'node-opcua-pki/dist/pki/certificate_authority';","symbol":"CertificateAuthority","correct":"import { CertificateAuthority } from 'node-opcua-pki';"},{"note":"`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.","wrong":"import { initializeCSR } from 'node-opcua-pki/lib/pki/certificate_authority';","symbol":"initializeCSR","correct":"import { initializeCSR } from 'node-opcua-pki';"}],"quickstart":{"code":"#!/bin/bash\n\n# This script demonstrates how to set up a basic PKI structure and generate a self-signed certificate.\n# Prerequisites: Node.js (with npx) and OpenSSL (or LibreSSL) installed on your system.\n# For Debian/Ubuntu, install OpenSSL: `sudo apt install openssl`\n\n# Define a root directory for our PKI (relative path).\nPKI_ROOT=\"./my_opcua_pki_example\"\n\necho \"\\n--- 1. Creating a new OPC UA PKI directory structure in ${PKI_ROOT} ---\"\nnpx node-opcua-pki createPKI \\\n  --root \"${PKI_ROOT}\" \\\n  --keySize 2048 \\\n  --silent\n\n# Check if the PKI root directory was created\nif [ ! -d \"${PKI_ROOT}\" ]; then\n  echo \"Error: PKI root directory '${PKI_ROOT}' was not created. Exiting.\" >&2\n  exit 1\nfi\n\necho \"\\n--- 2. Creating a self-signed OPC UA Application Certificate ---\"\nnpx node-opcua-pki certificate \\\n  --root \"${PKI_ROOT}\" \\\n  --selfSigned \\\n  --applicationUri \"urn:my-opcua-server:application\" \\\n  --subject \"/C=US/ST=CA/L=SF/O=MyCompany/CN=MyOPCUAServer\" \\\n  -o \"${PKI_ROOT}/own/certs/server_certificate.pem\" \\\n  --dns \"localhost\" \\\n  --ip \"127.0.0.1\" \\\n  --validity 365 # Valid for 1 year\n\n# Check if the certificate was created\nif [ ! -f \"${PKI_ROOT}/own/certs/server_certificate.pem\" ]; then\n  echo \"Error: Server certificate was not created. Exiting.\" >&2\n  exit 1\nfi\n\necho \"\\n--- 3. Dumping the created certificate information for verification ---\"\nnpx node-opcua-pki dump \"${PKI_ROOT}/own/certs/server_certificate.pem\"\n\necho \"\\nPKI setup and self-signed certificate generation complete in '${PKI_ROOT}'.\"","lang":"bash","description":"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."},"warnings":[{"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.","message":"The 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.","severity":"breaking","affected_versions":">=6.5.0"},{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=6.0.0"},{"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.","message":"This 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"As 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.","severity":"gotcha","affected_versions":">=6.11.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"OpenSSL executable is not found in the system's PATH, or there's an issue with the OpenSSL installation itself (e.g., missing dependencies).","error":"Error: Command failed: openssl req -new -key ..."},{"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.","cause":"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.","error":"TypeError: CertificateManager is not a constructor"},{"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).","cause":"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.","error":"Error: unable to find 'index.txt' in Certificate Authority folder"}],"ecosystem":"npm"}