PKI Management for node-opcua

Common errors

• Error: Command failed: openssl req -new -key ...

  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).
  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

  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.
  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

  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.
  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).

Warnings

• breaking 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install node-opcua-pki npm
• yarn add node-opcua-pki yarn
• pnpm add node-opcua-pki pnpm

Imports

• CertificateManager
  wrong:

  const CertificateManager = require('node-opcua-pki').CertificateManager;

  correct:

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

  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
  wrong:

  import { CertificateAuthority } from 'node-opcua-pki/dist/pki/certificate_authority';

  correct:

  import { CertificateAuthority } from 'node-opcua-pki';

  Import `CertificateAuthority` directly from the main package entry point. Avoid importing from internal `dist` paths, as these are subject to change.
• initializeCSR
  wrong:

  import { initializeCSR } from 'node-opcua-pki/lib/pki/certificate_authority';

  correct:

  import { initializeCSR } from 'node-opcua-pki';

  `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.

Quickstart

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}'."