certd/packages/core/acme-client/docs/forge.md

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.

Constants

createPublicKey ⇒ Promise.<buffer>

Create public key from a private RSA key

getPemBody ⇒ string

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

splitPemChain ⇒ Array.<string>

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

getModulus ⇒ Promise.<buffer>

Get modulus

getPublicExponent ⇒ Promise.<buffer>

Get public exponent

readCsrDomains ⇒ Promise.<object>

Read domains from a Certificate Signing Request

readCertificateInfo ⇒ Promise.<object>

Read information from a certificate

createCsr ⇒ Promise.<Array.<buffer>>

Create a Certificate Signing Request

Functions

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

Generate a private RSA key

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.

Kind: global namespace

createPublicKey ⇒ Promise.<buffer>

Create public key from a private RSA key

Kind: global constant
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 ⇒ string

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

Kind: global constant
Returns: string - PEM body

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

splitPemChain ⇒ Array.<string>

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

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

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

getModulus ⇒ Promise.<buffer>

Get modulus

Kind: global constant
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 ⇒ Promise.<buffer>

Get public exponent

Kind: global constant
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 ⇒ Promise.<object>

Read domains from a Certificate Signing Request

Kind: global constant
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 ⇒ Promise.<object>

Read information from a certificate

Kind: global constant
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 ⇒ Promise.<Array.<buffer>>

Create a Certificate Signing Request

Kind: global constant
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);
<a name="createPrivateKey"></a>

## createPrivateKey([size]) ⇒ <code>Promise.&lt;buffer&gt;</code>
Generate a private RSA key

**Kind**: global function  
**Returns**: <code>Promise.&lt;buffer&gt;</code> - PEM encoded private RSA key  

| Param | Type | Description |
| --- | --- | --- |
| [size] | <code>number</code> | Size of the key, default: `2048` |

**Example**  
Generate private RSA key
```js
const privateKey = await acme.forge.createPrivateKey();

Example
Private RSA key with defined size

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