node-opcua-pki 6.20.0 → 6.22.0

package/dist/index.d.mts

@@ -1,147 +1,29 @@
-import { SubjectOptions, PrivateKey, CertificatePurpose, Subject, Certificate, DER, CertificateRevocationList } from 'node-opcua-crypto';
-export { PrivateKeyPassphraseRequiredError, Subject, SubjectOptions } from 'node-opcua-crypto';
+import { IKeyOperations, PrivateKey, Certificate, SubjectOptions, DER, CertificateRevocationList } from 'node-opcua-crypto';
+export { AsymmetricDecryptParams, AsymmetricSignParams, IKeyOperations, KeyMetadata, PrivateKeyPassphraseRequiredError, PrivateKeyUnavailableError, Subject, SubjectOptions } from 'node-opcua-crypto';
+import { C as CaBackend, a as CertificateAuthorityCore, P as Params, b as ProcessAltNamesParam, c as CertificateAuthorityCoreOptions, K as KeySize, d as PrivateKeyPassphrase, e as PrivateKeyProvider, f as CreateSelfSignCertificateParam, F as Filename } from './core-BwqSJPHc.mjs';
+export { g as CertificateStatus, h as CreateCertificateSigningRequestOptions, i as CreateCertificateSigningRequestWithConfigOptions, j as CreateSelfSignCertificateWithConfigParam, G as GenerateKeyPairAndSignOptions, k as GenerateKeyPairAndSignPFXOptions, I as InitializeCSRResult, l as InstallCACertificateResult, m as KeyLength, N as NativeCaBackend, n as PkiBackendCapabilities, S as SignCertificateOptions, o as StartDateEndDateParam, T as Thumbprint, p as adjustApplicationUri, q as adjustDate, r as isOpaqueSigner, s as quote, t as resolvePrivateKeyPassphrase } from './core-BwqSJPHc.mjs';
 import { EventEmitter } from 'node:events';
 
-/** RSA key size in bits. */
-type KeySize = 1024 | 2048 | 3072 | 4096;
-/** Hex-encoded SHA-1 certificate thumbprint. */
-type Thumbprint = string;
-/** A filesystem path to a file. */
-type Filename = string;
-/** Status of a certificate in the trust store. */
-type CertificateStatus = "unknown" | "trusted" | "rejected";
-
-/**
- * @deprecated Use {@link KeySize} instead.
- */
-type KeyLength = 1024 | 2048 | 3072 | 4096;
-declare function quote(str?: string): string;
-/**
- * Subject Alternative Name (SAN) parameters for certificate
- * generation.
- */
-interface ProcessAltNamesParam {
-    /** DNS host names to include in the SAN extension. */
-    dns?: string[];
-    /** IP addresses to include in the SAN extension. */
-    ip?: string[];
-    /** OPC UA application URI for the SAN extension. */
-    applicationUri?: string;
-}
-/**
- * Options for creating a Certificate Signing Request (CSR).
- */
-interface CreateCertificateSigningRequestOptions extends ProcessAltNamesParam {
-    /** X.500 subject for the certificate. */
-    subject?: SubjectOptions | string;
-}
-/**
- * Extended CSR options that include filesystem paths and
- * certificate purpose — used internally by the OpenSSL toolbox.
- */
-interface CreateCertificateSigningRequestWithConfigOptions extends CreateCertificateSigningRequestOptions {
-    /** Root directory of the PKI store. */
-    rootDir: Filename;
-    /** Path to the OpenSSL configuration file. */
-    configFile: 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;
-}
-/**
- * Validity period parameters for certificate generation.
- */
-interface StartDateEndDateParam {
-    /** Certificate "Not Before" date. Defaults to now. */
-    startDate?: Date;
-    /** Certificate "Not After" date (computed from validity). */
-    endDate?: Date;
-    /** Number of days the certificate is valid. @defaultValue 365 */
-    validity?: number;
-    /**
-     * Certificate validity in milliseconds.
-     *
-     * When provided, takes precedence over {@link validity} and enables
-     * sub-day validity (X.509 supports second precision per RFC 5280
-     * §4.1.2.5; OpenSSL is invoked with `-startdate`/`-enddate` already).
-     *
-     * Typical use is short-lived certificates for demos or for renewal
-     * cycle testing. Existing day-based callers are unaffected.
-     */
-    validityMs?: number;
-}
-/**
- * Parameters for creating a self-signed certificate.
- */
-interface CreateSelfSignCertificateParam extends ProcessAltNamesParam, StartDateEndDateParam {
-    /** X.500 subject for the certificate. */
-    subject?: SubjectOptions | string;
-}
-/**
- * Extended self-signed certificate options that include
- * filesystem paths and purpose — used internally.
- */
-interface CreateSelfSignCertificateWithConfigParam extends CreateSelfSignCertificateParam {
-    /** Root directory of the PKI store. */
-    rootDir: Filename;
-    /** Path to the OpenSSL configuration file. */
-    configFile: 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
- * {@link CertificateAuthority.revokeCertificate}.
+ * The default {@link CaBackend}: shells out to the `openssl` CLI, exactly as
+ * `CertificateAuthority` always has — this is a pure code move (plus a lock
+ * around every database-mutating operation, temp-config cleanup, and
+ * explicit `envOverrides` on every config render) with no change in the
+ * openssl commands issued or the files produced.
  */
-interface Params extends ProcessAltNamesParam, StartDateEndDateParam {
-    /** X.500 subject for the certificate. */
-    subject?: SubjectOptions | string;
-    /** Path to the private key file. */
-    privateKey?: string;
-    /** Path to the OpenSSL configuration file. */
-    configFile?: string;
-    /** Root directory of the PKI store. */
-    rootDir?: string;
-    /** Output filename for the generated certificate. */
-    outputFile?: string;
-    /** CRL revocation reason (e.g. `"keyCompromise"`). */
-    reason?: string;
+declare class OpenSslCaBackend implements CaBackend {
+    #private;
+    /** The openssl CLI loads its key from a file, so it cannot call out to an HSM. */
+    readonly supportsExternalSigner = false;
+    preflight(): Promise<void>;
+    generateCaCsr(ca: CertificateAuthorityCore, _caRootDir: string, privateKeyFile: string, csrFile: string): Promise<void>;
+    bootstrap(ca: CertificateAuthorityCore): Promise<void>;
+    regenerateCrl(ca: CertificateAuthorityCore): Promise<void>;
+    signSubordinateCsr(ca: CertificateAuthorityCore, csrFile: string, certFile: string, validityDays: number): Promise<void>;
+    signEndEntityCsr(ca: CertificateAuthorityCore, certificate: string, csr: string, params1: Params, sanOverride: Required<ProcessAltNamesParam>): Promise<void>;
+    revoke(ca: CertificateAuthorityCore, certificate: string, reason: string): Promise<void>;
+    createSelfSignedCertificate(ca: CertificateAuthorityCore, certificateFile: string, privateKeyFile: string, params: Params): Promise<void>;
 }
-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 {
@@ -156,660 +38,63 @@ interface OpensslPassArg {
 declare function install_prerequisite(): Promise<string>;
 
 /**
- * Result of {@link CertificateAuthority.initializeCSR}.
- *
- * - `"ready"` — the CA certificate already exists and is valid.
- * - `"pending"` — key + CSR exist but no cert; waiting for external signing.
- * - `"created"` — a fresh key + CSR were just generated.
- * - `"expired"` — the CA certificate has expired (or will expire within
- *   the configured threshold). A new CSR has been generated for renewal
- *   while preserving the existing private key.
- */
-type InitializeCSRResult = {
-    status: "ready";
-} | {
-    status: "pending";
-    csrPath: string;
-} | {
-    status: "created";
-    csrPath: string;
-} | {
-    status: "expired";
-    csrPath: string;
-    expiryDate: Date;
-};
-/**
- * Result of {@link CertificateAuthority.installCACertificate}.
- *
- * - `"success"` — the certificate was installed and CRL generated.
- * - `"error"` — the certificate was rejected (see `reason`).
- */
-type InstallCACertificateResult = {
-    status: "success";
-} | {
-    status: "error";
-    reason: string;
-    message: string;
-};
-/**
- * Options for creating a {@link CertificateAuthority}.
+ * Options for {@link CertificateAuthority}: the core's, except that the
+ * backend is named rather than supplied.
  */
-interface CertificateAuthorityOptions {
-    /** RSA key size for the CA private key. */
-    keySize: KeySize;
-    /** Filesystem path where the CA directory structure is stored. */
-    location: string;
-    /**
-     * X.500 subject for the CA certificate.
-     * Accepts a slash-delimited string (e.g. `"/CN=My CA/O=Acme"`) or
-     * a structured {@link SubjectOptions} object.
-     *
-     * @defaultValue {@link defaultSubject}
-     */
-    subject?: string | SubjectOptions;
-    /**
-     * Parent CA that will sign this CA's certificate.
-     * If omitted, the CA is self-signed (root CA).
-     * The parent CA must be initialized before this CA.
-     */
-    issuerCA?: CertificateAuthority;
+interface CertificateAuthorityOptions extends Omit<CertificateAuthorityCoreOptions, "backend"> {
     /**
-     * Public URL (http/https) where the CRL produced by this CA is
-     * reachable. When set, every issued certificate carries an
-     * X.509v3 `crlDistributionPoints` extension pointing at this URL.
-     *
-     * Leave undefined to omit the extension entirely (opt-in — see
-     * US-202).  Validated synchronously at construction / setter call.
-     */
-    crlDistributionUrl?: string;
-    /**
-     * Public URL of the OCSP responder. When set, every issued cert
-     * carries an `authorityInfoAccess` extension with an `OCSP` leg
-     * pointing at this URL. Leave undefined to omit (US-202).
-     */
-    ocspResponderUrl?: string;
-    /**
-     * Public URL where the issuer's certificate can be fetched.
-     * When set, the `authorityInfoAccess` extension on every issued
-     * cert carries a `caIssuers` leg pointing at this URL (chain
-     * 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.
+     * Signing backend to use.
      *
-     * 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,
- * sign, and revoke X.509 certificates.
- *
- * The CA maintains a standard OpenSSL directory layout under
- * {@link CertificateAuthority.rootDir | rootDir}:
- *
- * ```
- * <location>/
- *   ├── conf/           OpenSSL configuration
- *   ├── private/        CA private key (cakey.pem)
- *   ├── public/         CA certificate  (cacert.pem)
- *   ├── certs/          Signed certificates
- *   ├── crl/            Revocation lists
- *   ├── serial          Next serial number
- *   ├── crlnumber       Next CRL number
- *   └── index.txt       Certificate database
- * ```
- *
- * @example
- * ```ts
- * const ca = new CertificateAuthority({
- *     keySize: 2048,
- *     location: "/var/pki/CA"
- * });
- * await ca.initialize();
- * ```
- */
-/**
- * A record from the OpenSSL CA certificate database
- * (`index.txt`).
- */
-interface IssuedCertificateRecord {
-    /** Hex-encoded serial number (e.g. `"1000"`). */
-    serial: string;
-    /** Certificate status. */
-    status: "valid" | "revoked" | "expired";
-    /** X.500 subject string (slash-delimited). */
-    subject: string;
-    /** Certificate expiry date as ISO-8601 string. */
-    expiryDate: string;
-    /**
-     * Revocation date as ISO-8601 string.
-     * Only present when `status === "revoked"`.
-     */
-    revocationDate?: string;
-}
-/**
- * Options for {@link CertificateAuthority.signCertificateRequestFromDER}.
- *
- * All fields are optional. When provided, they override the
- * corresponding values from the CSR.
- */
-interface SignCertificateOptions {
-    /** Certificate validity in days (default: 365). */
-    validity?: number;
-    /**
-     * Certificate validity in milliseconds.
+     * - `"openssl"` (default): shells out to the `openssl` CLI, as this
+     *   class always has.
+     * - `"native"`: signs in pure JS via `node-opcua-crypto`, writing the
+     *   same on-disk database format, and needs no `openssl` executable.
      *
-     * When provided, takes precedence over {@link validity} and enables
-     * sub-day validity (e.g. 10-minute certificates for renewal demos).
-     */
-    validityMs?: number;
-    /** Override the certificate start date. */
-    startDate?: Date;
-    /** Override DNS SANs. */
-    dns?: string[];
-    /** Override IP SANs. */
-    ip?: string[];
-    /** Override the application URI SAN. */
-    applicationUri?: string;
-    /** Override the X.500 subject. */
-    subject?: SubjectOptions | string;
-}
-/**
- * Capabilities advertised by a PKI backend (or by this
- * {@link CertificateAuthority}) so consumers can clamp requested
- * validity to the limits the backend can actually honor.
- *
- * Useful for the GDS Pull / Push management flows, where the CA may
- * be supplied by an external service (step-ca, EJBCA, …) with its
- * own minimum / maximum / granularity constraints.
- *
- * @see CertificateAuthority.getCapabilities
- */
-interface PkiBackendCapabilities {
-    /** Smallest validity this backend can issue, in milliseconds. */
-    minValidityMs: number;
-    /** Largest validity this backend will issue, in milliseconds. */
-    maxValidityMs: number;
-    /**
-     * Validity is rounded up to the nearest multiple of this many
-     * milliseconds. For `node-opcua-pki`'s OpenSSL-based CA this is
-     * 1 000 ms (one second — the X.509 floor per RFC 5280 §4.1.2.5).
-     */
-    validityGranularityMs: number;
-    /**
-     * Native unit the backend works in. Diagnostic only — callers
-     * always pass `validityMs` (US-208 / US-210).
-     */
-    nativeUnit: "second" | "minute" | "hour" | "day";
-}
-/**
- * Options for {@link CertificateAuthority.generateKeyPairAndSignDER}.
- */
-interface GenerateKeyPairAndSignOptions {
-    /** OPC UA application URI (required). */
-    applicationUri: string;
-    /** X.500 subject for the certificate (e.g. "CN=MyApp"). */
-    subject?: SubjectOptions | string;
-    /** DNS host names for the SAN extension. */
-    dns?: string[];
-    /** IP addresses for the SAN extension. */
-    ip?: string[];
-    /** Certificate validity in days (default: 365). */
-    validity?: number;
-    /**
-     * Certificate validity in milliseconds.
+     * Setting `signer` implies `"native"`, since the openssl CLI can only
+     * load a key from a file.
      *
-     * When provided, takes precedence over {@link validity} and enables
-     * sub-day validity (e.g. 10-minute certificates for renewal demos).
+     * To supply a backend instance directly - including one of your own -
+     * use {@link CertificateAuthorityCore}, which is also the class to
+     * build against when you do not want the openssl backend in your
+     * bundle at all.
      */
-    validityMs?: number;
-    /** Certificate start date (default: now). */
-    startDate?: Date;
-    /** RSA key size in bits (default: 2048). */
-    keySize?: KeySize;
+    backend?: "openssl" | "native";
 }
 /**
- * Options for {@link CertificateAuthority.generateKeyPairAndSignPFX}.
+ * A Certificate Authority with a backend chosen for you.
  *
- * Extends the DER options with an optional `passphrase` to protect
- * the PFX bundle.
+ * This is {@link CertificateAuthorityCore} plus the convenience that made
+ * it the historical API: name a backend, or name nothing and get openssl.
+ * Because it resolves the name, it necessarily references both backends,
+ * which is why the core exists separately - a program that never imports
+ * this class never pulls the openssl backend into its bundle.
  */
-interface GenerateKeyPairAndSignPFXOptions extends GenerateKeyPairAndSignOptions {
-    /**
-     * Passphrase to protect the PFX file.
-     * If omitted, the PFX is created without a password.
-     */
-    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. */
-    readonly location: string;
-    /** X.500 subject of the CA certificate. */
-    readonly subject: Subject;
-    /** @internal Parent CA (undefined for root CAs). */
-    readonly _issuerCA?: CertificateAuthority;
-    /** @internal Configured CDP / AIA URLs (US-202). */
-    private _crlDistributionUrl?;
-    private _ocspResponderUrl?;
-    private _caIssuersUrl?;
+declare class CertificateAuthority extends CertificateAuthorityCore {
     constructor(options: CertificateAuthorityOptions);
     /**
-     * Public URL where the CRL produced by this CA is reachable, or
-     * `undefined` if no CDP extension should be emitted on issued certs.
-     */
-    get crlDistributionUrl(): string | undefined;
-    /**
-     * Public URL of the OCSP responder, or `undefined` if no AIA OCSP
-     * leg should be emitted on issued certs.
-     */
-    get ocspResponderUrl(): string | undefined;
-    /**
-     * Public URL where the issuer's certificate can be fetched, or
-     * `undefined` if no AIA caIssuers leg should be emitted.
-     */
-    get caIssuersUrl(): string | undefined;
-    /**
-     * Configure the URL embedded as `crlDistributionPoints` in every
-     * subsequently-issued certificate. Pass `undefined` to disable
-     * the extension entirely. Validated synchronously — throws on
-     * empty string, non-http(s) protocol, missing path. Warns (does
-     * not throw) when the URL points at loopback.
+     * @internal `-passin env:` argv + env for an openssl call that loads
+     * this CA's key (always emitted, empty when none).
      *
-     * @see US-202
-     */
-    setCrlDistributionUrl(url: string | undefined): void;
-    /**
-     * Configure the OCSP responder URL embedded as the `OCSP` leg of
-     * the `authorityInfoAccess` extension on every subsequently-issued
-     * certificate. Pass `undefined` to disable.
-     *
-     * @see US-202
-     */
-    setOcspResponderUrl(url: string | undefined): void;
-    /**
-     * Configure the caIssuers URL embedded as the `caIssuers` leg of
-     * the `authorityInfoAccess` extension on every subsequently-issued
-     * certificate. Pass `undefined` to disable.
-     *
-     * @see US-202
-     */
-    setCaIssuersUrl(url: string | undefined): void;
-    /**
-     * @internal
-     * Populate the OpenSSL config substitution env vars (`CDP_URL` and
-     * `AIA_VALUE`) from the configured URLs, or unset them so the
-     * matching `{{#KEY}}...{{/KEY}}` blocks in the templates are
-     * stripped. MUST be called before every `generateStaticConfig`
-     * invocation that signs a certificate.
-     */
-    _wireRevocationEnvVars(): void;
-    /** Absolute path to the CA root directory (alias for {@link location}). */
-    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.
+     * The openssl backend builds its own now; this remains so that external
+     * code calling it keeps working, and lives here rather than on the core
+     * because the flag means nothing to a backend that spawns nothing.
      */
-    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;
-    /**
-     * Path to the issuer certificate chain (`public/issuer_chain.pem`).
-     *
-     * This file is created by {@link installCACertificate} when the
-     * provided cert file contains additional issuer certificates
-     * (e.g. intermediate + root). It is appended to signed certs
-     * by {@link constructCertificateChain} to produce a full chain
-     * per OPC UA Part 6 §6.2.6.
-     */
-    get issuerCertificateChain(): string;
-    /**
-     * Path to the current Certificate Revocation List in DER format.
-     * (`crl/revocation_list.der`)
-     */
-    get revocationListDER(): string;
-    /**
-     * Path to the current Certificate Revocation List in PEM format.
-     * (`crl/revocation_list.crl`)
-     */
-    get revocationList(): string;
-    /**
-     * Path to the concatenated CA certificate + CRL file.
-     * Used by OpenSSL for CRL-based verification.
-     */
-    get caCertificateWithCrl(): string;
-    /**
-     * Return the CA certificate as a DER-encoded buffer.
-     *
-     * @throws if the CA certificate file does not exist
-     *   (call {@link initialize} first).
-     */
-    getCACertificateDER(): Buffer;
-    /**
-     * Return the CA certificate as a PEM-encoded string.
-     *
-     * @throws if the CA certificate file does not exist
-     *   (call {@link initialize} first).
-     */
-    getCACertificatePEM(): string;
-    /**
-     * Return the current Certificate Revocation List as a
-     * DER-encoded buffer.
-     *
-     * Returns an empty buffer if no CRL has been generated yet.
-     */
-    getCRLDER(): Buffer;
-    /**
-     * Return the current Certificate Revocation List as a
-     * PEM-encoded string.
-     *
-     * Returns an empty string if no CRL has been generated yet.
-     */
-    getCRLPEM(): string;
-    /**
-     * Return a list of all issued certificates recorded in the
-     * OpenSSL `index.txt` database.
-     *
-     * Each entry includes the serial number, subject, status,
-     * expiry date, and (for revoked certs) the revocation date.
-     */
-    getIssuedCertificates(): IssuedCertificateRecord[];
-    /**
-     * Return the total number of certificates recorded in
-     * `index.txt`.
-     */
-    getIssuedCertificateCount(): number;
-    /**
-     * Return the status of a certificate by its serial number.
-     *
-     * @param serial - hex-encoded serial number (e.g. `"1000"`)
-     * @returns `"valid"`, `"revoked"`, `"expired"`, or
-     *   `undefined` if not found
-     */
-    getCertificateStatus(serial: string): "valid" | "revoked" | "expired" | undefined;
-    /**
-     * Read a specific issued certificate by serial number and
-     * return its content as a DER-encoded buffer.
-     *
-     * OpenSSL stores signed certificates in the `certs/`
-     * directory using the naming convention `<SERIAL>.pem`.
-     *
-     * @param serial - hex-encoded serial number (e.g. `"1000"`)
-     * @returns the DER buffer, or `undefined` if not found
-     */
-    getCertificateBySerial(serial: string): Buffer | undefined;
-    /**
-     * Path to the OpenSSL certificate database file.
-     */
-    get indexFile(): string;
-    /**
-     * Parse the OpenSSL `index.txt` certificate database.
-     *
-     * Each line has tab-separated fields:
-     * ```
-     * status  expiry  [revocationDate]  serial  unknown  subject
-     * ```
-     *
-     * - status: `V` (valid), `R` (revoked), `E` (expired)
-     * - expiry: `YYMMDDHHmmssZ`
-     * - revocationDate: present only for revoked certs
-     * - serial: hex string
-     * - unknown: always `"unknown"`
-     * - subject: X.500 slash-delimited string
-     */
-    private _parseIndexTxt;
-    /**
-     * Sign a DER-encoded Certificate Signing Request and return
-     * the signed certificate as a DER buffer.
-     *
-     * This method handles temp-file creation and cleanup
-     * internally so that callers can work with in-memory
-     * buffers only.
-     *
-     * The CA can override fields from the CSR by passing
-     * `options.dns`, `options.ip`, `options.applicationUri`,
-     * `options.startDate`, or `options.subject`.
-     *
-     * @param csrDer - the CSR as a DER-encoded buffer
-     * @param options - signing options and CA overrides
-     * @returns the signed certificate as a DER-encoded buffer
-     */
-    signCertificateRequestFromDER(csrDer: Buffer, options?: SignCertificateOptions): Promise<Buffer>;
-    /**
-     * Advertise the validity limits this CA can honor.
-     *
-     * Consumers (notably the GDS server in [`cert_auth.ts`](https://github.com/sterfive/node-opcua-gds))
-     * clamp a requested validity against these bounds before calling
-     * {@link signCertificateRequestFromDER}, so a misconfigured
-     * `defaultCertValidity` cannot ask the CA for something it cannot
-     * produce.
-     *
-     * Defaults match the OpenSSL-backed implementation:
-     * - `minValidityMs = 60_000` (1 minute) — practical floor; the
-     *   X.509 spec floor is 1 second but very short certs are rarely
-     *   useful and pathological for any real deployment.
-     * - `maxValidityMs = 10 * 365 * 86_400_000` (≈ 10 years) — long
-     *   enough for root CAs.
-     * - `validityGranularityMs = 1_000` (1 second) — RFC 5280 §4.1.2.5
-     *   floor on `notBefore` / `notAfter`.
-     * - `nativeUnit = "second"` — what `x509Date()` actually encodes.
-     *
-     * @see US-208 — the consumer-side capability story.
-     */
-    getCapabilities(): PkiBackendCapabilities;
-    /**
-     * Generate a new RSA key pair, create an internal CSR, sign it
-     * with this CA, and return both the certificate and private key
-     * as DER-encoded buffers.
-     *
-     * The private key is **never stored** by the CA — it exists only
-     * in a temporary directory that is cleaned up after the operation.
-     *
-     * This is used by `StartNewKeyPairRequest` (OPC UA Part 12) for
-     * constrained devices that cannot generate their own keys.
-     *
-     * @param options - key generation and certificate parameters
-     * @returns `{ certificateDer, privateKey }` — certificate as DER,
-     *   private key as a branded `PrivateKey` buffer
-     */
-    generateKeyPairAndSignDER(options: GenerateKeyPairAndSignOptions): Promise<{
-        certificateDer: Buffer;
-        privateKey: PrivateKey;
-    }>;
-    /**
-     * Generate a new RSA key pair, create an internal CSR, sign it
-     * with this CA, and return the result as a PKCS#12 (PFX)
-     * buffer bundling the certificate, private key, and CA chain.
-     *
-     * The private key is **never stored** by the CA — it exists only
-     * in a temporary directory that is cleaned up after the operation.
-     *
-     * @param options - key generation, certificate, and PFX options
-     * @returns the PFX as a `Buffer`
-     */
-    generateKeyPairAndSignPFX(options: GenerateKeyPairAndSignPFXOptions): Promise<Buffer>;
-    /**
-     * Revoke a DER-encoded certificate and regenerate the CRL.
-     *
-     * Extracts the serial number from the certificate, then
-     * uses the stored cert file at `certs/<serial>.pem` for
-     * revocation — avoiding temp-file PEM format mismatches.
-     *
-     * @param certDer - the certificate as a DER-encoded buffer
-     * @param reason - CRL reason code
-     *   (default: `"keyCompromise"`)
-     * @throws if the certificate's serial is not found in the CA
-     */
-    revokeCertificateDER(certDer: Buffer, reason?: string): Promise<void>;
-    /**
-     * Initialize the CA directory structure, generate the CA
-     * private key and self-signed certificate if they do not
-     * already exist.
-     */
-    initialize(): Promise<void>;
-    /**
-     * Initialize the CA directory structure and generate the
-     * private key + CSR **without signing**.
-     *
-     * Use this when the CA certificate will be signed by an
-     * external (third-party) root CA.  After receiving the signed
-     * certificate, call {@link installCACertificate} to complete
-     * the setup.
-     *
-     * **Idempotent / restart-safe:**
-     * - If the CA certificate exists and is valid → `{ status: "ready" }`
-     * - If the CA certificate has expired → `{ status: "expired", csrPath, expiryDate }`
-     *   (a new CSR is generated, preserving the existing private key)
-     * - If key + CSR exist but no cert (restart before install) →
-     *   `{ status: "pending", csrPath }` without regenerating
-     * - Otherwise → generates key + CSR → `{ status: "created", csrPath }`
-     *
-     * @returns an {@link InitializeCSRResult} describing the CA state
-     */
-    initializeCSR(): Promise<InitializeCSRResult>;
-    /**
-     * Check whether the CA certificate needs renewal and, if so,
-     * generate a new CSR for re-signing by the external root CA.
-     *
-     * Use this while the CA is running to detect upcoming expiry
-     * **before** it actually expires. The existing private key is
-     * preserved so previously issued certs remain valid.
-     *
-     * @param thresholdDays - number of days before expiry at which
-     *   to trigger renewal (default: 30)
-     * @returns an {@link InitializeCSRResult} — `"expired"` if
-     *   renewal is needed, `"ready"` if the cert is still valid
-     */
-    renewCSR(thresholdDays?: number): Promise<InitializeCSRResult>;
-    /**
-     * Generate a CSR using the existing private key.
      * @internal
+     * Legacy shim: publish the `CDP_URL` / `AIA_VALUE` config substitution
+     * values to the shared env registry, or unset them so the matching
+     * `{{#KEY}}...{{/KEY}}` blocks are stripped. Nothing in this package
+     * reads the registry any more - every openssl config render receives
+     * these values explicitly, from the same {@link caConfigEnvOverrides}
+     * builder this delegates to, so the two cannot drift - kept only for
+     * external code that renders openssl config templates against the
+     * registry directly.
+     *
+     * It lives on this class rather than the core because it is meaningful
+     * only to the openssl backend.
      */
-    private _generateCSR;
-    /**
-     * Install an externally-signed CA certificate and generate
-     * the initial CRL.
-     *
-     * Call this after {@link initializeCSR} once the external
-     * root CA has signed the CSR.
-     *
-     * **Safety checks:**
-     * - Verifies that the certificate's public key matches the
-     *   CA private key before installing.
-     *
-     * @param signedCertFile - path to the PEM-encoded signed
-     *   CA certificate (issued by the external root CA)
-     * @returns an {@link InstallCACertificateResult} with
-     *   `status: "success"` or `status: "error"` and a `reason`
-     */
-    installCACertificate(signedCertFile: string): Promise<InstallCACertificateResult>;
-    /**
-     * Sign a CSR with CA extensions (`v3_ca`), producing a
-     * subordinate CA certificate.
-     *
-     * Unlike {@link signCertificateRequest} which signs with
-     * end-entity extensions (SANs, etc.), this method signs
-     * with `basicConstraints = CA:TRUE` and `keyUsage =
-     * keyCertSign, cRLSign`.
-     *
-     * @param certFile - output path for the signed CA cert (PEM)
-     * @param csrFile - path to the subordinate CA's CSR
-     * @param params - signing parameters
-     */
-    signCACertificateRequest(certFile: string, csrFile: string, params: {
-        validity?: number;
-    }): Promise<void>;
-    /**
-     * Rebuild the combined CA certificate + CRL file.
-     *
-     * This concatenates the CA certificate with the current
-     * revocation list so that OpenSSL can verify certificates
-     * with CRL checking enabled.
-     */
-    constructCACertificateWithCRL(): Promise<void>;
-    /**
-     * Append the CA certificate to a signed certificate file,
-     * creating a PEM certificate chain.
-     *
-     * @param certificate - path to the certificate file to extend
-     */
-    constructCertificateChain(certificate: Filename): Promise<void>;
-    /**
-     * Create a self-signed certificate using OpenSSL.
-     *
-     * @param certificateFile - output path for the signed certificate
-     * @param privateKey - path to the private key file
-     * @param params - certificate parameters (subject, validity, SANs)
-     */
-    createSelfSignedCertificate(certificateFile: Filename, privateKey: Filename, params: Params): Promise<void>;
-    /**
-     * Revoke a certificate and regenerate the CRL.
-     *
-     * @param certificate - path to the certificate file to revoke
-     * @param params - revocation parameters
-     * @param params.reason - CRL reason code
-     *   (default `"keyCompromise"`)
-     */
-    revokeCertificate(certificate: Filename, params: Params): Promise<void>;
-    /**
-     * Sign a Certificate Signing Request (CSR) with this CA.
-     *
-     * The signed certificate is written to `certificate`, and the
-     * CA certificate chain plus CRL are appended to form a
-     * complete certificate chain.
-     *
-     * @param certificate - output path for the signed certificate
-     * @param certificateSigningRequestFilename - path to the CSR
-     * @param params1 - signing parameters (validity, dates, SANs)
-     * @returns the path to the signed certificate
-     */
-    signCertificateRequest(certificate: Filename, certificateSigningRequestFilename: Filename, params1: Params): Promise<Filename>;
-    /**
-     * Verify a certificate against this CA.
-     *
-     * @param certificate - path to the certificate file to verify
-     */
-    verifyCertificate(certificate: Filename): Promise<void>;
+    _wireRevocationEnvVars(): void;
 }
 
 /**
@@ -954,6 +239,29 @@ interface CertificateManagerOptions {
      * ignored.
      */
     privateKeyProvider?: PrivateKeyProvider;
+    /**
+     * Use a private key this manager can never read: an opaque
+     * {@link IKeyOperations} provider (HSM, KMS, TPM, OS keystore, ...).
+     *
+     * The distinction with `privateKeyProvider` matters: a
+     * `privateKeyProvider` *sources raw key material* from elsewhere and
+     * hands it back; `keyOperations` never reveals the key — only sign and
+     * decrypt operations on it. Prefer `keyOperations` whenever the key
+     * does not need to be exportable.
+     *
+     * When set:
+     * - {@link CertificateManager.getPrivateKey} and
+     *   {@link CertificateManager.reencryptPrivateKey} throw
+     *   `PrivateKeyUnavailableError` — there is no key material to return
+     *   or rewrite, and no on-disk key is generated or expected;
+     * - {@link CertificateManager.getKeyOperations} returns this object;
+     * - `initialize()` fails closed if the provider cannot answer
+     *   `getKeyMetadata()` (unreachable HSM, misconfiguration);
+     * - mutually exclusive with `privateKeyProvider` and
+     *   `privateKeyPassphrase` — both describe key *material*, which an
+     *   opaque configuration does not have.
+     */
+    keyOperations?: IKeyOperations;
 }
 /**
  * Parameters for {@link createSelfSignedCertificate}.
@@ -1248,6 +556,27 @@ declare class CertificateManager extends EventEmitter {
      * authority on what the current key is.
      */
     getPrivateKey(): Promise<PrivateKey>;
+    /**
+     * True when this manager's key is opaque — configured through
+     * `keyOperations`, held by an HSM/KMS, never obtainable as material.
+     * When true, {@link getPrivateKey} throws `PrivateKeyUnavailableError`
+     * and {@link getKeyOperations} is the only way to use the key.
+     */
+    isPrivateKeyOpaque(): boolean;
+    /**
+     * The key as an opaque {@link IKeyOperations} — the recommended way to
+     * *use* the private key regardless of where it lives.
+     *
+     * Returns the configured `keyOperations` object when the key is opaque.
+     * Otherwise returns a stable lazy wrap over {@link getPrivateKey}: its
+     * methods resolve the key on first use (disk read, passphrase,
+     * `privateKeyProvider` — all async), so the wrap offers no synchronous
+     * fast path; callers that need one resolve the key themselves and build
+     * a `LocalKeyOperations` over it. The wrap follows key rotation: a
+     * `privateKeyProvider` that starts returning a different key gets a
+     * fresh underlying `LocalKeyOperations`.
+     */
+    getKeyOperations(): IKeyOperations;
     /**
      * Enable, disable, or rotate the passphrase protecting the on-disk
      * private key: decrypt with `oldPassphrase` (omit if the key is
@@ -1569,6 +898,12 @@ interface CreatePFXOptions {
      * to include in the PFX bundle.
      */
     caCertificateFiles?: Filename[];
+    /**
+     * Optional display label stored on the bundle, the equivalent of
+     * openssl's `-name`. The Windows certificate store and `keytool` show
+     * it; {@link extractAllFromPFX} and {@link dumpPFX} report it back.
+     */
+    friendlyName?: string;
 }
 /**
  * Options for extracting data from a PFX (PKCS#12) file.
@@ -1595,67 +930,39 @@ interface ExtractPFXResult {
      * (empty string if none).
      */
     caCertificates: string;
+    /** The display label the bundle carries, if it has one. */
+    friendlyName?: string;
 }
 /**
  * Create a PFX (PKCS#12) file from a certificate and private key.
  *
- * Wraps:
- * ```
- * openssl pkcs12 -export
- *   -in <cert> -inkey <key>
- *   [-certfile <ca>]
- *   -out <pfx>
- *   -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.
+ * The bundle is protected with PBES2 / AES-256-CBC under an SHA-256 MAC. If
+ * `certificateFile` holds more than one PEM block, the first is the
+ * identity and the rest join the issuer chain, ahead of any
+ * `caCertificateFiles`.
+ *
+ * Nothing is written unless every input reads back cleanly and the private
+ * key belongs to the certificate, so a wrong `privateKeyPassphrase` or a
+ * mismatched pair leaves no half-made file behind.
  *
- * @param options — see {@link CreatePFXOptions}
+ * @param options - see {@link CreatePFXOptions}
  */
 declare function createPFX(options: CreatePFXOptions): Promise<void>;
 /**
  * Extract the client/server certificate from a PFX file.
  *
- * Wraps:
- * ```
- * openssl pkcs12 -in <pfx> -clcerts -nokeys
- *   -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.
  */
 declare function extractCertificateFromPFX(options: ExtractPFXOptions): Promise<string>;
 /**
  * Extract the private key from a PFX file.
  *
- * Wraps:
- * ```
- * openssl pkcs12 -in <pfx> -nocerts -nodes
- *   -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.
+ * @returns the private key as unencrypted PKCS#8 PEM.
  */
 declare function extractPrivateKeyFromPFX(options: ExtractPFXOptions): Promise<string>;
 /**
  * Extract the CA / intermediate certificates from a PFX file.
  *
- * Wraps:
- * ```
- * openssl pkcs12 -in <pfx> -cacerts -nokeys -nodes
- *   -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).
  */
@@ -1664,35 +971,31 @@ declare function extractCACertificatesFromPFX(options: ExtractPFXOptions): Promi
  * Extract certificate + private key + CA certs from a PFX file
  * in a single call.
  *
+ * Prefer this over the single-part helpers when you want more than one
+ * part: the file is read, decrypted and MAC-verified once here, against
+ * once per part.
+ *
  * @returns an {@link ExtractPFXResult} with all PEM-encoded parts.
  */
 declare function extractAllFromPFX(options: ExtractPFXOptions): Promise<ExtractPFXResult>;
 /**
- * Convert a PFX file to a single PEM file containing both the
- * certificate and the private key.
- *
- * Wraps:
- * ```
- * openssl pkcs12 -in <pfx> -out <pem> -nodes
- *   -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}.
+ * Convert a PFX file to a single PEM file holding the private key, the
+ * certificate, and any issuer certificates the bundle carries, in that
+ * order.
  */
 declare function convertPFXtoPEM(pfxFile: Filename, pemFile: Filename, passphrase?: string): Promise<void>;
 /**
  * Dump the contents of a PFX file in human-readable form.
  *
- * Wraps:
- * ```
- * openssl pkcs12 -in <pfx> -info -noout
- *   -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}.
+ * The layout is this package's own, not `openssl pkcs12 -info`'s: it
+ * describes the identity the bundle carries rather than the algorithms it
+ * was encrypted with, and it states outright whether the enclosed key
+ * matches the enclosed certificate - the question a bundle that will not
+ * load is usually being asked. Treat the text as something to read, not to
+ * parse; use {@link extractAllFromPFX} to get at the parts.
  *
  * @returns the human-readable dump as a string.
  */
 declare function dumpPFX(pfxFile: Filename, passphrase?: string): 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 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 };
+export { type AddCertificateValidationOptions, CaBackend, CertificateAuthority, CertificateAuthorityCore, CertificateAuthorityCoreOptions, type CertificateAuthorityOptions, CertificateManager, type CertificateManagerEvents, type CertificateManagerOptions, CertificateManagerState, type CertificateStore, type ChainCompletionResult, ChainCompletionStatus, type CreatePFXOptions, CreateSelfSignCertificateParam, type CreateSelfSignCertificateParam1, type CrlStore, type ExtractPFXOptions, type ExtractPFXResult, Filename, KeySize, OpenSslCaBackend, Params, PrivateKeyPassphrase, PrivateKeyProvider, ProcessAltNamesParam, VerificationStatus, type VerifyCertificateOptions, coerceCertificateChain, convertPFXtoPEM, createPFX, dumpPFX, extractAllFromPFX, extractCACertificatesFromPFX, extractCertificateFromPFX, extractPrivateKeyFromPFX, findIssuerCertificateInChain, install_prerequisite, isIntermediateIssuer, isIssuer, isRootIssuer, makeFingerprint };