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

Objects

crypto : object

Native Node.js crypto interface

Constants

createPrivateEcdsaKey ⇒ Promise.<buffer>

Generate a private ECDSA key

getPublicKey ⇒ buffer

Get a public key derived from a RSA or ECDSA key

getPemBodyAsB64u ⇒ string

Parse body of PEM encoded object and return a Base64URL string If multiple objects are chained, the first body will be returned

readCsrDomains ⇒ object

Read domains from a Certificate Signing Request

readCertificateInfo ⇒ object

Read information from a certificate If multiple certificates are chained, the first will be read

createCsr ⇒ Promise.<Array.<buffer>>

Create a Certificate Signing Request

createAlpnCertificate ⇒ Promise.<Array.<buffer>>

Create a self-signed ALPN certificate for TLS-ALPN-01 challenges

https://datatracker.ietf.org/doc/html/rfc8737

isAlpnCertificateAuthorizationValid ⇒ boolean

Validate that a ALPN certificate contains the expected key authorization

Functions

createPrivateRsaKey([modulusLength]) ⇒ Promise.<buffer>

Generate a private RSA key

createPrivateKey()

Alias of createPrivateRsaKey()

getJwk(keyPem) ⇒ object

Get a JSON Web Key derived from a RSA or ECDSA key

https://datatracker.ietf.org/doc/html/rfc7517

splitPemChain(chainPem) ⇒ Array.<string>

Split chain of PEM encoded objects from string into array

crypto : object

Native Node.js crypto interface

Kind: global namespace

createPrivateEcdsaKey ⇒ Promise.<buffer>

Generate a private ECDSA key

Kind: global constant
Returns: Promise.<buffer> - PEM encoded private ECDSA key

Param	Type	Description
[namedCurve]	string	ECDSA curve name (P-256, P-384 or P-521), default P-256

Example
Generate private ECDSA key

const privateKey = await acme.crypto.createPrivateEcdsaKey();

Example
Private ECDSA key using P-384 curve

const privateKey = await acme.crypto.createPrivateEcdsaKey('P-384');

getPublicKey ⇒ buffer

Get a public key derived from a RSA or ECDSA key

Kind: global constant
Returns: buffer - PEM encoded public key

Param	Type	Description
keyPem	buffer | string	PEM encoded private or public key

Example
Get public key

const publicKey = acme.crypto.getPublicKey(privateKey);

getPemBodyAsB64u ⇒ string

Parse body of PEM encoded object and return a Base64URL string If multiple objects are chained, the first body will be returned

Kind: global constant
Returns: string - Base64URL-encoded body

Param	Type	Description
pem	buffer | string	PEM encoded chain or object

readCsrDomains ⇒ object

Read domains from a Certificate Signing Request

Kind: global constant
Returns: object - {commonName, altNames}

Param	Type	Description
csrPem	buffer | string	PEM encoded Certificate Signing Request

Example
Read Certificate Signing Request domains

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

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

readCertificateInfo ⇒ object

Read information from a certificate If multiple certificates are chained, the first will be read

Kind: global constant
Returns: object - Certificate info

Param	Type	Description
certPem	buffer | string	PEM encoded certificate or chain

Example
Read certificate information

const info = acme.crypto.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 RSA private key modulus in bits, default: 2048
[data.commonName]	string	FQDN of your server
[data.altNames]	Array.<string>	SAN (Subject Alternative Names), default: []
[data.country]	string	2 letter country code
[data.state]	string	State or province
[data.locality]	string	City
[data.organization]	string	Organization name
[data.organizationUnit]	string	Organizational unit name
[data.emailAddress]	string	Email address
[keyPem]	buffer | string	PEM encoded CSR private key

Example
Create a Certificate Signing Request

const [certificateKey, certificateRequest] = await acme.crypto.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.crypto.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.crypto.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 ECDSA private key

const certificateKey = await acme.crypto.createPrivateEcdsaKey();

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

createAlpnCertificate ⇒ Promise.<Array.<buffer>>

Create a self-signed ALPN certificate for TLS-ALPN-01 challenges

https://datatracker.ietf.org/doc/html/rfc8737

Kind: global constant
Returns: Promise.<Array.<buffer>> - [privateKey, certificate]

Param	Type	Description
authz	object	Identifier authorization
keyAuthorization	string	Challenge key authorization
[keyPem]	buffer | string	PEM encoded CSR private key

Example
Create a ALPN certificate

const [alpnKey, alpnCertificate] = await acme.crypto.createAlpnCertificate(authz, keyAuthorization);

Example
Create a ALPN certificate with ECDSA private key

const alpnKey = await acme.crypto.createPrivateEcdsaKey();
const [, alpnCertificate] = await acme.crypto.createAlpnCertificate(authz, keyAuthorization, alpnKey);

isAlpnCertificateAuthorizationValid ⇒ boolean

Validate that a ALPN certificate contains the expected key authorization

Kind: global constant
Returns: boolean - True when valid

Param	Type	Description
certPem	buffer | string	PEM encoded certificate
keyAuthorization	string	Expected challenge key authorization

createPrivateRsaKey([modulusLength]) ⇒ Promise.<buffer>

Generate a private RSA key

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

Param	Type	Description
[modulusLength]	number	Size of the keys modulus in bits, default: 2048

Example
Generate private RSA key

const privateKey = await acme.crypto.createPrivateRsaKey();

Example
Private RSA key with modulus size 4096

const privateKey = await acme.crypto.createPrivateRsaKey(4096);

createPrivateKey()

Alias of createPrivateRsaKey()

Kind: global function

getJwk(keyPem) ⇒ object

Get a JSON Web Key derived from a RSA or ECDSA key

https://datatracker.ietf.org/doc/html/rfc7517

Kind: global function
Returns: object - JSON Web Key

Param	Type	Description
keyPem	buffer | string	PEM encoded private or public key

Example
Get JWK

const jwk = acme.crypto.getJwk(privateKey);

splitPemChain(chainPem) ⇒ Array.<string>

Split chain of PEM encoded objects from string into array

Kind: global function
Returns: Array.<string> - Array of PEM objects including headers

Param	Type	Description
chainPem	buffer | string	PEM encoded object chain