Skip to content

Latest commit

 

History

History
316 lines (258 loc) · 10.9 KB

crypto.md

File metadata and controls

316 lines (258 loc) · 10.9 KB
Raw

Objects

crypto : object

Native Node.js crypto interface

Functions

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

Generate a private RSA key

createPrivateKey()

Alias of createPrivateRsaKey()

createPrivateEcdsaKey([namedCurve]) ⇒ Promise.<buffer>

Generate a private ECDSA key

getPublicKey(keyPem) ⇒ buffer

Get a public key derived from a RSA or ECDSA key

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

getPemBodyAsB64u(pem) ⇒ string

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

readCsrDomains(csrPem) ⇒ object

Read domains from a Certificate Signing Request

readCertificateInfo(certPem) ⇒ object

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

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

Create a Certificate Signing Request

createAlpnCertificate(authz, keyAuthorization, [keyPem]) ⇒ Promise.<Array.<buffer>>

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

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

isAlpnCertificateAuthorizationValid(certPem, keyAuthorization) ⇒ boolean

Validate that a ALPN certificate contains the expected key authorization

crypto : object

Native Node.js crypto interface

Kind: global namespace

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

Generate a private RSA key

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

Param Type Default Description
[modulusLength] number 2048 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

createPrivateEcdsaKey([namedCurve]) ⇒ Promise.<buffer>

Generate a private ECDSA key

Kind: global function
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(keyPem) ⇒ buffer

Get a public key derived from a RSA or ECDSA key

Kind: global function
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);

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

getPemBodyAsB64u(pem) ⇒ 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 function
Returns: string - Base64URL-encoded body

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

readCsrDomains(csrPem) ⇒ object

Read domains from a Certificate Signing Request

Kind: global function
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(certPem) ⇒ object

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

Kind: global function
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(data, [keyPem]) ⇒ 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 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(authz, keyAuthorization, [keyPem]) ⇒ Promise.<Array.<buffer>>

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

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

Kind: global function
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(certPem, keyAuthorization) ⇒ boolean

Validate that a ALPN certificate contains the expected key authorization

Kind: global function
Returns: boolean - True when valid

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