crypto: introduce crypto/promises

Refs: #36181

doc/api/crypto.md

@@ -2551,8 +2551,8 @@ added:
 * Returns: {Buffer}
 
 Computes the Diffie-Hellman secret based on a `privateKey` and a `publicKey`.
-Both keys must have the same `asymmetricKeyType`, which must be one of `'dh'`
-(for Diffie-Hellman), `'ec'` (for ECDH), `'x448'`, or `'x25519'` (for ECDH-ES).
+Both keys must have the same `asymmetricKeyType`, which must be one of `'dh'`,
+`'ec'`, `'x448'`, or `'x25519'`.
 
 ### `crypto.generateKey(type, options, callback)`
 <!-- YAML
@@ -3895,6 +3895,130 @@ Type: {Crypto} An implementation of the Web Crypto API standard.
 
 See the [Web Crypto API documentation][] for details.
 
+## `crypto` Promises API
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+The `crypto.promises` API provides an alternative set of asynchronous crypto
+methods that return `Promise` objects and execute operations in libuv's
+threadpool.
+The API is accessible via `require('crypto').promises` or `require('crypto/promises')`.
+
+### `cryptoPromises.diffieHellman(options)`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `options`: {Object}
+ * `privateKey`: {KeyObject|CryptoKey}
+ * `publicKey`: {KeyObject|CryptoKey}
+* Returns: {Promise} containing {Buffer}
+
+Computes the Diffie-Hellman secret based on a `privateKey` and a `publicKey`.
+Both keys must have the same `asymmetricKeyType`, which must be one of `'dh'`,
+`'ec'`, `'x448'`, or `'x25519'`.
+
+### `cryptoPromises.digest(algorithm, data[, options])`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `algorithm` {string}
+* `data` {ArrayBuffer|TypedArray|DataView|Buffer}
+* `options` {Object}
+ * `outputLength` {number} Used to specify the desired output length in bytes
+ for XOF hash functions such as `'shake256'`.
+* Returns: {Promise} containing {Buffer}
+
+Calculates the digest for the `data` using the given `algorithm`.
+
+The `algorithm` is dependent on the available algorithms supported by the
+version of OpenSSL on the platform. Examples are `'sha256'`, `'sha512'`, etc.
+On recent releases of OpenSSL, `openssl list -digest-algorithms`
+(`openssl list-message-digest-algorithms` for older versions of OpenSSL) will
+display the available digest algorithms.
+
+### `cryptoPromises.hmac(algorithm, data, key)`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `algorithm` {string}
+* `data` {ArrayBuffer|TypedArray|DataView|Buffer}
+* `key` {KeyObject|CryptoKey}
+* Returns: {Promise} containing {Buffer}
+
+Calculates the HMAC digest for the `data` using the given `algorithm`.
+
+The `algorithm` is dependent on the available algorithms supported by the
+version of OpenSSL on the platform. Examples are `'sha256'`, `'sha512'`, etc.
+On recent releases of OpenSSL, `openssl list -digest-algorithms`
+(`openssl list-message-digest-algorithms` for older versions of OpenSSL) will
+display the available digest algorithms.
+
+### `cryptoPromises.sign(algorithm, data, key[, options])`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `algorithm` {string|null|undefined}
+* `data` {ArrayBuffer|TypedArray|DataView|Buffer}
+* `key` {KeyObject|CryptoKey}
+* `options` {Object}
+ * `dsaEncoding` {string} For DSA and ECDSA, this option specifies the
+ format of the generated signature. It can be one of the following:
+ * `'der'` (default): DER-encoded ASN.1 signature structure encoding `(r, s)`.
+ * `'ieee-p1363'`: Signature format `r || s` as proposed in IEEE-P1363.
+ * `padding` {integer} Optional padding value for RSA, one of the following:
+ * `crypto.constants.RSA_PKCS1_PADDING` (default)
+ * `crypto.constants.RSA_PKCS1_PSS_PADDING`
+ * `saltLength` {integer} Salt length for when padding is
+ `RSA_PKCS1_PSS_PADDING`. The special value
+ `crypto.constants.RSA_PSS_SALTLEN_DIGEST` sets the salt length to the digest
+ size, `crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN` (default) sets it to the
+ maximum permissible value.
+* Returns: {Promise} containing {Buffer}
+
+Calculates the signature for `data` using the given private key and
+algorithm. If `algorithm` is `null` or `undefined`, then the algorithm is
+dependent upon the key type (especially Ed25519 and Ed448).
+
+### `cryptoPromises.verify(algorithm, data, key, signature[, options])`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `algorithm` {string|null|undefined}
+* `data` {ArrayBuffer|TypedArray|DataView|Buffer}
+* `key` {KeyObject|CryptoKey}
+* `signature` {ArrayBuffer|TypedArray|DataView|Buffer}
+* `options` {Object}
+ * `dsaEncoding` {string} For DSA and ECDSA, this option specifies the
+ format of the generated signature. It can be one of the following:
+ * `'der'` (default): DER-encoded ASN.1 signature structure encoding `(r, s)`.
+ * `'ieee-p1363'`: Signature format `r || s` as proposed in IEEE-P1363.
+ * `padding` {integer} Optional padding value for RSA, one of the following:
+ * `crypto.constants.RSA_PKCS1_PADDING` (default)
+ * `crypto.constants.RSA_PKCS1_PSS_PADDING`
+ * `saltLength` {integer} Salt length for when padding is
+ `RSA_PKCS1_PSS_PADDING`. The special value
+ `crypto.constants.RSA_PSS_SALTLEN_DIGEST` sets the salt length to the digest
+ size, `crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN` (default) sets it to the
+ maximum permissible value.
+* Returns: {Promise} containing {boolean}
+
+Verifies the given signature for `data` using the given key and algorithm. If
+`algorithm` is `null` or `undefined`, then the algorithm is dependent upon the
+key type (especially Ed25519 and Ed448).
+
+The `signature` argument is the previously calculated signature for the `data`.
+
+Because public keys can be derived from private keys, a private key or a public
+key may be passed for `key`.
+
 ## Notes
 
 ### Legacy streams API (prior to Node.js 0.10)

lib/crypto.js

@@ -172,6 +172,9 @@ function createVerify(algorithm, options) {
  return new Verify(algorithm, options);
 }
 
+// Lazy loaded
+let promises = null;
+
 module.exports = {
  // Methods
  checkPrime,
@@ -327,5 +330,14 @@ ObjectDefineProperties(module.exports, {
  value: pendingDeprecation ?
  deprecate(randomBytes, 'crypto.rng is deprecated.', 'DEP0115') :
  randomBytes
+ },
+ promises: {
+ configurable: true,
+ enumerable: true,
+ get() {
+ if (promises === null)
+ promises = require('internal/crypto/promises').exports;
+ return promises;
+ }
  }
 });

lib/crypto/promises.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('internal/crypto/promises').exports;

lib/internal/crypto/diffiehellman.js

@@ -346,6 +346,46 @@ function deriveBitsDH(publicKey, privateKey, callback) {
  job.run();
 }
 
+async function asyncDiffieHellman(publicKey, privateKey) {
+ const { asymmetricKeyType } = privateKey;
+
+ if (asymmetricKeyType === 'dh') {
+ return new Promise((resolve, reject) => {
+ deriveBitsDH(
+ publicKey[kHandle],
+ privateKey[kHandle],
+ (err, bits) => {
+ if (err) reject(err);
+ else resolve(bits);
+ });
+ });
+ }
+
+ if (asymmetricKeyType === 'x25519' || asymmetricKeyType === 'x448') {
+ return new Promise((resolve, reject) => {
+ deriveBitsECDH(
+ `NODE-${asymmetricKeyType.toUpperCase()}`,
+ publicKey[kHandle],
+ privateKey[kHandle],
+ (err, bits) => {
+ if (err) reject(err);
+ else resolve(bits);
+ });
+ });
+ }
+
+ return new Promise((resolve, reject) => {
+ deriveBitsECDH(
+ privateKey.asymmetricKeyDetails.namedCurve,
+ publicKey[kHandle],
+ privateKey[kHandle],
+ (err, bits) => {
+ if (err) reject(err);
+ else resolve(bits);
+ });
+ });
+}
+
 function verifyAcceptableDhKeyUse(name, type, usages) {
  let checkSet;
  switch (type) {
@@ -601,9 +641,11 @@ module.exports = {
  DiffieHellman,
  DiffieHellmanGroup,
  ECDH,
+ asyncDiffieHellman,
  diffieHellman,
  deriveBitsECDH,
  deriveBitsDH,
+ dhEnabledKeyTypes,
  dhGenerateKey,
  asyncDeriveBitsECDH,
  asyncDeriveBitsDH,