node-opcua-pki 6.10.2 → 6.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bin/pki.mjs +505 -119
- package/dist/bin/pki.mjs.map +1 -1
- package/dist/index.d.mts +217 -8
- package/dist/index.d.ts +217 -8
- package/dist/index.js +637 -261
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +642 -263
- package/dist/index.mjs.map +1 -1
- package/package.json +2 -2
- package/readme.md +27 -163
package/dist/index.d.mts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { SubjectOptions, CertificatePurpose, Subject, Certificate, DER, CertificateRevocationList } from 'node-opcua-crypto';
|
|
1
|
+
import { SubjectOptions, CertificatePurpose, Subject, PrivateKey, Certificate, DER, CertificateRevocationList } from 'node-opcua-crypto';
|
|
2
2
|
export { Subject, SubjectOptions } from 'node-opcua-crypto';
|
|
3
3
|
import { EventEmitter } from 'node:events';
|
|
4
4
|
|
|
@@ -103,6 +103,42 @@ interface Params extends ProcessAltNamesParam, StartDateEndDateParam {
|
|
|
103
103
|
declare function adjustDate(params: StartDateEndDateParam): void;
|
|
104
104
|
declare function adjustApplicationUri(params: Params): void;
|
|
105
105
|
|
|
106
|
+
/**
|
|
107
|
+
* Result of {@link CertificateAuthority.initializeCSR}.
|
|
108
|
+
*
|
|
109
|
+
* - `"ready"` — the CA certificate already exists and is valid.
|
|
110
|
+
* - `"pending"` — key + CSR exist but no cert; waiting for external signing.
|
|
111
|
+
* - `"created"` — a fresh key + CSR were just generated.
|
|
112
|
+
* - `"expired"` — the CA certificate has expired (or will expire within
|
|
113
|
+
* the configured threshold). A new CSR has been generated for renewal
|
|
114
|
+
* while preserving the existing private key.
|
|
115
|
+
*/
|
|
116
|
+
type InitializeCSRResult = {
|
|
117
|
+
status: "ready";
|
|
118
|
+
} | {
|
|
119
|
+
status: "pending";
|
|
120
|
+
csrPath: string;
|
|
121
|
+
} | {
|
|
122
|
+
status: "created";
|
|
123
|
+
csrPath: string;
|
|
124
|
+
} | {
|
|
125
|
+
status: "expired";
|
|
126
|
+
csrPath: string;
|
|
127
|
+
expiryDate: Date;
|
|
128
|
+
};
|
|
129
|
+
/**
|
|
130
|
+
* Result of {@link CertificateAuthority.installCACertificate}.
|
|
131
|
+
*
|
|
132
|
+
* - `"success"` — the certificate was installed and CRL generated.
|
|
133
|
+
* - `"error"` — the certificate was rejected (see `reason`).
|
|
134
|
+
*/
|
|
135
|
+
type InstallCACertificateResult = {
|
|
136
|
+
status: "success";
|
|
137
|
+
} | {
|
|
138
|
+
status: "error";
|
|
139
|
+
reason: string;
|
|
140
|
+
message: string;
|
|
141
|
+
};
|
|
106
142
|
/**
|
|
107
143
|
* Options for creating a {@link CertificateAuthority}.
|
|
108
144
|
*/
|
|
@@ -119,6 +155,12 @@ interface CertificateAuthorityOptions {
|
|
|
119
155
|
* @defaultValue {@link defaultSubject}
|
|
120
156
|
*/
|
|
121
157
|
subject?: string | SubjectOptions;
|
|
158
|
+
/**
|
|
159
|
+
* Parent CA that will sign this CA's certificate.
|
|
160
|
+
* If omitted, the CA is self-signed (root CA).
|
|
161
|
+
* The parent CA must be initialized before this CA.
|
|
162
|
+
*/
|
|
163
|
+
issuerCA?: CertificateAuthority;
|
|
122
164
|
}
|
|
123
165
|
/**
|
|
124
166
|
* An OpenSSL-based Certificate Authority (CA) that can create,
|
|
@@ -167,6 +209,58 @@ interface IssuedCertificateRecord {
|
|
|
167
209
|
*/
|
|
168
210
|
revocationDate?: string;
|
|
169
211
|
}
|
|
212
|
+
/**
|
|
213
|
+
* Options for {@link CertificateAuthority.signCertificateRequestFromDER}.
|
|
214
|
+
*
|
|
215
|
+
* All fields are optional. When provided, they override the
|
|
216
|
+
* corresponding values from the CSR.
|
|
217
|
+
*/
|
|
218
|
+
interface SignCertificateOptions {
|
|
219
|
+
/** Certificate validity in days (default: 365). */
|
|
220
|
+
validity?: number;
|
|
221
|
+
/** Override the certificate start date. */
|
|
222
|
+
startDate?: Date;
|
|
223
|
+
/** Override DNS SANs. */
|
|
224
|
+
dns?: string[];
|
|
225
|
+
/** Override IP SANs. */
|
|
226
|
+
ip?: string[];
|
|
227
|
+
/** Override the application URI SAN. */
|
|
228
|
+
applicationUri?: string;
|
|
229
|
+
/** Override the X.500 subject. */
|
|
230
|
+
subject?: SubjectOptions | string;
|
|
231
|
+
}
|
|
232
|
+
/**
|
|
233
|
+
* Options for {@link CertificateAuthority.generateKeyPairAndSignDER}.
|
|
234
|
+
*/
|
|
235
|
+
interface GenerateKeyPairAndSignOptions {
|
|
236
|
+
/** OPC UA application URI (required). */
|
|
237
|
+
applicationUri: string;
|
|
238
|
+
/** X.500 subject for the certificate (e.g. "CN=MyApp"). */
|
|
239
|
+
subject?: SubjectOptions | string;
|
|
240
|
+
/** DNS host names for the SAN extension. */
|
|
241
|
+
dns?: string[];
|
|
242
|
+
/** IP addresses for the SAN extension. */
|
|
243
|
+
ip?: string[];
|
|
244
|
+
/** Certificate validity in days (default: 365). */
|
|
245
|
+
validity?: number;
|
|
246
|
+
/** Certificate start date (default: now). */
|
|
247
|
+
startDate?: Date;
|
|
248
|
+
/** RSA key size in bits (default: 2048). */
|
|
249
|
+
keySize?: KeySize;
|
|
250
|
+
}
|
|
251
|
+
/**
|
|
252
|
+
* Options for {@link CertificateAuthority.generateKeyPairAndSignPFX}.
|
|
253
|
+
*
|
|
254
|
+
* Extends the DER options with an optional `passphrase` to protect
|
|
255
|
+
* the PFX bundle.
|
|
256
|
+
*/
|
|
257
|
+
interface GenerateKeyPairAndSignPFXOptions extends GenerateKeyPairAndSignOptions {
|
|
258
|
+
/**
|
|
259
|
+
* Passphrase to protect the PFX file.
|
|
260
|
+
* If omitted, the PFX is created without a password.
|
|
261
|
+
*/
|
|
262
|
+
passphrase?: string;
|
|
263
|
+
}
|
|
170
264
|
declare class CertificateAuthority {
|
|
171
265
|
/** RSA key size used when generating the CA private key. */
|
|
172
266
|
readonly keySize: KeySize;
|
|
@@ -174,6 +268,8 @@ declare class CertificateAuthority {
|
|
|
174
268
|
readonly location: string;
|
|
175
269
|
/** X.500 subject of the CA certificate. */
|
|
176
270
|
readonly subject: Subject;
|
|
271
|
+
/** @internal Parent CA (undefined for root CAs). */
|
|
272
|
+
readonly _issuerCA?: CertificateAuthority;
|
|
177
273
|
constructor(options: CertificateAuthorityOptions);
|
|
178
274
|
/** Absolute path to the CA root directory (alias for {@link location}). */
|
|
179
275
|
get rootDir(): string;
|
|
@@ -181,6 +277,16 @@ declare class CertificateAuthority {
|
|
|
181
277
|
get configFile(): string;
|
|
182
278
|
/** Path to the CA certificate in PEM format (`public/cacert.pem`). */
|
|
183
279
|
get caCertificate(): string;
|
|
280
|
+
/**
|
|
281
|
+
* Path to the issuer certificate chain (`public/issuer_chain.pem`).
|
|
282
|
+
*
|
|
283
|
+
* This file is created by {@link installCACertificate} when the
|
|
284
|
+
* provided cert file contains additional issuer certificates
|
|
285
|
+
* (e.g. intermediate + root). It is appended to signed certs
|
|
286
|
+
* by {@link constructCertificateChain} to produce a full chain
|
|
287
|
+
* per OPC UA Part 6 §6.2.6.
|
|
288
|
+
*/
|
|
289
|
+
get issuerCertificateChain(): string;
|
|
184
290
|
/**
|
|
185
291
|
* Path to the current Certificate Revocation List in DER format.
|
|
186
292
|
* (`crl/revocation_list.der`)
|
|
@@ -284,15 +390,46 @@ declare class CertificateAuthority {
|
|
|
284
390
|
* internally so that callers can work with in-memory
|
|
285
391
|
* buffers only.
|
|
286
392
|
*
|
|
393
|
+
* The CA can override fields from the CSR by passing
|
|
394
|
+
* `options.dns`, `options.ip`, `options.applicationUri`,
|
|
395
|
+
* `options.startDate`, or `options.subject`.
|
|
396
|
+
*
|
|
287
397
|
* @param csrDer - the CSR as a DER-encoded buffer
|
|
288
|
-
* @param options - signing options
|
|
289
|
-
* @param options.validity - certificate validity in days
|
|
290
|
-
* (default: 365)
|
|
398
|
+
* @param options - signing options and CA overrides
|
|
291
399
|
* @returns the signed certificate as a DER-encoded buffer
|
|
292
400
|
*/
|
|
293
|
-
signCertificateRequestFromDER(csrDer: Buffer, options?:
|
|
294
|
-
|
|
295
|
-
|
|
401
|
+
signCertificateRequestFromDER(csrDer: Buffer, options?: SignCertificateOptions): Promise<Buffer>;
|
|
402
|
+
/**
|
|
403
|
+
* Generate a new RSA key pair, create an internal CSR, sign it
|
|
404
|
+
* with this CA, and return both the certificate and private key
|
|
405
|
+
* as DER-encoded buffers.
|
|
406
|
+
*
|
|
407
|
+
* The private key is **never stored** by the CA — it exists only
|
|
408
|
+
* in a temporary directory that is cleaned up after the operation.
|
|
409
|
+
*
|
|
410
|
+
* This is used by `StartNewKeyPairRequest` (OPC UA Part 12) for
|
|
411
|
+
* constrained devices that cannot generate their own keys.
|
|
412
|
+
*
|
|
413
|
+
* @param options - key generation and certificate parameters
|
|
414
|
+
* @returns `{ certificateDer, privateKey }` — certificate as DER,
|
|
415
|
+
* private key as a branded `PrivateKey` buffer
|
|
416
|
+
*/
|
|
417
|
+
generateKeyPairAndSignDER(options: GenerateKeyPairAndSignOptions): Promise<{
|
|
418
|
+
certificateDer: Buffer;
|
|
419
|
+
privateKey: PrivateKey;
|
|
420
|
+
}>;
|
|
421
|
+
/**
|
|
422
|
+
* Generate a new RSA key pair, create an internal CSR, sign it
|
|
423
|
+
* with this CA, and return the result as a PKCS#12 (PFX)
|
|
424
|
+
* buffer bundling the certificate, private key, and CA chain.
|
|
425
|
+
*
|
|
426
|
+
* The private key is **never stored** by the CA — it exists only
|
|
427
|
+
* in a temporary directory that is cleaned up after the operation.
|
|
428
|
+
*
|
|
429
|
+
* @param options - key generation, certificate, and PFX options
|
|
430
|
+
* @returns the PFX as a `Buffer`
|
|
431
|
+
*/
|
|
432
|
+
generateKeyPairAndSignPFX(options: GenerateKeyPairAndSignPFXOptions): Promise<Buffer>;
|
|
296
433
|
/**
|
|
297
434
|
* Revoke a DER-encoded certificate and regenerate the CRL.
|
|
298
435
|
*
|
|
@@ -312,6 +449,78 @@ declare class CertificateAuthority {
|
|
|
312
449
|
* already exist.
|
|
313
450
|
*/
|
|
314
451
|
initialize(): Promise<void>;
|
|
452
|
+
/**
|
|
453
|
+
* Initialize the CA directory structure and generate the
|
|
454
|
+
* private key + CSR **without signing**.
|
|
455
|
+
*
|
|
456
|
+
* Use this when the CA certificate will be signed by an
|
|
457
|
+
* external (third-party) root CA. After receiving the signed
|
|
458
|
+
* certificate, call {@link installCACertificate} to complete
|
|
459
|
+
* the setup.
|
|
460
|
+
*
|
|
461
|
+
* **Idempotent / restart-safe:**
|
|
462
|
+
* - If the CA certificate exists and is valid → `{ status: "ready" }`
|
|
463
|
+
* - If the CA certificate has expired → `{ status: "expired", csrPath, expiryDate }`
|
|
464
|
+
* (a new CSR is generated, preserving the existing private key)
|
|
465
|
+
* - If key + CSR exist but no cert (restart before install) →
|
|
466
|
+
* `{ status: "pending", csrPath }` without regenerating
|
|
467
|
+
* - Otherwise → generates key + CSR → `{ status: "created", csrPath }`
|
|
468
|
+
*
|
|
469
|
+
* @returns an {@link InitializeCSRResult} describing the CA state
|
|
470
|
+
*/
|
|
471
|
+
initializeCSR(): Promise<InitializeCSRResult>;
|
|
472
|
+
/**
|
|
473
|
+
* Check whether the CA certificate needs renewal and, if so,
|
|
474
|
+
* generate a new CSR for re-signing by the external root CA.
|
|
475
|
+
*
|
|
476
|
+
* Use this while the CA is running to detect upcoming expiry
|
|
477
|
+
* **before** it actually expires. The existing private key is
|
|
478
|
+
* preserved so previously issued certs remain valid.
|
|
479
|
+
*
|
|
480
|
+
* @param thresholdDays - number of days before expiry at which
|
|
481
|
+
* to trigger renewal (default: 30)
|
|
482
|
+
* @returns an {@link InitializeCSRResult} — `"expired"` if
|
|
483
|
+
* renewal is needed, `"ready"` if the cert is still valid
|
|
484
|
+
*/
|
|
485
|
+
renewCSR(thresholdDays?: number): Promise<InitializeCSRResult>;
|
|
486
|
+
/**
|
|
487
|
+
* Generate a CSR using the existing private key.
|
|
488
|
+
* @internal
|
|
489
|
+
*/
|
|
490
|
+
private _generateCSR;
|
|
491
|
+
/**
|
|
492
|
+
* Install an externally-signed CA certificate and generate
|
|
493
|
+
* the initial CRL.
|
|
494
|
+
*
|
|
495
|
+
* Call this after {@link initializeCSR} once the external
|
|
496
|
+
* root CA has signed the CSR.
|
|
497
|
+
*
|
|
498
|
+
* **Safety checks:**
|
|
499
|
+
* - Verifies that the certificate's public key matches the
|
|
500
|
+
* CA private key before installing.
|
|
501
|
+
*
|
|
502
|
+
* @param signedCertFile - path to the PEM-encoded signed
|
|
503
|
+
* CA certificate (issued by the external root CA)
|
|
504
|
+
* @returns an {@link InstallCACertificateResult} with
|
|
505
|
+
* `status: "success"` or `status: "error"` and a `reason`
|
|
506
|
+
*/
|
|
507
|
+
installCACertificate(signedCertFile: string): Promise<InstallCACertificateResult>;
|
|
508
|
+
/**
|
|
509
|
+
* Sign a CSR with CA extensions (`v3_ca`), producing a
|
|
510
|
+
* subordinate CA certificate.
|
|
511
|
+
*
|
|
512
|
+
* Unlike {@link signCertificateRequest} which signs with
|
|
513
|
+
* end-entity extensions (SANs, etc.), this method signs
|
|
514
|
+
* with `basicConstraints = CA:TRUE` and `keyUsage =
|
|
515
|
+
* keyCertSign, cRLSign`.
|
|
516
|
+
*
|
|
517
|
+
* @param certFile - output path for the signed CA cert (PEM)
|
|
518
|
+
* @param csrFile - path to the subordinate CA's CSR
|
|
519
|
+
* @param params - signing parameters
|
|
520
|
+
*/
|
|
521
|
+
signCACertificateRequest(certFile: string, csrFile: string, params: {
|
|
522
|
+
validity?: number;
|
|
523
|
+
}): Promise<void>;
|
|
315
524
|
/**
|
|
316
525
|
* Rebuild the combined CA certificate + CRL file.
|
|
317
526
|
*
|
|
@@ -1014,4 +1223,4 @@ declare function dumpPFX(pfxFile: Filename, passphrase?: string): Promise<string
|
|
|
1014
1223
|
*/
|
|
1015
1224
|
declare function install_prerequisite(): Promise<string>;
|
|
1016
1225
|
|
|
1017
|
-
export { CertificateAuthority, type CertificateAuthorityOptions, CertificateManager, type CertificateManagerEvents, type CertificateManagerOptions, CertificateManagerState, type CertificateStatus, type CertificateStore, type CreateCertificateSigningRequestOptions, type CreateCertificateSigningRequestWithConfigOptions, type CreatePFXOptions, type CreateSelfSignCertificateParam, type CreateSelfSignCertificateParam1, type CreateSelfSignCertificateWithConfigParam, type CrlStore, type ExtractPFXOptions, type ExtractPFXResult, type Filename, type KeyLength, type KeySize, type Params, type ProcessAltNamesParam, type StartDateEndDateParam, type Thumbprint, VerificationStatus, type VerifyCertificateOptions, adjustApplicationUri, adjustDate, convertPFXtoPEM, createPFX, dumpPFX, extractAllFromPFX, extractCACertificatesFromPFX, extractCertificateFromPFX, extractPrivateKeyFromPFX, findIssuerCertificateInChain, install_prerequisite, quote };
|
|
1226
|
+
export { CertificateAuthority, type CertificateAuthorityOptions, CertificateManager, type CertificateManagerEvents, type CertificateManagerOptions, CertificateManagerState, type CertificateStatus, type CertificateStore, 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 ProcessAltNamesParam, type SignCertificateOptions, type StartDateEndDateParam, type Thumbprint, VerificationStatus, type VerifyCertificateOptions, adjustApplicationUri, adjustDate, convertPFXtoPEM, createPFX, dumpPFX, extractAllFromPFX, extractCACertificatesFromPFX, extractCertificateFromPFX, extractPrivateKeyFromPFX, findIssuerCertificateInChain, install_prerequisite, quote };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { SubjectOptions, CertificatePurpose, Subject, Certificate, DER, CertificateRevocationList } from 'node-opcua-crypto';
|
|
1
|
+
import { SubjectOptions, CertificatePurpose, Subject, PrivateKey, Certificate, DER, CertificateRevocationList } from 'node-opcua-crypto';
|
|
2
2
|
export { Subject, SubjectOptions } from 'node-opcua-crypto';
|
|
3
3
|
import { EventEmitter } from 'node:events';
|
|
4
4
|
|
|
@@ -103,6 +103,42 @@ interface Params extends ProcessAltNamesParam, StartDateEndDateParam {
|
|
|
103
103
|
declare function adjustDate(params: StartDateEndDateParam): void;
|
|
104
104
|
declare function adjustApplicationUri(params: Params): void;
|
|
105
105
|
|
|
106
|
+
/**
|
|
107
|
+
* Result of {@link CertificateAuthority.initializeCSR}.
|
|
108
|
+
*
|
|
109
|
+
* - `"ready"` — the CA certificate already exists and is valid.
|
|
110
|
+
* - `"pending"` — key + CSR exist but no cert; waiting for external signing.
|
|
111
|
+
* - `"created"` — a fresh key + CSR were just generated.
|
|
112
|
+
* - `"expired"` — the CA certificate has expired (or will expire within
|
|
113
|
+
* the configured threshold). A new CSR has been generated for renewal
|
|
114
|
+
* while preserving the existing private key.
|
|
115
|
+
*/
|
|
116
|
+
type InitializeCSRResult = {
|
|
117
|
+
status: "ready";
|
|
118
|
+
} | {
|
|
119
|
+
status: "pending";
|
|
120
|
+
csrPath: string;
|
|
121
|
+
} | {
|
|
122
|
+
status: "created";
|
|
123
|
+
csrPath: string;
|
|
124
|
+
} | {
|
|
125
|
+
status: "expired";
|
|
126
|
+
csrPath: string;
|
|
127
|
+
expiryDate: Date;
|
|
128
|
+
};
|
|
129
|
+
/**
|
|
130
|
+
* Result of {@link CertificateAuthority.installCACertificate}.
|
|
131
|
+
*
|
|
132
|
+
* - `"success"` — the certificate was installed and CRL generated.
|
|
133
|
+
* - `"error"` — the certificate was rejected (see `reason`).
|
|
134
|
+
*/
|
|
135
|
+
type InstallCACertificateResult = {
|
|
136
|
+
status: "success";
|
|
137
|
+
} | {
|
|
138
|
+
status: "error";
|
|
139
|
+
reason: string;
|
|
140
|
+
message: string;
|
|
141
|
+
};
|
|
106
142
|
/**
|
|
107
143
|
* Options for creating a {@link CertificateAuthority}.
|
|
108
144
|
*/
|
|
@@ -119,6 +155,12 @@ interface CertificateAuthorityOptions {
|
|
|
119
155
|
* @defaultValue {@link defaultSubject}
|
|
120
156
|
*/
|
|
121
157
|
subject?: string | SubjectOptions;
|
|
158
|
+
/**
|
|
159
|
+
* Parent CA that will sign this CA's certificate.
|
|
160
|
+
* If omitted, the CA is self-signed (root CA).
|
|
161
|
+
* The parent CA must be initialized before this CA.
|
|
162
|
+
*/
|
|
163
|
+
issuerCA?: CertificateAuthority;
|
|
122
164
|
}
|
|
123
165
|
/**
|
|
124
166
|
* An OpenSSL-based Certificate Authority (CA) that can create,
|
|
@@ -167,6 +209,58 @@ interface IssuedCertificateRecord {
|
|
|
167
209
|
*/
|
|
168
210
|
revocationDate?: string;
|
|
169
211
|
}
|
|
212
|
+
/**
|
|
213
|
+
* Options for {@link CertificateAuthority.signCertificateRequestFromDER}.
|
|
214
|
+
*
|
|
215
|
+
* All fields are optional. When provided, they override the
|
|
216
|
+
* corresponding values from the CSR.
|
|
217
|
+
*/
|
|
218
|
+
interface SignCertificateOptions {
|
|
219
|
+
/** Certificate validity in days (default: 365). */
|
|
220
|
+
validity?: number;
|
|
221
|
+
/** Override the certificate start date. */
|
|
222
|
+
startDate?: Date;
|
|
223
|
+
/** Override DNS SANs. */
|
|
224
|
+
dns?: string[];
|
|
225
|
+
/** Override IP SANs. */
|
|
226
|
+
ip?: string[];
|
|
227
|
+
/** Override the application URI SAN. */
|
|
228
|
+
applicationUri?: string;
|
|
229
|
+
/** Override the X.500 subject. */
|
|
230
|
+
subject?: SubjectOptions | string;
|
|
231
|
+
}
|
|
232
|
+
/**
|
|
233
|
+
* Options for {@link CertificateAuthority.generateKeyPairAndSignDER}.
|
|
234
|
+
*/
|
|
235
|
+
interface GenerateKeyPairAndSignOptions {
|
|
236
|
+
/** OPC UA application URI (required). */
|
|
237
|
+
applicationUri: string;
|
|
238
|
+
/** X.500 subject for the certificate (e.g. "CN=MyApp"). */
|
|
239
|
+
subject?: SubjectOptions | string;
|
|
240
|
+
/** DNS host names for the SAN extension. */
|
|
241
|
+
dns?: string[];
|
|
242
|
+
/** IP addresses for the SAN extension. */
|
|
243
|
+
ip?: string[];
|
|
244
|
+
/** Certificate validity in days (default: 365). */
|
|
245
|
+
validity?: number;
|
|
246
|
+
/** Certificate start date (default: now). */
|
|
247
|
+
startDate?: Date;
|
|
248
|
+
/** RSA key size in bits (default: 2048). */
|
|
249
|
+
keySize?: KeySize;
|
|
250
|
+
}
|
|
251
|
+
/**
|
|
252
|
+
* Options for {@link CertificateAuthority.generateKeyPairAndSignPFX}.
|
|
253
|
+
*
|
|
254
|
+
* Extends the DER options with an optional `passphrase` to protect
|
|
255
|
+
* the PFX bundle.
|
|
256
|
+
*/
|
|
257
|
+
interface GenerateKeyPairAndSignPFXOptions extends GenerateKeyPairAndSignOptions {
|
|
258
|
+
/**
|
|
259
|
+
* Passphrase to protect the PFX file.
|
|
260
|
+
* If omitted, the PFX is created without a password.
|
|
261
|
+
*/
|
|
262
|
+
passphrase?: string;
|
|
263
|
+
}
|
|
170
264
|
declare class CertificateAuthority {
|
|
171
265
|
/** RSA key size used when generating the CA private key. */
|
|
172
266
|
readonly keySize: KeySize;
|
|
@@ -174,6 +268,8 @@ declare class CertificateAuthority {
|
|
|
174
268
|
readonly location: string;
|
|
175
269
|
/** X.500 subject of the CA certificate. */
|
|
176
270
|
readonly subject: Subject;
|
|
271
|
+
/** @internal Parent CA (undefined for root CAs). */
|
|
272
|
+
readonly _issuerCA?: CertificateAuthority;
|
|
177
273
|
constructor(options: CertificateAuthorityOptions);
|
|
178
274
|
/** Absolute path to the CA root directory (alias for {@link location}). */
|
|
179
275
|
get rootDir(): string;
|
|
@@ -181,6 +277,16 @@ declare class CertificateAuthority {
|
|
|
181
277
|
get configFile(): string;
|
|
182
278
|
/** Path to the CA certificate in PEM format (`public/cacert.pem`). */
|
|
183
279
|
get caCertificate(): string;
|
|
280
|
+
/**
|
|
281
|
+
* Path to the issuer certificate chain (`public/issuer_chain.pem`).
|
|
282
|
+
*
|
|
283
|
+
* This file is created by {@link installCACertificate} when the
|
|
284
|
+
* provided cert file contains additional issuer certificates
|
|
285
|
+
* (e.g. intermediate + root). It is appended to signed certs
|
|
286
|
+
* by {@link constructCertificateChain} to produce a full chain
|
|
287
|
+
* per OPC UA Part 6 §6.2.6.
|
|
288
|
+
*/
|
|
289
|
+
get issuerCertificateChain(): string;
|
|
184
290
|
/**
|
|
185
291
|
* Path to the current Certificate Revocation List in DER format.
|
|
186
292
|
* (`crl/revocation_list.der`)
|
|
@@ -284,15 +390,46 @@ declare class CertificateAuthority {
|
|
|
284
390
|
* internally so that callers can work with in-memory
|
|
285
391
|
* buffers only.
|
|
286
392
|
*
|
|
393
|
+
* The CA can override fields from the CSR by passing
|
|
394
|
+
* `options.dns`, `options.ip`, `options.applicationUri`,
|
|
395
|
+
* `options.startDate`, or `options.subject`.
|
|
396
|
+
*
|
|
287
397
|
* @param csrDer - the CSR as a DER-encoded buffer
|
|
288
|
-
* @param options - signing options
|
|
289
|
-
* @param options.validity - certificate validity in days
|
|
290
|
-
* (default: 365)
|
|
398
|
+
* @param options - signing options and CA overrides
|
|
291
399
|
* @returns the signed certificate as a DER-encoded buffer
|
|
292
400
|
*/
|
|
293
|
-
signCertificateRequestFromDER(csrDer: Buffer, options?:
|
|
294
|
-
|
|
295
|
-
|
|
401
|
+
signCertificateRequestFromDER(csrDer: Buffer, options?: SignCertificateOptions): Promise<Buffer>;
|
|
402
|
+
/**
|
|
403
|
+
* Generate a new RSA key pair, create an internal CSR, sign it
|
|
404
|
+
* with this CA, and return both the certificate and private key
|
|
405
|
+
* as DER-encoded buffers.
|
|
406
|
+
*
|
|
407
|
+
* The private key is **never stored** by the CA — it exists only
|
|
408
|
+
* in a temporary directory that is cleaned up after the operation.
|
|
409
|
+
*
|
|
410
|
+
* This is used by `StartNewKeyPairRequest` (OPC UA Part 12) for
|
|
411
|
+
* constrained devices that cannot generate their own keys.
|
|
412
|
+
*
|
|
413
|
+
* @param options - key generation and certificate parameters
|
|
414
|
+
* @returns `{ certificateDer, privateKey }` — certificate as DER,
|
|
415
|
+
* private key as a branded `PrivateKey` buffer
|
|
416
|
+
*/
|
|
417
|
+
generateKeyPairAndSignDER(options: GenerateKeyPairAndSignOptions): Promise<{
|
|
418
|
+
certificateDer: Buffer;
|
|
419
|
+
privateKey: PrivateKey;
|
|
420
|
+
}>;
|
|
421
|
+
/**
|
|
422
|
+
* Generate a new RSA key pair, create an internal CSR, sign it
|
|
423
|
+
* with this CA, and return the result as a PKCS#12 (PFX)
|
|
424
|
+
* buffer bundling the certificate, private key, and CA chain.
|
|
425
|
+
*
|
|
426
|
+
* The private key is **never stored** by the CA — it exists only
|
|
427
|
+
* in a temporary directory that is cleaned up after the operation.
|
|
428
|
+
*
|
|
429
|
+
* @param options - key generation, certificate, and PFX options
|
|
430
|
+
* @returns the PFX as a `Buffer`
|
|
431
|
+
*/
|
|
432
|
+
generateKeyPairAndSignPFX(options: GenerateKeyPairAndSignPFXOptions): Promise<Buffer>;
|
|
296
433
|
/**
|
|
297
434
|
* Revoke a DER-encoded certificate and regenerate the CRL.
|
|
298
435
|
*
|
|
@@ -312,6 +449,78 @@ declare class CertificateAuthority {
|
|
|
312
449
|
* already exist.
|
|
313
450
|
*/
|
|
314
451
|
initialize(): Promise<void>;
|
|
452
|
+
/**
|
|
453
|
+
* Initialize the CA directory structure and generate the
|
|
454
|
+
* private key + CSR **without signing**.
|
|
455
|
+
*
|
|
456
|
+
* Use this when the CA certificate will be signed by an
|
|
457
|
+
* external (third-party) root CA. After receiving the signed
|
|
458
|
+
* certificate, call {@link installCACertificate} to complete
|
|
459
|
+
* the setup.
|
|
460
|
+
*
|
|
461
|
+
* **Idempotent / restart-safe:**
|
|
462
|
+
* - If the CA certificate exists and is valid → `{ status: "ready" }`
|
|
463
|
+
* - If the CA certificate has expired → `{ status: "expired", csrPath, expiryDate }`
|
|
464
|
+
* (a new CSR is generated, preserving the existing private key)
|
|
465
|
+
* - If key + CSR exist but no cert (restart before install) →
|
|
466
|
+
* `{ status: "pending", csrPath }` without regenerating
|
|
467
|
+
* - Otherwise → generates key + CSR → `{ status: "created", csrPath }`
|
|
468
|
+
*
|
|
469
|
+
* @returns an {@link InitializeCSRResult} describing the CA state
|
|
470
|
+
*/
|
|
471
|
+
initializeCSR(): Promise<InitializeCSRResult>;
|
|
472
|
+
/**
|
|
473
|
+
* Check whether the CA certificate needs renewal and, if so,
|
|
474
|
+
* generate a new CSR for re-signing by the external root CA.
|
|
475
|
+
*
|
|
476
|
+
* Use this while the CA is running to detect upcoming expiry
|
|
477
|
+
* **before** it actually expires. The existing private key is
|
|
478
|
+
* preserved so previously issued certs remain valid.
|
|
479
|
+
*
|
|
480
|
+
* @param thresholdDays - number of days before expiry at which
|
|
481
|
+
* to trigger renewal (default: 30)
|
|
482
|
+
* @returns an {@link InitializeCSRResult} — `"expired"` if
|
|
483
|
+
* renewal is needed, `"ready"` if the cert is still valid
|
|
484
|
+
*/
|
|
485
|
+
renewCSR(thresholdDays?: number): Promise<InitializeCSRResult>;
|
|
486
|
+
/**
|
|
487
|
+
* Generate a CSR using the existing private key.
|
|
488
|
+
* @internal
|
|
489
|
+
*/
|
|
490
|
+
private _generateCSR;
|
|
491
|
+
/**
|
|
492
|
+
* Install an externally-signed CA certificate and generate
|
|
493
|
+
* the initial CRL.
|
|
494
|
+
*
|
|
495
|
+
* Call this after {@link initializeCSR} once the external
|
|
496
|
+
* root CA has signed the CSR.
|
|
497
|
+
*
|
|
498
|
+
* **Safety checks:**
|
|
499
|
+
* - Verifies that the certificate's public key matches the
|
|
500
|
+
* CA private key before installing.
|
|
501
|
+
*
|
|
502
|
+
* @param signedCertFile - path to the PEM-encoded signed
|
|
503
|
+
* CA certificate (issued by the external root CA)
|
|
504
|
+
* @returns an {@link InstallCACertificateResult} with
|
|
505
|
+
* `status: "success"` or `status: "error"` and a `reason`
|
|
506
|
+
*/
|
|
507
|
+
installCACertificate(signedCertFile: string): Promise<InstallCACertificateResult>;
|
|
508
|
+
/**
|
|
509
|
+
* Sign a CSR with CA extensions (`v3_ca`), producing a
|
|
510
|
+
* subordinate CA certificate.
|
|
511
|
+
*
|
|
512
|
+
* Unlike {@link signCertificateRequest} which signs with
|
|
513
|
+
* end-entity extensions (SANs, etc.), this method signs
|
|
514
|
+
* with `basicConstraints = CA:TRUE` and `keyUsage =
|
|
515
|
+
* keyCertSign, cRLSign`.
|
|
516
|
+
*
|
|
517
|
+
* @param certFile - output path for the signed CA cert (PEM)
|
|
518
|
+
* @param csrFile - path to the subordinate CA's CSR
|
|
519
|
+
* @param params - signing parameters
|
|
520
|
+
*/
|
|
521
|
+
signCACertificateRequest(certFile: string, csrFile: string, params: {
|
|
522
|
+
validity?: number;
|
|
523
|
+
}): Promise<void>;
|
|
315
524
|
/**
|
|
316
525
|
* Rebuild the combined CA certificate + CRL file.
|
|
317
526
|
*
|
|
@@ -1014,4 +1223,4 @@ declare function dumpPFX(pfxFile: Filename, passphrase?: string): Promise<string
|
|
|
1014
1223
|
*/
|
|
1015
1224
|
declare function install_prerequisite(): Promise<string>;
|
|
1016
1225
|
|
|
1017
|
-
export { CertificateAuthority, type CertificateAuthorityOptions, CertificateManager, type CertificateManagerEvents, type CertificateManagerOptions, CertificateManagerState, type CertificateStatus, type CertificateStore, type CreateCertificateSigningRequestOptions, type CreateCertificateSigningRequestWithConfigOptions, type CreatePFXOptions, type CreateSelfSignCertificateParam, type CreateSelfSignCertificateParam1, type CreateSelfSignCertificateWithConfigParam, type CrlStore, type ExtractPFXOptions, type ExtractPFXResult, type Filename, type KeyLength, type KeySize, type Params, type ProcessAltNamesParam, type StartDateEndDateParam, type Thumbprint, VerificationStatus, type VerifyCertificateOptions, adjustApplicationUri, adjustDate, convertPFXtoPEM, createPFX, dumpPFX, extractAllFromPFX, extractCACertificatesFromPFX, extractCertificateFromPFX, extractPrivateKeyFromPFX, findIssuerCertificateInChain, install_prerequisite, quote };
|
|
1226
|
+
export { CertificateAuthority, type CertificateAuthorityOptions, CertificateManager, type CertificateManagerEvents, type CertificateManagerOptions, CertificateManagerState, type CertificateStatus, type CertificateStore, 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 ProcessAltNamesParam, type SignCertificateOptions, type StartDateEndDateParam, type Thumbprint, VerificationStatus, type VerifyCertificateOptions, adjustApplicationUri, adjustDate, convertPFXtoPEM, createPFX, dumpPFX, extractAllFromPFX, extractCACertificatesFromPFX, extractCertificateFromPFX, extractPrivateKeyFromPFX, findIssuerCertificateInChain, install_prerequisite, quote };
|