Class CertificateBuilder

Builder class for creating X.509 certificates.

This builder provides a fluent API for constructing certificates with various options including subject, issuer, validity period, extensions, and more. It supports both self-signed and CA-signed certificates.

Example

// Create a self-signed certificate
const cert = await Certificate.builder()
    .setSubject('CN=Test Certificate, O=My Org, C=US')
    .setPublicKey(publicKey)
    .setPrivateKey(privateKey)
    .setValidityPeriod(
        new Date('2024-01-01'),
        new Date('2025-01-01')
    )
    .addExtension(basicConstraintsExt)
    .selfSign()

// Create a CA-signed certificate
const cert = await Certificate.builder()
    .setSubject('CN=User Certificate')
    .setPublicKey(userPublicKey)
    .setIssuer(caCert)
    .setIssuerPrivateKey(caPrivateKey)
    .setSerialNumber(generateSerial())
    .setValidityPeriod(notBefore, notAfter)
    .sign()

Implements

AsyncBuilder<Certificate>

Constructors

constructor

new CertificateBuilder(): CertificateBuilder
Returns CertificateBuilder

Methods

addAuthorityKeyIdentifier

addAuthorityKeyIdentifier(keyIdentifier: Uint8Array<ArrayBuffer>): this
Adds an Authority Key Identifier extension to the certificate.
Parameters
- keyIdentifier: Uint8Array<ArrayBuffer>
  The authority key identifier bytes
Returns this
This builder for chaining
- Defined in packages/pki-lite/src/core/builders/CertificateBuilder.ts:324

addBasicConstraints

addBasicConstraints(cA: boolean, pathLenConstraint?: number): this
Adds a Basic Constraints extension to the certificate.
Parameters
- cA: boolean
  Whether this is a CA certificate
- OptionalpathLenConstraint: number
  Optional path length constraint
Returns this
This builder for chaining
Example
```
// CA certificate with path length 1
builder.addBasicConstraints(true, 1)

// End-entity certificate
builder.addBasicConstraints(false)
```
- Defined in packages/pki-lite/src/core/builders/CertificateBuilder.ts:242

addExtendedKeyUsage

addExtendedKeyUsage(
    options: {
        clientAuth?: boolean;
        codeSigning?: boolean;
        emailProtection?: boolean;
        ocspSigning?: boolean;
        serverAuth?: boolean;
        timeStamping?: boolean;
    } & { [oid: string]: boolean },
): this
Adds an Extended Key Usage extension to the certificate.
Parameters
- options: {
      clientAuth?: boolean;
      codeSigning?: boolean;
      emailProtection?: boolean;
      ocspSigning?: boolean;
      serverAuth?: boolean;
      timeStamping?: boolean;
  } & { [oid: string]: boolean }
  Extended key usage purposes
Returns this
This builder for chaining
Example
```
builder.addExtendedKeyUsage({
    serverAuth: true,
    clientAuth: true
})
```
- Defined in packages/pki-lite/src/core/builders/CertificateBuilder.ts:296

addExtension

addExtension(extension: Extension): this
Adds an extension to the certificate.
Parameters
- extension: Extension
  The extension to add
Returns this
This builder for chaining
- Defined in packages/pki-lite/src/core/builders/CertificateBuilder.ts:193

addExtensions

addExtensions(...extensions: Extension[]): this
Adds multiple extensions to the certificate.
Parameters
- ...extensions: Extension[]
  Array of extensions to add
Returns this
This builder for chaining
- Defined in packages/pki-lite/src/core/builders/CertificateBuilder.ts:204

addKeyUsage

addKeyUsage(options: KeyUsageOptions): this
Adds a Key Usage extension to the certificate.
Parameters
- options: KeyUsageOptions
  Key usage flags
Returns this
This builder for chaining
Example
```
builder.addKeyUsage({
    digitalSignature: true,
    keyEncipherment: true
})
```
- Defined in packages/pki-lite/src/core/builders/CertificateBuilder.ts:222

addSubjectAltName

addSubjectAltName(...altNames: (string | GeneralName)[]): this

Adds a Subject Alternative Name extension to the certificate. Strings are automatically converted to DNS names.

Parameters

...altNames: (string | GeneralName)[]
Alternative names for the subject (strings or GeneralName objects)

Returns this

This builder for chaining

Example

// Simple DNS names as strings
builder.addSubjectAltName('example.com', '*.example.com')

// Or use GeneralName objects for other types
builder.addSubjectAltName(
    new GeneralName.dNSName({ value: 'example.com' }),
    new GeneralName.rfc822Name({ value: 'admin@example.com' })
)

// Mix strings and GeneralName objects
builder.addSubjectAltName(
    'example.com',
    new GeneralName.rfc822Name({ value: 'admin@example.com' })
)

addSubjectKeyIdentifier

addSubjectKeyIdentifier(keyIdentifier: Uint8Array<ArrayBuffer>): this
Adds a Subject Key Identifier extension to the certificate.
Parameters
- keyIdentifier: Uint8Array<ArrayBuffer>
  The key identifier bytes
Returns this
This builder for chaining
- Defined in packages/pki-lite/src/core/builders/CertificateBuilder.ts:313

build

build(): Promise<Certificate>
Alias for sign() to match the AsyncBuilder interface. Builds a CA-signed certificate, or self-signed if no issuer is set.

Returns Promise<Certificate>
Promise resolving to the signed certificate
Implementation of AsyncBuilder.build
- Defined in packages/pki-lite/src/core/builders/CertificateBuilder.ts:523

generateSerialNumber

generateSerialNumber(): this
Generates a random serial number.

Returns this
This builder for chaining
- Defined in packages/pki-lite/src/core/builders/CertificateBuilder.ts:178

selfSign

selfSign(): Promise<Certificate>
Builds and signs a self-signed certificate.

Returns Promise<Certificate>
Promise resolving to the signed certificate

Throws
Error if required fields are missing
- Defined in packages/pki-lite/src/core/builders/CertificateBuilder.ts:391

setAlgorithm

setAlgorithm(
    algorithm:
        | SignatureAlgorithmIdentifier
        | AsymmetricEncryptionAlgorithmParams,
): this
Sets the signature algorithm.
Parameters
- algorithm: SignatureAlgorithmIdentifier | AsymmetricEncryptionAlgorithmParams
  Algorithm parameters or SignatureAlgorithmIdentifier
Returns this
This builder for chaining
Example
```
// Using algorithm parameters
builder.setAlgorithm({
    type: 'ECDSA',
    params: { namedCurve: 'P-256', hash: 'SHA-256' }
})

// Or using a SignatureAlgorithmIdentifier
builder.setAlgorithm(AlgorithmIdentifier.signatureAlgorithm({
    type: 'RSA_PSS',
    params: { hash: 'SHA-512', saltLength: 64 }
}))
```
- Defined in packages/pki-lite/src/core/builders/CertificateBuilder.ts:349

setIssuer

setIssuer(issuer: string | RDNSequence | Certificate): this
Sets the issuer for the certificate. For self-signed certificates, this will be set to match the subject.
Parameters
- issuer: string | RDNSequence | Certificate
  Issuer DN as string, Name object, or Certificate
Returns this
This builder for chaining
- Defined in packages/pki-lite/src/core/builders/CertificateBuilder.ts:84

setIssuerPrivateKey

setIssuerPrivateKey(privateKey: PrivateKeyInfo): this
Sets the issuer's private key for signing (for CA-signed certificates).
Parameters
- privateKey: PrivateKeyInfo
  The issuer's private key
Returns this
This builder for chaining
- Defined in packages/pki-lite/src/core/builders/CertificateBuilder.ts:121

setPrivateKey

setPrivateKey(privateKey: PrivateKeyInfo): this
Sets the private key for signing (for self-signed certificates).
Parameters
- privateKey: PrivateKeyInfo
  The private key
Returns this
This builder for chaining
- Defined in packages/pki-lite/src/core/builders/CertificateBuilder.ts:110

setPublicKey

setPublicKey(publicKey: SubjectPublicKeyInfo): this
Sets the subject's public key.
Parameters
- publicKey: SubjectPublicKeyInfo
  The subject's public key
Returns this
This builder for chaining
- Defined in packages/pki-lite/src/core/builders/CertificateBuilder.ts:99

setSerialNumber

setSerialNumber(serialNumber: string | number | Uint8Array<ArrayBuffer>): this
Sets the serial number for the certificate.
Parameters
- serialNumber: string | number | Uint8Array<ArrayBuffer>
  Serial number as bytes, number, or string
Returns this
This builder for chaining
- Defined in packages/pki-lite/src/core/builders/CertificateBuilder.ts:157

setSubject

setSubject(subject: string | RDNSequence): this
Sets the subject distinguished name for the certificate.
Parameters
- subject: string | RDNSequence
  Subject DN as string or Name object
Returns this
This builder for chaining
- Defined in packages/pki-lite/src/core/builders/CertificateBuilder.ts:71

setValidityDays

setValidityDays(days: number): this
Sets the validity period in days from now.
Parameters
- days: number
  Number of days the certificate should be valid
Returns this
This builder for chaining
- Defined in packages/pki-lite/src/core/builders/CertificateBuilder.ts:145

setValidityPeriod

setValidityPeriod(notBefore: Date, notAfter: Date): this
Sets the validity period for the certificate.
Parameters
- notBefore: Date
  Start of validity period
- notAfter: Date
  End of validity period
Returns this
This builder for chaining
- Defined in packages/pki-lite/src/core/builders/CertificateBuilder.ts:133

setVersion

setVersion(version: number): this
Sets the certificate version.
Parameters
- version: number
  Certificate version (0 = v1, 1 = v2, 2 = v3)
Returns this
This builder for chaining
- Defined in packages/pki-lite/src/core/builders/CertificateBuilder.ts:364

sign

sign(): Promise<Certificate>
Builds and signs a certificate with the specified issuer.

Returns Promise<Certificate>
Promise resolving to the signed certificate

Throws
Error if required fields are missing
- Defined in packages/pki-lite/src/core/builders/CertificateBuilder.ts:458

Class CertificateBuilder

Example

Implements

Index

Constructors

Methods

Constructors

constructor

Returns CertificateBuilder

Methods

addAuthorityKeyIdentifier

Parameters

Returns this

addBasicConstraints

Parameters

Returns this

Example

addExtendedKeyUsage

Parameters

Returns this

Example

addExtension

Parameters

Returns this

addExtensions

Parameters

Returns this

addKeyUsage

Parameters

Returns this

Example

addSubjectAltName

Parameters

Returns this

Example

addSubjectKeyIdentifier

Parameters

Returns this

build

Returns Promise<Certificate>

generateSerialNumber

Returns this

selfSign

Returns Promise<Certificate>

Throws

setAlgorithm

Parameters

Returns this

Example

setIssuer

Parameters

Returns this

setIssuerPrivateKey

Parameters

Returns this

setPrivateKey

Parameters

Returns this

setPublicKey

Parameters

Returns this

setSerialNumber

Parameters

Returns this

setSubject

Parameters

Returns this

setValidityDays

Parameters

Returns this

setValidityPeriod

Parameters

Returns this

setVersion

Parameters

Returns this

sign

Returns Promise<Certificate>

Throws

Settings