forge.md

May 22, 2024 · View on GitHub

Objects

forge : object

Legacy node-forge crypto interface

DEPRECATION WARNING: This crypto interface is deprecated and will be removed from acme-client in a future major release. Please migrate to the new acme.crypto interface at your earliest convenience.

Functions

createPrivateKey([size]) ⇒ Promise.<buffer>: Generate a private RSA key
createPublicKey(key) ⇒ Promise.<buffer>: Create public key from a private RSA key
getPemBody(str) ⇒ string: Parse body of PEM encoded object from buffer or string If multiple objects are chained, the first body will be returned
splitPemChain(str) ⇒ Array.<string>: Split chain of PEM encoded objects from buffer or string into array
getModulus(input) ⇒ Promise.<buffer>: Get modulus
getPublicExponent(input) ⇒ Promise.<buffer>: Get public exponent
readCsrDomains(csr) ⇒ Promise.<object>: Read domains from a Certificate Signing Request
readCertificateInfo(cert) ⇒ Promise.<object>: Read information from a certificate
createCsr(data, [key]) ⇒ Promise.<Array.<buffer>>: Create a Certificate Signing Request

forge : `object`

Legacy node-forge crypto interface

Kind: global namespace

createPrivateKey([size]) ⇒ `Promise.<buffer>`

Generate a private RSA key

Kind: global function
Returns: Promise.<buffer> - PEM encoded private RSA key

Param	Type	Default	Description
[size]	`number`	`2048`	Size of the key, default: `2048`

Example
Generate private RSA key

const privateKey = await acme.forge.createPrivateKey();

Example
Private RSA key with defined size

const privateKey = await acme.forge.createPrivateKey(4096);

createPublicKey(key) ⇒ `Promise.<buffer>`

Create public key from a private RSA key

Kind: global function
Returns: Promise.<buffer> - PEM encoded public RSA key

Param	Type	Description
key	`buffer` \| `string`	PEM encoded private RSA key

Example
Create public key

const publicKey = await acme.forge.createPublicKey(privateKey);

getPemBody(str) ⇒ `string`

Parse body of PEM encoded object from buffer or string If multiple objects are chained, the first body will be returned

Kind: global function
Returns: string - PEM body

Param	Type	Description
str	`buffer` \| `string`	PEM encoded buffer or string

splitPemChain(str) ⇒ `Array.<string>`

Split chain of PEM encoded objects from buffer or string into array

Kind: global function
Returns: Array.<string> - Array of PEM bodies

Param	Type	Description
str	`buffer` \| `string`	PEM encoded buffer or string

getModulus(input) ⇒ `Promise.<buffer>`

Get modulus

Kind: global function
Returns: Promise.<buffer> - Modulus

Param	Type	Description
input	`buffer` \| `string`	PEM encoded private key, certificate or CSR

Example
Get modulus

const m1 = await acme.forge.getModulus(privateKey);
const m2 = await acme.forge.getModulus(certificate);
const m3 = await acme.forge.getModulus(certificateRequest);

getPublicExponent(input) ⇒ `Promise.<buffer>`

Get public exponent

Kind: global function
Returns: Promise.<buffer> - Exponent

Param	Type	Description
input	`buffer` \| `string`	PEM encoded private key, certificate or CSR

Example
Get public exponent

const e1 = await acme.forge.getPublicExponent(privateKey);
const e2 = await acme.forge.getPublicExponent(certificate);
const e3 = await acme.forge.getPublicExponent(certificateRequest);

readCsrDomains(csr) ⇒ `Promise.<object>`

Read domains from a Certificate Signing Request

Kind: global function
Returns: Promise.<object> - {commonName, altNames}

Param	Type	Description
csr	`buffer` \| `string`	PEM encoded Certificate Signing Request

Example
Read Certificate Signing Request domains

const { commonName, altNames } = await acme.forge.readCsrDomains(certificateRequest);

console.log(`Common name: ${commonName}`);
console.log(`Alt names: ${altNames.join(', ')}`);

readCertificateInfo(cert) ⇒ `Promise.<object>`

Read information from a certificate

Kind: global function
Returns: Promise.<object> - Certificate info

Param	Type	Description
cert	`buffer` \| `string`	PEM encoded certificate

Example
Read certificate information

const info = await acme.forge.readCertificateInfo(certificate);
const { commonName, altNames } = info.domains;

console.log(`Not after: ${info.notAfter}`);
console.log(`Not before: ${info.notBefore}`);

console.log(`Common name: ${commonName}`);
console.log(`Alt names: ${altNames.join(', ')}`);

createCsr(data, [key]) ⇒ `Promise.<Array.<buffer>>`

Create a Certificate Signing Request

Kind: global function
Returns: Promise.<Array.<buffer>> - [privateKey, certificateSigningRequest]

Param	Type	Description
data	`object`
[data.keySize]	`number`	Size of newly created private key, default: `2048`
[data.commonName]	`string`
[data.altNames]	`Array.<string>`	default: `[]`
[data.country]	`string`
[data.state]	`string`
[data.locality]	`string`
[data.organization]	`string`
[data.organizationUnit]	`string`
[data.emailAddress]	`string`
[key]	`buffer` \| `string`	CSR private key

Example
Create a Certificate Signing Request

const [certificateKey, certificateRequest] = await acme.forge.createCsr({
    altNames: ['test.example.com'],
});

Example
Certificate Signing Request with both common and alternative names

Warning: Certificate subject common name has been deprecated and its use is discouraged.

const [certificateKey, certificateRequest] = await acme.forge.createCsr({
    keySize: 4096,
    commonName: 'test.example.com',
    altNames: ['foo.example.com', 'bar.example.com'],
});

Example
Certificate Signing Request with additional information

const [certificateKey, certificateRequest] = await acme.forge.createCsr({
    altNames: ['test.example.com'],
    country: 'US',
    state: 'California',
    locality: 'Los Angeles',
    organization: 'The Company Inc.',
    organizationUnit: 'IT Department',
    emailAddress: 'contact@example.com',
});

Example
Certificate Signing Request with predefined private key

const certificateKey = await acme.forge.createPrivateKey();

const [, certificateRequest] = await acme.forge.createCsr({
    altNames: ['test.example.com'],
}, certificateKey);