Skip to content

Commit

Permalink
crypto: experimental (Ed/X)25519/(Ed/X)448 support
Browse files Browse the repository at this point in the history 
Implements initial experimental support for Curve25519 and
Curve448 support for both ECDH and sign/verify in Web Crypto.

Introduced as a Node.js-specific extension to Web Crypto.

Signed-off-by: James M Snell <jasnell@gmail.com>
Fixes: #36076

PR-URL: #36879
Reviewed-By: Filip Skokan <panva.ip@gmail.com>
  • Loading branch information
@jasnell @ruyadorno
jasnell authored and ruyadorno committed Jan 21, 2021
1 parent 48b6781 commit 68ffe5a
Show file tree
Hide file tree
Showing 15 changed files with 1,287 additions and 167 deletions.
101 changes: 97 additions & 4 deletions doc/api/webcrypto.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,26 @@ async function generateEcKey(namedCurve = 'P-521') {
}
```

#### ED25519/ED448/X25519/X448 Elliptic curve key pairs

```js
const { subtle } = require('crypto').webcrypto;

async function generateEd25519Key() {
return subtle.generateKey({
name: 'NODE-ED25519',
namedCurve: 'NODE-ED25519',
}, true, ['sign', 'verify']);
}

async function generateX25519Key() {
return subtle.generateKey({
name: 'ECDH',
namedCurve: 'NODE-X25519',
}, true, ['deriveKey']);
}
```

#### HMAC keys

```js
Expand Down Expand Up @@ -305,6 +325,8 @@ implementation and the APIs supported for each:
| `'SHA-512'` | | | | | | | | | | | | ✔ |
| `'NODE-DSA'`<sup>1</sup> | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
| `'NODE-DH'`<sup>1</sup> | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | |
| `'NODE-ED25519'`<sup>1</sup> | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
| `'NODE-ED448'`<sup>1</sup> | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |

<sup>1</sup> Node.js-specific extension

Expand Down Expand Up @@ -420,6 +442,8 @@ Valid key usages depend on the key algorithm (identified by
| `'NODE-DSA'` <sup>1</sup> | | | ✔ | ✔ | | | | |
| `'NODE-DH'` <sup>1</sup> | | | | | ✔ | ✔ | | |
| `'NODE-SCRYPT'` <sup>1</sup> | | | | | ✔ | ✔ | | |
| `'NODE-ED25519'` <sup>1</sup> | | | ✔ | ✔ | | | | |
| `'NODE-ED448'` <sup>1</sup> | | | ✔ | ✔ | | | | |

<sup>1</sup> Node.js-specific extension.

Expand Down Expand Up @@ -620,6 +644,8 @@ extension that allows converting a {CryptoKey} into a Node.js {KeyObject}.
| `'NODE-DSA'` <sup>1</sup> | ✔ | ✔ | ✔ | |
| `'NODE-DH'` <sup>1</sup> | ✔ | ✔ | | |
| `'NODE-SCRYPT'` <sup>1</sup> | | | | |
| `'NODE-ED25519'` <sup>1</sup> | ✔ | ✔ | ✔ | ✔ |
| `'NODE-ED448'` <sup>1</sup> | ✔ | ✔ | ✔ | ✔ |

<sup>1</sup> Node.js-specific extension

Expand All @@ -629,7 +655,7 @@ added: v15.0.0
-->

<!--lint disable maximum-line-length remark-lint-->
* `algorithm`: {RsaHashedKeyGenParams|EcKeyGenParams|HmacKeyGenParams|AesKeyGenParams|NodeDsaKeyGenParams|NodeDhKeyGenParams}
* `algorithm`: {RsaHashedKeyGenParams|EcKeyGenParams|HmacKeyGenParams|AesKeyGenParams|NodeDsaKeyGenParams|NodeDhKeyGenParams|NodeEdKeyGenParams}
<!--lint enable maximum-line-length remark-lint-->
* `extractable`: {boolean}
* `keyUsages`: {string[]} See [Key usages][].
Expand All @@ -649,6 +675,8 @@ include:
* `'ECDH'`
* `'NODE-DSA'` <sup>1</sup>
* `'NODE-DH'` <sup>1</sup>
* `'NODE-ED25519'` <sup>1</sup>
* `'NODE-ED448'` <sup>1</sup>

The {CryptoKey} (secret key) generating algorithms supported include:

Expand All @@ -669,7 +697,7 @@ added: v15.0.0
`node.keyObject`.
* `keyData`: {ArrayBuffer|TypedArray|DataView|Buffer|KeyObject}
<!--lint disable maximum-line-length remark-lint-->
* `algorithm`: {RsaHashedImportParams|EcKeyImportParams|HmacImportParams|AesImportParams|Pbkdf2ImportParams|NodeDsaImportParams|NodeDhImportParams|NodeScryptImportParams}
* `algorithm`: {RsaHashedImportParams|EcKeyImportParams|HmacImportParams|AesImportParams|Pbkdf2ImportParams|NodeDsaImportParams|NodeDhImportParams|NodeScryptImportParams|NodeEdKeyImportParams}
<!--lint enable maximum-line-length remark-lint-->
* `extractable`: {boolean}
* `keyUsages`: {string[]} See [Key usages][].
Expand Down Expand Up @@ -704,6 +732,8 @@ The algorithms currently supported include:
| `'NODE-DSA'` <sup>1</sup> | ✔ | ✔ | ✔ | |
| `'NODE-DH'` <sup>1</sup> | ✔ | ✔ | | |
| `'NODE-SCRYPT'` <sup>1</sup> | | | | ✔ |
| `'NODE-ED25519'` <sup>1</sup> | ✔ | ✔ | ✔ | ✔ |
| `'NODE-ED448'` <sup>1</sup> | ✔ | ✔ | ✔ | ✔ |

<sup>1</sup> Node.js-specific extension

Expand Down Expand Up @@ -731,6 +761,8 @@ The algorithms currently supported include:
* `'ECDSA'`
* `'HMAC'`
* `'NODE-DSA'`<sup>1</sup>
* `'NODE-ED25519'`<sup>1</sup>
* `'NODE-ED448'`<sup>1</sup>

<sup>1</sup> Non-standadrd Node.js extension

Expand Down Expand Up @@ -809,6 +841,8 @@ The algorithms currently supported include:
* `'ECDSA'`
* `'HMAC'`
* `'NODE-DSA'`<sup>1</sup>
* `'NODE-ED25519'`<sup>1</sup>
* `'NODE-ED448'`<sup>1</sup>

<sup>1</sup> Non-standard Node.js extension

Expand Down Expand Up @@ -1062,7 +1096,8 @@ added: v15.0.0
added: v15.0.0
-->

* Type: {string} Must be one of `'P-256'`, `'P-384'` or `'P-521'`.
* Type: {string} Must be one of `'P-256'`, `'P-384'`, `'P-521'`,
`'NODE-ED25519'`, `'NODE-ED448'`, `'NODE-X25519'`, or `'NODE-X448'`.

### Class: `EcKeyImportParams`
<!-- YAML
Expand All @@ -1081,7 +1116,8 @@ added: v15.0.0
added: v15.0.0
-->

* Type: {string} Must be one of `'P-256'`, `'P-384'` or `'P-521'`.
* Type: {string} Must be one of `'P-256'`, `'P-384'`, `'P-521'`,
`'NODE-ED25519'`, `'NODE-ED448'`, `'NODE-X25519'`, or `'NODE-X448'`.

### Class: `HkdfParams`
<!-- YAML
Expand Down Expand Up @@ -1598,6 +1634,63 @@ added: v15.0.0

* Type: {string} Must be `'NODE-DSA'`

### `NODE-ED25519` and `NODE-ED448` Algorithms
<!-- YAML
added: REPLACEME
-->

#### Class: `NodeEdKeyGenParams`
<!-- YAML
added: REPLACEME
-->

##### `nodeEdKeyGenParams.name`
<!-- YAML
added: REPLACEME
-->

* Type: {string} Must be one of `'NODE-ED25519'`, `'NODE-ED448'` or `'ECDH'`.

##### `nodeEdKeyGenParams.namedCurve`
<!-- YAML
added: REPLACEME
-->

* Type: {string} Must be one of `'NODE-ED25519'`, `'NODE-ED448'`,
`'NODE-X25519'`, or `'NODE-X448'`.

#### Class: `NodeEdKeyImportParams`
<!-- YAML
added: REPLACEME
-->

##### `nodeEdKeyImportParams.name`
<!-- YAML
added: REPLACEME
-->

* Type: {string} Must be one of `'NODE-ED25519'` or `'NODE-ED448'`
if importing an `Ed25519` or `Ed448` key, or `'ECDH'` if importing
an `X25519` or `X448` key.

##### `nodeEdKeyImportParams.namedCurve`
<!-- YAML
added: REPLACEME
-->

* Type: {string} Must be one of `'NODE-ED25519'`, `'NODE-ED448'`,
`'NODE-X25519'`, or `'NODE-X448'`.

##### `nodeEdKeyImportParams.public`
<!-- YAML
added: REPLACEME
-->

* Type: {boolean}

The `public` parameter is used to specify that the key is to be interpreted
as a public key.

### `NODE-SCRYPT` Algorithm
<!-- YAML
added: v15.0.0
Expand Down
3 changes: 1 addition & 2 deletions lib/internal/crypto/diffiehellman.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,6 @@ const {
toBuf,
kHandle,
kKeyObject,
kNamedCurveAliases,
} = require('internal/crypto/util');

const {
Expand Down Expand Up @@ -451,7 +450,7 @@ async function asyncDeriveBitsECDH(algorithm, baseKey, length) {

const bits = await new Promise((resolve, reject) => {
deriveBitsECDH(
kNamedCurveAliases[baseKey.algorithm.namedCurve],
baseKey.algorithm.namedCurve,
key[kKeyObject][kHandle],
baseKey[kKeyObject][kHandle], (err, bits) => {
if (err) return reject(err);
Expand Down
Loading

0 comments on commit 68ffe5a

Please sign in to comment.