node-opcua-pki 6.19.0 → 6.20.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { SubjectOptions, CertificatePurpose, Subject, PrivateKey, Certificate, DER, CertificateRevocationList } from 'node-opcua-crypto';
-export { Subject, SubjectOptions } from 'node-opcua-crypto';
+import { SubjectOptions, PrivateKey, CertificatePurpose, Subject, Certificate, DER, CertificateRevocationList } from 'node-opcua-crypto';
+export { PrivateKeyPassphraseRequiredError, Subject, SubjectOptions } from 'node-opcua-crypto';
 import { EventEmitter } from 'node:events';
 
 /** RSA key size in bits. */
@@ -44,8 +44,12 @@ interface CreateCertificateSigningRequestWithConfigOptions extends CreateCertifi
     rootDir: Filename;
     /** Path to the OpenSSL configuration file. */
     configFile: Filename;
-    /** Path to the private key file. */
-    privateKey: Filename;
+    /**
+     * The private key: either a filesystem path to a PEM file (unencrypted;
+     * the historical behavior), or an already-resolved in-memory
+     * {@link PrivateKey} — see {@link CreateSelfSignCertificateWithConfigParam.privateKey}.
+     */
+    privateKey: Filename | PrivateKey;
     /** Intended purpose of the certificate. */
     purpose: CertificatePurpose;
 }
@@ -87,11 +91,36 @@ interface CreateSelfSignCertificateWithConfigParam extends CreateSelfSignCertifi
     rootDir: Filename;
     /** Path to the OpenSSL configuration file. */
     configFile: Filename;
-    /** Path to the private key file. */
-    privateKey: Filename;
+    /**
+     * The private key: either a filesystem path to a PEM file (unencrypted;
+     * the historical behavior), or an already-resolved in-memory
+     * {@link PrivateKey} — used when the key is passphrase-protected on
+     * disk, so the decrypted key material is never written back out in
+     * cleartext.
+     */
+    privateKey: Filename | PrivateKey;
     /** Intended purpose of the certificate. */
     purpose: CertificatePurpose;
 }
+/**
+ * A passphrase, or a function resolving one — called lazily, and at most
+ * once per `CertificateManager` / `CertificateAuthority` instance (the
+ * result is cached in memory). Never logged.
+ */
+type PrivateKeyPassphrase = string | (() => Promise<string>);
+/**
+ * Sources a {@link PrivateKey} from somewhere other than the local
+ * filesystem (an HSM, a KMS, ...). When configured on `CertificateManager`,
+ * it overrides disk entirely — the on-disk `own/private/private_key.pem` is
+ * neither generated nor read. `CertificateAuthority` does not support a
+ * provider (its signing paths are openssl reading a key file); it does
+ * support `privateKeyPassphrase`.
+ */
+interface PrivateKeyProvider {
+    getPrivateKey(): Promise<PrivateKey>;
+}
+/** Resolve a {@link PrivateKeyPassphrase}, if configured. */
+declare function resolvePrivateKeyPassphrase(passphrase: PrivateKeyPassphrase | undefined): Promise<string | undefined>;
 /**
  * General-purpose parameters passed to CA operations such as
  * {@link CertificateAuthority.signCertificateRequest} and
@@ -114,6 +143,18 @@ interface Params extends ProcessAltNamesParam, StartDateEndDateParam {
 declare function adjustDate(params: StartDateEndDateParam): void;
 declare function adjustApplicationUri(params: Params): void;
 
+/** openssl argv entries plus the env they need; merge `env` into `ExecuteOptions.env`. */
+interface OpensslPassArg {
+    args: string[];
+    env: NodeJS.ProcessEnv;
+}
+
+/**
+ *
+ * return path to the openssl executable
+ */
+declare function install_prerequisite(): Promise<string>;
+
 /**
  * Result of {@link CertificateAuthority.initializeCSR}.
  *
@@ -194,6 +235,24 @@ interface CertificateAuthorityOptions {
      * repair). Leave undefined to omit (US-202).
      */
     caIssuersUrl?: string;
+    /**
+     * Encrypt the CA private key (`private/cakey.pem`) at rest with this
+     * passphrase (opt-in, default off). When set:
+     * - a freshly generated CA key is written as encrypted PKCS#8;
+     * - an existing *plaintext* CA key is encrypted in place by
+     *   {@link CertificateAuthority.initialize} / `initializeCSR()`;
+     * - every `openssl` invocation that loads the CA key (CSR, self-sign,
+     *   sign, revoke, CRL generation) receives it via `-passin env:`, never
+     *   in argv; a missing or wrong passphrase fails `initialize()` closed.
+     *
+     * A function is called at most once per instance; the resolved
+     * passphrase is kept in memory for the instance's lifetime because the
+     * CA hands it to each openssl child. Never logged.
+     *
+     * A subordinate CA (`issuerCA` set) uses the *issuer's* passphrase for
+     * the issuer's key: construct the parent with its own option.
+     */
+    privateKeyPassphrase?: PrivateKeyPassphrase;
 }
 /**
  * An OpenSSL-based Certificate Authority (CA) that can create,
@@ -337,6 +396,7 @@ interface GenerateKeyPairAndSignPFXOptions extends GenerateKeyPairAndSignOptions
     passphrase?: string;
 }
 declare class CertificateAuthority {
+    #private;
     /** RSA key size used when generating the CA private key. */
     readonly keySize: KeySize;
     /** Root filesystem path of the CA directory structure. */
@@ -404,6 +464,33 @@ declare class CertificateAuthority {
     get rootDir(): string;
     /** Path to the OpenSSL configuration file (`conf/caconfig.cnf`). */
     get configFile(): string;
+    /** Path to the CA private key (`private/cakey.pem`); may be passphrase-encrypted, see {@link getPrivateKey}. */
+    get privateKey(): string;
+    /**
+     * The CA private key, decrypted with the configured `privateKeyPassphrase`
+     * if it is encrypted. Fails closed (`PrivateKeyPassphraseRequiredError`)
+     * on an encrypted key with no or the wrong passphrase.
+     */
+    getPrivateKey(): Promise<PrivateKey>;
+    /**
+     * Enable, disable, or rotate the passphrase protecting `private/cakey.pem`
+     * (temp file + atomic rename, temp file removed on failure). Only
+     * rewrites the file: construct a new `CertificateAuthority` with the new
+     * passphrase to continue using it.
+     */
+    reencryptPrivateKey(oldPassphrase?: PrivateKeyPassphrase, newPassphrase?: PrivateKeyPassphrase): Promise<void>;
+    /** @internal resolve the configured passphrase, at most once per instance */
+    _privateKeyPassphrase(): Promise<string | undefined>;
+    /** @internal `-passin env:` argv + env for every openssl call that loads this CA's key (always emitted, empty when none) */
+    _opensslPassin(): Promise<OpensslPassArg>;
+    /**
+     * @internal On an existing key: encrypt it in place if a passphrase is
+     * configured and it is still plaintext (secure by default: the option
+     * means "protect this key", not "ignore me"), then read it back so a
+     * wrong or missing passphrase fails initialize() closed rather than the
+     * first signing operation.
+     */
+    _ensurePrivateKeyProtection(): Promise<void>;
     /** Path to the CA certificate in PEM format (`public/cacert.pem`). */
     get caCertificate(): string;
     /**
@@ -836,6 +923,37 @@ interface CertificateManagerOptions {
      * @defaultValue false
      */
     disableFileWatchers?: boolean;
+    /**
+     * Encrypt the private key at rest with this passphrase (opt-in,
+     * default off). When set:
+     * - a freshly generated key is written as encrypted PKCS#8;
+     * - an existing *plaintext* key is re-encrypted in place by
+     *   {@link CertificateManager.initialize} (atomic rename, same as
+     *   {@link CertificateManager.reencryptPrivateKey}), so enabling the
+     *   option on an existing install never leaves the key in cleartext;
+     * - an existing encrypted key requires the same passphrase — a
+     *   mismatch, or an encrypted key with no passphrase configured, fails
+     *   `initialize()` closed with `PrivateKeyPassphraseRequiredError`.
+     *
+     * A function is called at most once per `CertificateManager` instance
+     * (the decrypted key is cached in memory for the instance's lifetime,
+     * see {@link CertificateManager.getPrivateKey}). Never logged.
+     *
+     * Existing consumers that read `own/private/private_key.pem` directly
+     * (e.g. node-opcua's `OPCUAServer`, or `createPFX` without its
+     * `privateKeyPassphrase` option) still expect a plaintext key — do not
+     * enable this unless every reader of that file goes through
+     * {@link CertificateManager.getPrivateKey} or is given the passphrase.
+     */
+    privateKeyPassphrase?: PrivateKeyPassphrase;
+    /**
+     * Source the private key from somewhere other than
+     * `own/private/private_key.pem` (an HSM, a KMS, ...). When set, it
+     * overrides disk entirely for every operation that needs the private
+     * key — the on-disk file is not read, and `privateKeyPassphrase` is
+     * ignored.
+     */
+    privateKeyProvider?: PrivateKeyProvider;
 }
 /**
  * Parameters for {@link createSelfSignedCertificate}.
@@ -1104,8 +1222,53 @@ declare class CertificateManager extends EventEmitter {
     get configFile(): string;
     /** Root directory of the PKI store. */
     get rootDir(): string;
-    /** Path to the private key file (`own/private/private_key.pem`). */
+    /**
+     * Path to the private key file (`own/private/private_key.pem`).
+     *
+     * Kept for backward compatibility with code that reads the key
+     * directly from disk. When a passphrase or a `privateKeyProvider` is
+     * configured, prefer {@link getPrivateKey} instead — this getter still
+     * returns the on-disk path even if a provider is configured (there may
+     * be no meaningful file in that case).
+     */
     get privateKey(): string;
+    /**
+     * Resolve the private key: from `privateKeyProvider` if configured,
+     * otherwise from disk (decrypting with `privateKeyPassphrase` if the
+     * key is encrypted). Fails closed — throws
+     * `PrivateKeyPassphraseRequiredError` — if the on-disk key is encrypted
+     * and no passphrase is configured, or if the wrong passphrase is
+     * configured.
+     *
+     * The on-disk key is read and decrypted once and then cached for the
+     * lifetime of this instance, so a `privateKeyPassphrase` function is
+     * called at most once (concurrent first calls share the same read). A
+     * failed read is not cached, so a caller can fix the passphrase and
+     * retry. A `privateKeyProvider` is consulted on every call: it is the
+     * authority on what the current key is.
+     */
+    getPrivateKey(): Promise<PrivateKey>;
+    /**
+     * Enable, disable, or rotate the passphrase protecting the on-disk
+     * private key: decrypt with `oldPassphrase` (omit if the key is
+     * currently unencrypted), then write back encrypted with
+     * `newPassphrase` (omit to leave it unencrypted). The write goes to a
+     * temporary file in the same directory and is atomically renamed into
+     * place, so a crash mid-rotation cannot leave a partially-written key;
+     * the temporary file is removed if anything fails, so a rotation *to*
+     * plaintext can never leave a stray cleartext copy behind. Runs under
+     * the same lock as `initialize()`.
+     *
+     * This only rewrites the on-disk file — it does not update this
+     * instance's own `privateKeyPassphrase` (set at construction), and it
+     * drops this instance's cached key so that disk stays the source of
+     * truth. Construct a new `CertificateManager` with the new passphrase to
+     * continue using it afterward.
+     *
+     * Not supported when a `privateKeyProvider` is configured (there is no
+     * disk file for this method to rewrite).
+     */
+    reencryptPrivateKey(oldPassphrase?: PrivateKeyPassphrase, newPassphrase?: PrivateKeyPassphrase): Promise<void>;
     /** Path to the OpenSSL random seed file. */
     get randomFile(): string;
     /**
@@ -1385,8 +1548,15 @@ declare class CertificateManager extends EventEmitter {
 interface CreatePFXOptions {
     /** Path to the certificate file (PEM or DER). */
     certificateFile: Filename;
-    /** Path to the private key file (PEM). */
+    /** Path to the private key file (PEM, plaintext or encrypted PKCS#8). */
     privateKeyFile: Filename;
+    /**
+     * Passphrase that decrypts `privateKeyFile` if it is an encrypted
+     * PKCS#8 key (e.g. a `CertificateManager` created with
+     * `privateKeyPassphrase`). Omit for a plaintext key. This is distinct
+     * from `passphrase`, which protects the *output* PFX bundle.
+     */
+    privateKeyPassphrase?: string;
     /** Output path for the generated PFX file. */
     outputFile: Filename;
     /**
@@ -1435,8 +1605,14 @@ interface ExtractPFXResult {
  *   -in <cert> -inkey <key>
  *   [-certfile <ca>]
  *   -out <pfx>
- *   -passout pass:<passphrase>
+ *   -passin  env:NODE_OPCUA_PKI_OPENSSL_PASSIN
+ *   -passout env:NODE_OPCUA_PKI_OPENSSL_PASSOUT
  * ```
+ * Both passphrases are passed via per-invocation environment variables,
+ * never placed in argv — see {@link ExecuteOptions.env}.
+ * `-passin` is always present (empty when the key is plaintext) so that an
+ * encrypted key without a `privateKeyPassphrase` fails fast rather than
+ * leaving openssl waiting on a terminal prompt that never comes.
  *
  * @param options — see {@link CreatePFXOptions}
  */
@@ -1447,8 +1623,10 @@ declare function createPFX(options: CreatePFXOptions): Promise<void>;
  * Wraps:
  * ```
  * openssl pkcs12 -in <pfx> -clcerts -nokeys
- *   -passin pass:<passphrase>
+ *   -passin env:NODE_OPCUA_PKI_OPENSSL_PASSIN
  * ```
+ * The passphrase is passed via a per-invocation environment variable, never
+ * placed in argv — see {@link ExecuteOptions.env}.
  *
  * @returns the certificate in PEM format.
  */
@@ -1459,8 +1637,10 @@ declare function extractCertificateFromPFX(options: ExtractPFXOptions): Promise<
  * Wraps:
  * ```
  * openssl pkcs12 -in <pfx> -nocerts -nodes
- *   -passin pass:<passphrase>
+ *   -passin env:NODE_OPCUA_PKI_OPENSSL_PASSIN
  * ```
+ * The passphrase is passed via a per-invocation environment variable, never
+ * placed in argv — see {@link ExecuteOptions.env}.
  *
  * @returns the private key in PEM format.
  */
@@ -1471,8 +1651,10 @@ declare function extractPrivateKeyFromPFX(options: ExtractPFXOptions): Promise<s
  * Wraps:
  * ```
  * openssl pkcs12 -in <pfx> -cacerts -nokeys -nodes
- *   -passin pass:<passphrase>
+ *   -passin env:NODE_OPCUA_PKI_OPENSSL_PASSIN
  * ```
+ * The passphrase is passed via a per-invocation environment variable, never
+ * placed in argv — see {@link ExecuteOptions.env}.
  *
  * @returns the CA certificates in PEM format
  *          (empty string if none are present).
@@ -1492,8 +1674,10 @@ declare function extractAllFromPFX(options: ExtractPFXOptions): Promise<ExtractP
  * Wraps:
  * ```
  * openssl pkcs12 -in <pfx> -out <pem> -nodes
- *   -passin pass:<passphrase>
+ *   -passin env:NODE_OPCUA_PKI_OPENSSL_PASSIN
  * ```
+ * The passphrase is passed via a per-invocation environment variable, never
+ * placed in argv — see {@link ExecuteOptions.env}.
  */
 declare function convertPFXtoPEM(pfxFile: Filename, pemFile: Filename, passphrase?: string): Promise<void>;
 /**
@@ -1502,17 +1686,13 @@ declare function convertPFXtoPEM(pfxFile: Filename, pemFile: Filename, passphras
  * Wraps:
  * ```
  * openssl pkcs12 -in <pfx> -info -noout
- *   -passin pass:<passphrase>
+ *   -passin env:NODE_OPCUA_PKI_OPENSSL_PASSIN
  * ```
+ * The passphrase is passed via a per-invocation environment variable, never
+ * placed in argv — see {@link ExecuteOptions.env}.
  *
  * @returns the human-readable dump as a string.
  */
 declare function dumpPFX(pfxFile: Filename, passphrase?: string): Promise<string>;
 
-/**
- *
- * return path to the openssl executable
- */
-declare function install_prerequisite(): Promise<string>;
-
-export { type AddCertificateValidationOptions, CertificateAuthority, type CertificateAuthorityOptions, CertificateManager, type CertificateManagerEvents, type CertificateManagerOptions, CertificateManagerState, type CertificateStatus, type CertificateStore, type ChainCompletionResult, ChainCompletionStatus, type CreateCertificateSigningRequestOptions, type CreateCertificateSigningRequestWithConfigOptions, type CreatePFXOptions, type CreateSelfSignCertificateParam, type CreateSelfSignCertificateParam1, type CreateSelfSignCertificateWithConfigParam, type CrlStore, type ExtractPFXOptions, type ExtractPFXResult, type Filename, type GenerateKeyPairAndSignOptions, type GenerateKeyPairAndSignPFXOptions, type InitializeCSRResult, type InstallCACertificateResult, type KeyLength, type KeySize, type Params, type PkiBackendCapabilities, type ProcessAltNamesParam, type SignCertificateOptions, type StartDateEndDateParam, type Thumbprint, VerificationStatus, type VerifyCertificateOptions, adjustApplicationUri, adjustDate, coerceCertificateChain, convertPFXtoPEM, createPFX, dumpPFX, extractAllFromPFX, extractCACertificatesFromPFX, extractCertificateFromPFX, extractPrivateKeyFromPFX, findIssuerCertificateInChain, install_prerequisite, isIntermediateIssuer, isIssuer, isRootIssuer, makeFingerprint, quote };
+export { type AddCertificateValidationOptions, CertificateAuthority, type CertificateAuthorityOptions, CertificateManager, type CertificateManagerEvents, type CertificateManagerOptions, CertificateManagerState, type CertificateStatus, type CertificateStore, type ChainCompletionResult, ChainCompletionStatus, type CreateCertificateSigningRequestOptions, type CreateCertificateSigningRequestWithConfigOptions, type CreatePFXOptions, type CreateSelfSignCertificateParam, type CreateSelfSignCertificateParam1, type CreateSelfSignCertificateWithConfigParam, type CrlStore, type ExtractPFXOptions, type ExtractPFXResult, type Filename, type GenerateKeyPairAndSignOptions, type GenerateKeyPairAndSignPFXOptions, type InitializeCSRResult, type InstallCACertificateResult, type KeyLength, type KeySize, type Params, type PkiBackendCapabilities, type PrivateKeyPassphrase, type PrivateKeyProvider, type ProcessAltNamesParam, type SignCertificateOptions, type StartDateEndDateParam, type Thumbprint, VerificationStatus, type VerifyCertificateOptions, adjustApplicationUri, adjustDate, coerceCertificateChain, convertPFXtoPEM, createPFX, dumpPFX, extractAllFromPFX, extractCACertificatesFromPFX, extractCertificateFromPFX, extractPrivateKeyFromPFX, findIssuerCertificateInChain, install_prerequisite, isIntermediateIssuer, isIssuer, isRootIssuer, makeFingerprint, quote, resolvePrivateKeyPassphrase };