1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: use GFM footnotes in webcrypto.md

Browse Source 
PR-URL: https://github.com/nodejs/node/pull/40477
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
This commit is contained in:
Rich Trott 2021-10-15 21:45:45 -07:00
parent 179248a7b9
commit a749c1f20c
1 changed files with 101 additions and 119 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

220
doc/api/webcrypto.md
View File

@ -306,30 +306,28 @@ async function digest(data, algorithm = 'SHA-512') {
The table details the algorithms supported by the Node.js Web Crypto API The table details the algorithms supported by the Node.js Web Crypto API
implementation and the APIs supported for each: implementation and the APIs supported for each:
| Algorithm | `generateKey` | `exportKey` | `importKey` | `encrypt` | `decrypt` | `wrapKey` | `unwrapKey` | `deriveBits` | `deriveKey` | `sign` | `verify` | `digest` | | Algorithm | `generateKey` | `exportKey` | `importKey` | `encrypt` | `decrypt` | `wrapKey` | `unwrapKey` | `deriveBits` | `deriveKey` | `sign` | `verify` | `digest` |
| ---------------------------- | ------------- | ----------- | ----------- | --------- | --------- | --------- | ----------- | ------------ | ----------- | ------ | -------- | -------- | | --------------------- | ------------- | ----------- | ----------- | --------- | --------- | --------- | ----------- | ------------ | ----------- | ------ | -------- | -------- |
| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | | `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
| `'RSA-PSS'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | | `'RSA-PSS'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
| `'RSA-OAEP'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | | | `'RSA-OAEP'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | |
| `'ECDSA'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | | `'ECDSA'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
| `'ECDH'` | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | | | `'ECDH'` | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | |
| `'AES-CTR'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | | | `'AES-CTR'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | |
| `'AES-CBC'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | | | `'AES-CBC'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | |
| `'AES-GCM'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | | | `'AES-GCM'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | |
| `'AES-KW'` | ✔ | ✔ | ✔ | | | ✔ | ✔ | | | | | | | `'AES-KW'` | ✔ | ✔ | ✔ | | | ✔ | ✔ | | | | | |
| `'HMAC'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | | `'HMAC'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
| `'HKDF'` | | ✔ | ✔ | | | | | ✔ | ✔ | | | | | `'HKDF'` | | ✔ | ✔ | | | | | ✔ | ✔ | | | |
| `'PBKDF2'` | | ✔ | ✔ | | | | | ✔ | ✔ | | | | | `'PBKDF2'` | | ✔ | ✔ | | | | | ✔ | ✔ | | | |
| `'SHA-1'` | | | | | | | | | | | | ✔ | | `'SHA-1'` | | | | | | | | | | | | ✔ |
| `'SHA-256'` | | | | | | | | | | | | ✔ | | `'SHA-256'` | | | | | | | | | | | | ✔ |
| `'SHA-384'` | | | | | | | | | | | | ✔ | | `'SHA-384'` | | | | | | | | | | | | ✔ |
| `'SHA-512'` | | | | | | | | | | | | ✔ | | `'SHA-512'` | | | | | | | | | | | | ✔ |
| `'NODE-DSA'`<sup>1</sup> | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | | `'NODE-DSA'`[^1] | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
| `'NODE-DH'`<sup>1</sup> | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | | | `'NODE-DH'`[^1] | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | |
| `'NODE-ED25519'`<sup>1</sup> | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | | `'NODE-ED25519'`[^1] | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
| `'NODE-ED448'`<sup>1</sup> | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | | `'NODE-ED448'`[^1] | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | |
<sup>1</sup> Node.js-specific extension
## Class: `Crypto` ## Class: `Crypto`
@ -447,27 +445,25 @@ The possible usages are:
Valid key usages depend on the key algorithm (identified by Valid key usages depend on the key algorithm (identified by
`cryptokey.algorithm.name`). `cryptokey.algorithm.name`).
| Key Type | `'encrypt'` | `'decrypt'` | `'sign'` | `'verify'` | `'deriveKey'` | `'deriveBits'` | `'wrapKey'` | `'unwrapKey'` | | Key Type | `'encrypt'` | `'decrypt'` | `'sign'` | `'verify'` | `'deriveKey'` | `'deriveBits'` | `'wrapKey'` | `'unwrapKey'` |
| ----------------------------- | ----------- | ----------- | -------- | ---------- | ------------- | -------------- | ----------- | ------------- | | --------------------- | ----------- | ----------- | -------- | ---------- | ------------- | -------------- | ----------- | ------------- |
| `'AES-CBC'` | ✔ | ✔ | | | | | ✔ | ✔ | | `'AES-CBC'` | ✔ | ✔ | | | | | ✔ | ✔ |
| `'AES-CTR'` | ✔ | ✔ | | | | | ✔ | ✔ | | `'AES-CTR'` | ✔ | ✔ | | | | | ✔ | ✔ |
| `'AES-GCM'` | ✔ | ✔ | | | | | ✔ | ✔ | | `'AES-GCM'` | ✔ | ✔ | | | | | ✔ | ✔ |
| `'AES-KW'` | | | | | | | ✔ | ✔ | | `'AES-KW'` | | | | | | | ✔ | ✔ |
| `'ECDH'` | | | | | ✔ | ✔ | | | | `'ECDH'` | | | | | ✔ | ✔ | | |
| `'ECDSA'` | | | ✔ | ✔ | | | | | | `'ECDSA'` | | | ✔ | ✔ | | | | |
| `'HDKF'` | | | | | ✔ | ✔ | | | | `'HDKF'` | | | | | ✔ | ✔ | | |
| `'HMAC'` | | | ✔ | ✔ | | | | | | `'HMAC'` | | | ✔ | ✔ | | | | |
| `'PBKDF2'` | | | | | ✔ | ✔ | | | | `'PBKDF2'` | | | | | ✔ | ✔ | | |
| `'RSA-OAEP'` | ✔ | ✔ | | | | | ✔ | ✔ | | `'RSA-OAEP'` | ✔ | ✔ | | | | | ✔ | ✔ |
| `'RSA-PSS'` | | | ✔ | ✔ | | | | | | `'RSA-PSS'` | | | ✔ | ✔ | | | | |
| `'RSASSA-PKCS1-v1_5'` | | | ✔ | ✔ | | | | | | `'RSASSA-PKCS1-v1_5'` | | | ✔ | ✔ | | | | |
| `'NODE-DSA'` <sup>1</sup> | | | ✔ | ✔ | | | | | | `'NODE-DSA'`[^1] | | | ✔ | ✔ | | | | |
| `'NODE-DH'` <sup>1</sup> | | | | | ✔ | ✔ | | | | `'NODE-DH'`[^1] | | | | | ✔ | ✔ | | |
| `'NODE-SCRYPT'` <sup>1</sup> | | | | | ✔ | ✔ | | | | `'NODE-SCRYPT'`[^1] | | | | | ✔ | ✔ | | |
| `'NODE-ED25519'` <sup>1</sup> | | | ✔ | ✔ | | | | | | `'NODE-ED25519'`[^1] | | | ✔ | ✔ | | | | |
| `'NODE-ED448'` <sup>1</sup> | | | ✔ | ✔ | | | | | | `'NODE-ED448'`[^1] | | | ✔ | ✔ | | | | |
<sup>1</sup> Node.js-specific extension.
## Class: `CryptoKeyPair` ## Class: `CryptoKeyPair`
@ -549,10 +545,8 @@ The algorithms currently supported include:
* `'ECDH'` * `'ECDH'`
* `'HKDF'` * `'HKDF'`
* `'PBKDF2'` * `'PBKDF2'`
* `'NODE-DH'`<sup>1</sup> * `'NODE-DH'`[^1]
* `'NODE-SCRYPT'`<sup>1</sup> * `'NODE-SCRYPT'`[^1]
<sup>1</sup> Node.js-specific extension
### `subtle.deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)` ### `subtle.deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)`
@ -585,10 +579,8 @@ The algorithms currently supported include:
* `'ECDH'` * `'ECDH'`
* `'HKDF'` * `'HKDF'`
* `'PBKDF2'` * `'PBKDF2'`
* `'NODE-DH'`<sup>1</sup> * `'NODE-DH'`[^1]
* '`NODE-SCRYPT'`<sup>1</sup> * '`NODE-SCRYPT'`[^1]
<sup>1</sup> Node.js-specific extension
### `subtle.digest(algorithm, data)` ### `subtle.digest(algorithm, data)`
@ -667,27 +659,25 @@ specification.
The special `'node.keyObject'` value for `format` is a Node.js-specific The special `'node.keyObject'` value for `format` is a Node.js-specific
extension that allows converting a {CryptoKey} into a Node.js {KeyObject}. extension that allows converting a {CryptoKey} into a Node.js {KeyObject}.
| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` | | Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
| ----------------------------- | -------- | --------- | ------- | ------- | | --------------------- | -------- | --------- | ------- | ------- |
| `'AES-CBC'` | | | ✔ | ✔ | | `'AES-CBC'` | | | ✔ | ✔ |
| `'AES-CTR'` | | | ✔ | ✔ | | `'AES-CTR'` | | | ✔ | ✔ |
| `'AES-GCM'` | | | ✔ | ✔ | | `'AES-GCM'` | | | ✔ | ✔ |
| `'AES-KW'` | | | ✔ | ✔ | | `'AES-KW'` | | | ✔ | ✔ |
| `'ECDH'` | ✔ | ✔ | ✔ | ✔ | | `'ECDH'` | ✔ | ✔ | ✔ | ✔ |
| `'ECDSA'` | ✔ | ✔ | ✔ | ✔ | | `'ECDSA'` | ✔ | ✔ | ✔ | ✔ |
| `'HDKF'` | | | | | | `'HDKF'` | | | | |
| `'HMAC'` | | | ✔ | ✔ | | `'HMAC'` | | | ✔ | ✔ |
| `'PBKDF2'` | | | | | | `'PBKDF2'` | | | | |
| `'RSA-OAEP'` | ✔ | ✔ | ✔ | | | `'RSA-OAEP'` | ✔ | ✔ | ✔ | |
| `'RSA-PSS'` | ✔ | ✔ | ✔ | | | `'RSA-PSS'` | ✔ | ✔ | ✔ | |
| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | | | `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | |
| `'NODE-DSA'` <sup>1</sup> | ✔ | ✔ | | | | `'NODE-DSA'`[^1] | ✔ | ✔ | | |
| `'NODE-DH'` <sup>1</sup> | ✔ | ✔ | | | | `'NODE-DH'`[^1] | ✔ | ✔ | | |
| `'NODE-SCRYPT'` <sup>1</sup> | | | | | | `'NODE-SCRYPT'`[^1] | | | | |
| `'NODE-ED25519'` <sup>1</sup> | ✔ | ✔ | ✔ | ✔ | | `'NODE-ED25519'`[^1] | ✔ | ✔ | ✔ | ✔ |
| `'NODE-ED448'` <sup>1</sup> | ✔ | ✔ | ✔ | ✔ | | `'NODE-ED448'`[^1] | ✔ | ✔ | ✔ | ✔ |
<sup>1</sup> Node.js-specific extension
### `subtle.generateKey(algorithm, extractable, keyUsages)` ### `subtle.generateKey(algorithm, extractable, keyUsages)`
@ -717,10 +707,10 @@ include:
* `'RSA-OAEP'` * `'RSA-OAEP'`
* `'ECDSA'` * `'ECDSA'`
* `'ECDH'` * `'ECDH'`
* `'NODE-DSA'` <sup>1</sup> * `'NODE-DSA'`[^1]
* `'NODE-DH'` <sup>1</sup> * `'NODE-DH'`[^1]
* `'NODE-ED25519'` <sup>1</sup> * `'NODE-ED25519'`[^1]
* `'NODE-ED448'` <sup>1</sup> * `'NODE-ED448'`[^1]
The {CryptoKey} (secret key) generating algorithms supported include: The {CryptoKey} (secret key) generating algorithms supported include:
@ -730,8 +720,6 @@ The {CryptoKey} (secret key) generating algorithms supported include:
* `'AES-GCM'` * `'AES-GCM'`
* `'AES-KW'` * `'AES-KW'`
<sup>1</sup> Non-standard Node.js extension
### `subtle.importKey(format, keyData, algorithm, extractable, keyUsages)` ### `subtle.importKey(format, keyData, algorithm, extractable, keyUsages)`
<!-- YAML <!-- YAML
@ -768,27 +756,25 @@ If importing a `'PBKDF2'` key, `extractable` must be `false`.
The algorithms currently supported include: The algorithms currently supported include:
| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` | | Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` |
| ----------------------------- | -------- | --------- | ------- | ------- | | --------------------- | -------- | --------- | ------- | ------- |
| `'AES-CBC'` | | | ✔ | ✔ | | `'AES-CBC'` | | | ✔ | ✔ |
| `'AES-CTR'` | | | ✔ | ✔ | | `'AES-CTR'` | | | ✔ | ✔ |
| `'AES-GCM'` | | | ✔ | ✔ | | `'AES-GCM'` | | | ✔ | ✔ |
| `'AES-KW'` | | | ✔ | ✔ | | `'AES-KW'` | | | ✔ | ✔ |
| `'ECDH'` | ✔ | ✔ | ✔ | ✔ | | `'ECDH'` | ✔ | ✔ | ✔ | ✔ |
| `'ECDSA'` | ✔ | ✔ | ✔ | ✔ | | `'ECDSA'` | ✔ | ✔ | ✔ | ✔ |
| `'HDKF'` | | | | ✔ | | `'HDKF'` | | | | ✔ |
| `'HMAC'` | | | ✔ | ✔ | | `'HMAC'` | | | ✔ | ✔ |
| `'PBKDF2'` | | | | ✔ | | `'PBKDF2'` | | | | ✔ |
| `'RSA-OAEP'` | ✔ | ✔ | ✔ | | | `'RSA-OAEP'` | ✔ | ✔ | ✔ | |
| `'RSA-PSS'` | ✔ | ✔ | ✔ | | | `'RSA-PSS'` | ✔ | ✔ | ✔ | |
| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | | | `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | |
| `'NODE-DSA'` <sup>1</sup> | ✔ | ✔ | | | | `'NODE-DSA'`[^1] | ✔ | ✔ | | |
| `'NODE-DH'` <sup>1</sup> | ✔ | ✔ | | | | `'NODE-DH'`[^1] | ✔ | ✔ | | |
| `'NODE-SCRYPT'` <sup>1</sup> | | | | ✔ | | `'NODE-SCRYPT'`[^1] | | | | ✔ |
| `'NODE-ED25519'` <sup>1</sup> | ✔ | ✔ | ✔ | ✔ | | `'NODE-ED25519'`[^1] | ✔ | ✔ | ✔ | ✔ |
| `'NODE-ED448'` <sup>1</sup> | ✔ | ✔ | ✔ | ✔ | | `'NODE-ED448'`[^1] | ✔ | ✔ | ✔ | ✔ |
<sup>1</sup> Node.js-specific extension
### `subtle.sign(algorithm, key, data)` ### `subtle.sign(algorithm, key, data)`
@ -816,11 +802,9 @@ The algorithms currently supported include:
* `'RSA-PSS'` * `'RSA-PSS'`
* `'ECDSA'` * `'ECDSA'`
* `'HMAC'` * `'HMAC'`
* `'NODE-DSA'`<sup>1</sup> * `'NODE-DSA'`[^1]
* `'NODE-ED25519'`<sup>1</sup> * `'NODE-ED25519'`[^1]
* `'NODE-ED448'`<sup>1</sup> * `'NODE-ED448'`[^1]
<sup>1</sup> Non-standard Node.js extension
### `subtle.unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgo, unwrappedKeyAlgo, extractable, keyUsages)` ### `subtle.unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgo, unwrappedKeyAlgo, extractable, keyUsages)`
@ -855,10 +839,10 @@ promise is resolved with a {CryptoKey} object.
The wrapping algorithms currently supported include: The wrapping algorithms currently supported include:
* `'RSA-OAEP'` * `'RSA-OAEP'`
* `'AES-CTR'`<sup>1</sup> * `'AES-CTR'`[^1]
* `'AES-CBC'`<sup>1</sup> * `'AES-CBC'`[^1]
* `'AES-GCM'`<sup>1</sup> * `'AES-GCM'`[^1]
* `'AES-KW'`<sup>1</sup> * `'AES-KW'`[^1]
The unwrapped key algorithms supported include: The unwrapped key algorithms supported include:
@ -872,10 +856,8 @@ The unwrapped key algorithms supported include:
* `'AES-CBC'` * `'AES-CBC'`
* `'AES-GCM'` * `'AES-GCM'`
* `'AES-KW'` * `'AES-KW'`
* `'NODE-DSA'`<sup>1</sup> * `'NODE-DSA'`[^1]
* `'NODE-DH'`<sup>1</sup> * `'NODE-DH'`[^1]
<sup>1</sup> Non-standard Node.js extension
### `subtle.verify(algorithm, key, signature, data)` ### `subtle.verify(algorithm, key, signature, data)`
@ -904,11 +886,9 @@ The algorithms currently supported include:
* `'RSA-PSS'` * `'RSA-PSS'`
* `'ECDSA'` * `'ECDSA'`
* `'HMAC'` * `'HMAC'`
* `'NODE-DSA'`<sup>1</sup> * `'NODE-DSA'`[^1]
* `'NODE-ED25519'`<sup>1</sup> * `'NODE-ED25519'`[^1]
* `'NODE-ED448'`<sup>1</sup> * `'NODE-ED448'`[^1]
<sup>1</sup> Non-standard Node.js extension
### `subtle.wrapKey(format, key, wrappingKey, wrapAlgo)` ### `subtle.wrapKey(format, key, wrappingKey, wrapAlgo)`
@ -1933,6 +1913,8 @@ added: v15.0.0
* Type: {string|ArrayBuffer|Buffer|TypedArray|DataView} * Type: {string|ArrayBuffer|Buffer|TypedArray|DataView}
[^1]: Non-standard Node.js-specific extension
[JSON Web Key]: https://tools.ietf.org/html/rfc7517 [JSON Web Key]: https://tools.ietf.org/html/rfc7517
[Key usages]: #cryptokeyusages [Key usages]: #cryptokeyusages
[RFC 4122]: https://www.rfc-editor.org/rfc/rfc4122.txt [RFC 4122]: https://www.rfc-editor.org/rfc/rfc4122.txt