Node-OPCUA Crypto Tools

5.3.5 · active · verified Sun Apr 19

Node-OPCUA Crypto is a robust, TypeScript-first JavaScript module designed to provide a comprehensive suite of cryptographic functionalities specifically for the OPC UA standard. It seamlessly operates in both Node.js and browser environments, ensuring broad compatibility for various industrial IoT and M2M applications. The library is currently on its stable version 5.3.5, with recent releases, such as v5.2.0, focusing on critical improvements like dependency reduction, enhanced browser compatibility, and the introduction of new cryptographic utilities including CRL-to-issuer matching. Key differentiators include its deep integration with OPC UA security requirements, support for generating private keys and X.509 self-signed certificates using native WebCrypto APIs, and dual CommonJS/ESM module support since version 3.0.0. This makes it a foundational component for securing OPC UA communications, offering tools for certificate management, key generation, and compliance with modern cryptographic practices. The project maintains an active release cadence, addressing bugs and introducing features regularly.

Common errors

```
Error: Certificate validation failed: Missing AuthorityKeyIdentifier
```
cause A bug in `node-opcua-crypto` versions 4.0.0 to 4.5.0 caused generated self-signed certificates to omit the AuthorityKeyIdentifier extension.

fix Upgrade `node-opcua-crypto` to version 4.5.0 or higher to correctly include the AuthorityKeyIdentifier.
```
TypeError: Cannot read properties of undefined (reading 'createX509Certificate')
```
cause This error often indicates a misuse of the `@peculiar/x509` API, specifically when passing non-standard attributes like `netscapeComment`, which was fixed in v4.2.0.

fix Ensure correct API usage, or upgrade to `node-opcua-crypto` v4.2.0 or newer if the issue is related to how certificates are created internally by the library.
```
Error: unable to parse certificate extension: Unknown OID for otherName
```
cause Older versions of the `exploreCertificate` utility (prior to v4.10.0) did not correctly support 'othernames' fields within the SubjectAltName extension, leading to parsing failures.

fix Update `node-opcua-crypto` to version 4.10.0 or later to ensure proper parsing of certificates with 'othernames' in SubjectAltName.
```
ERR_REQUIRE_ESM: Must use import to load ES Module
```
cause Attempting to `require()` the package in a CommonJS context when the package is configured as an ESM module, or mixing `require` and `import` incorrectly in a dual-module setup (since v3.0.0).

fix For projects running Node.js with ESM enabled, use `import` statements. If a CJS-only context is required, ensure the package version is compatible or use dynamic `import()` if necessary. Consider configuring `package.json` with `"type": "module"` and using `import`.

Warnings

breaking Version 5.0.0 dropped official support for Node.js versions 16, 18, and 20. Projects targeting these Node.js versions should remain on `node-opcua-crypto` v4.x.
Fix: Upgrade Node.js to version 22 or newer, or pin `node-opcua-crypto` to a v4.x release.
gotcha Incorrect module import paths for browser vs. Node.js environments. Since v4.11.0, explicit paths are recommended for optimal bundling and functionality.
Fix: For Node.js apps, use `import * as crypto from 'node-opcua-crypto';`. For browser environments (or Node.js apps that don't need file system APIs), use `import * as crypto from 'node-opcua-crypto/web';`.
breaking The package transitioned to being a dual CommonJS and ESM module in v3.0.0. This can affect how imports are resolved, especially in environments that strictly distinguish between module types.
Fix: Ensure your project's `tsconfig.json` or build tools are configured to correctly handle ESM imports (`"type": "module"` in `package.json` for Node.js projects, or specific bundler configurations for browsers). Prefer `import` statements over `require()` where possible.
gotcha Versions between 4.0.0 and 4.5.0 introduced a regression causing the `AuthorityKeyIdentifier` property to be missing in generated self-signed certificates, which could lead to validation issues in some OPC UA applications.
Fix: Upgrade to version 4.5.0 or newer to resolve the `AuthorityKeyIdentifier` regression.
breaking Version 4.7.0 updated the `jsrsasign` dependency to address RSA and RSAOAEP encryption vulnerabilities. Although not a direct breaking API change, failing to update can expose applications to security risks.
Fix: Upgrade to version 4.7.0 or newer to patch known vulnerabilities related to `jsrsasign`.

Install

npm install node-opcua-crypto npm
yarn add node-opcua-crypto yarn
pnpm add node-opcua-crypto pnpm

Imports

generatePrivateKey
wrong:
```
const { generatePrivateKey } = require('node-opcua-crypto');
```
correct:
```
import { generatePrivateKey } from 'node-opcua-crypto';
```
ESM is the primary export since v3.0.0. For older Node.js versions or CJS, use 'require' but prefer ESM.

createSelfSignedCertificate

wrong:

import createSelfSignedCertificate from 'node-opcua-crypto/dist/createSelfSignedCertificate';

correct:

import { createSelfSignedCertificate, CertificatePurpose } from 'node-opcua-crypto';

Ensure to import named exports from the top-level package. Also import enums like CertificatePurpose.

* as crypto
wrong:
```
import * as crypto from 'node-opcua-crypto/web';
```
correct:
```
import * as crypto from 'node-opcua-crypto';
```
Use `node-opcua-crypto` for Node.js applications. For browser environments or Node.js apps without file system APIs, use `import * as crypto from 'node-opcua-crypto/web'` (recommended since v4.11.0).
identifyDERContent
```
import { identifyDERContent } from 'node-opcua-crypto/dist/identify_der';
```
Some specific utilities, like `identifyDERContent` (added in v5.2.0), might be found under deeper paths within the `dist` directory.

Quickstart

This quickstart demonstrates how to generate a private key and then use it to create a self-signed X.509 certificate, common for OPC UA server and client identities.

import { generatePrivateKey, privateKeyToPEM, CertificatePurpose, createSelfSignedCertificate } from 'node-opcua-crypto';

async function demonstratePrivateKeyAndSelfSignedCertificateCreation() {
    // Create a new private key
    const privateKey = await generatePrivateKey();

    // Convert the private key to a PEM format for storage or display
    const { privPem } = await privateKeyToPEM(privateKey);

    console.log('Generated Private Key (PEM format):\n', privPem);

    // Create a self-signed X.509 certificate
    const { cert } = await createSelfSignedCertificate({
        privateKey,
        notAfter: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000), // Valid for 1 year from now
        notBefore: new Date(),
        subject: 'CN=Test Server, O=MyCompany, L=City, ST=State, C=US',
        dns: ['localhost', 'my-server.example.com'],
        ip: ['127.0.0.1'],
        applicationUri: 'urn:TestServer:MyApplication',
        purpose: CertificatePurpose.ForApplication
    });
    console.log('\nGenerated Self-Signed Certificate (PEM format):\n', cert);
}

demonstratePrivateKeyAndSelfSignedCertificateCreation().catch(console.error);

view raw JSON →