From 3627616b405e81835ba52d2aeade705038fc33fe Mon Sep 17 00:00:00 2001 From: Filip Skokan Date: Thu, 6 Oct 2022 16:14:58 +0200 Subject: [PATCH] doc,crypto: mark experimental algorithms more visually PR-URL: https://github.com/nodejs/node/pull/44892 Reviewed-By: Luigi Pinca Reviewed-By: Rich Trott --- doc/api/webcrypto.md | 182 +++++++++++++++++++-------------------- doc/api_assets/style.css | 9 ++ 2 files changed, 100 insertions(+), 91 deletions(-) diff --git a/doc/api/webcrypto.md b/doc/api/webcrypto.md index 280e0714276e63..d50fec3a8b4482 100644 --- a/doc/api/webcrypto.md +++ b/doc/api/webcrypto.md @@ -332,28 +332,28 @@ async function digest(data, algorithm = 'SHA-512') { The table details the algorithms supported by the Node.js Web Crypto API implementation and the APIs supported for each: -| Algorithm | `generateKey` | `exportKey` | `importKey` | `encrypt` | `decrypt` | `wrapKey` | `unwrapKey` | `deriveBits` | `deriveKey` | `sign` | `verify` | `digest` | -| --------------------- | ------------- | ----------- | ----------- | --------- | --------- | --------- | ----------- | ------------ | ----------- | ------ | -------- | -------- | -| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | -| `'RSA-PSS'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | -| `'RSA-OAEP'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | | -| `'ECDSA'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | -| `'Ed25519'`[^1] | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | -| `'Ed448'`[^1] | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | -| `'ECDH'` | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | | -| `'X25519'`[^1] | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | | -| `'X448'`[^1] | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | | -| `'AES-CTR'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | | -| `'AES-CBC'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | | -| `'AES-GCM'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | | -| `'AES-KW'` | ✔ | ✔ | ✔ | | | ✔ | ✔ | | | | | | -| `'HMAC'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | -| `'HKDF'` | | ✔ | ✔ | | | | | ✔ | ✔ | | | | -| `'PBKDF2'` | | ✔ | ✔ | | | | | ✔ | ✔ | | | | -| `'SHA-1'` | | | | | | | | | | | | ✔ | -| `'SHA-256'` | | | | | | | | | | | | ✔ | -| `'SHA-384'` | | | | | | | | | | | | ✔ | -| `'SHA-512'` | | | | | | | | | | | | ✔ | +| Algorithm | `generateKey` | `exportKey` | `importKey` | `encrypt` | `decrypt` | `wrapKey` | `unwrapKey` | `deriveBits` | `deriveKey` | `sign` | `verify` | `digest` | +| --------------------------------------------------------- | ------------- | ----------- | ----------- | --------- | --------- | --------- | ----------- | ------------ | ----------- | ------ | -------- | -------- | +| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | +| `'RSA-PSS'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | +| `'RSA-OAEP'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | | +| `'ECDSA'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | +| `'Ed25519'` [^1] | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | +| `'Ed448'` [^1] | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | +| `'ECDH'` | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | | +| `'X25519'` [^1] | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | | +| `'X448'` [^1] | ✔ | ✔ | ✔ | | | | | ✔ | ✔ | | | | +| `'AES-CTR'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | | +| `'AES-CBC'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | | +| `'AES-GCM'` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | | | | +| `'AES-KW'` | ✔ | ✔ | ✔ | | | ✔ | ✔ | | | | | | +| `'HMAC'` | ✔ | ✔ | ✔ | | | | | | | ✔ | ✔ | | +| `'HKDF'` | | ✔ | ✔ | | | | | ✔ | ✔ | | | | +| `'PBKDF2'` | | ✔ | ✔ | | | | | ✔ | ✔ | | | | +| `'SHA-1'` | | | | | | | | | | | | ✔ | +| `'SHA-256'` | | | | | | | | | | | | ✔ | +| `'SHA-384'` | | | | | | | | | | | | ✔ | +| `'SHA-512'` | | | | | | | | | | | | ✔ | ## Class: `Crypto` @@ -475,24 +475,24 @@ The possible usages are: Valid key usages depend on the key algorithm (identified by `cryptokey.algorithm.name`). -| Key Type | `'encrypt'` | `'decrypt'` | `'sign'` | `'verify'` | `'deriveKey'` | `'deriveBits'` | `'wrapKey'` | `'unwrapKey'` | -| --------------------- | ----------- | ----------- | -------- | ---------- | ------------- | -------------- | ----------- | ------------- | -| `'AES-CBC'` | ✔ | ✔ | | | | | ✔ | ✔ | -| `'AES-CTR'` | ✔ | ✔ | | | | | ✔ | ✔ | -| `'AES-GCM'` | ✔ | ✔ | | | | | ✔ | ✔ | -| `'AES-KW'` | | | | | | | ✔ | ✔ | -| `'ECDH'` | | | | | ✔ | ✔ | | | -| `'X25519'`[^1] | | | | | ✔ | ✔ | | | -| `'X448'`[^1] | | | | | ✔ | ✔ | | | -| `'ECDSA'` | | | ✔ | ✔ | | | | | -| `'Ed25519'`[^1] | | | ✔ | ✔ | | | | | -| `'Ed448'`[^1] | | | ✔ | ✔ | | | | | -| `'HDKF'` | | | | | ✔ | ✔ | | | -| `'HMAC'` | | | ✔ | ✔ | | | | | -| `'PBKDF2'` | | | | | ✔ | ✔ | | | -| `'RSA-OAEP'` | ✔ | ✔ | | | | | ✔ | ✔ | -| `'RSA-PSS'` | | | ✔ | ✔ | | | | | -| `'RSASSA-PKCS1-v1_5'` | | | ✔ | ✔ | | | | | +| Key Type | `'encrypt'` | `'decrypt'` | `'sign'` | `'verify'` | `'deriveKey'` | `'deriveBits'` | `'wrapKey'` | `'unwrapKey'` | +| --------------------------------------------------------- | ----------- | ----------- | -------- | ---------- | ------------- | -------------- | ----------- | ------------- | +| `'AES-CBC'` | ✔ | ✔ | | | | | ✔ | ✔ | +| `'AES-CTR'` | ✔ | ✔ | | | | | ✔ | ✔ | +| `'AES-GCM'` | ✔ | ✔ | | | | | ✔ | ✔ | +| `'AES-KW'` | | | | | | | ✔ | ✔ | +| `'ECDH'` | | | | | ✔ | ✔ | | | +| `'X25519'` [^1] | | | | | ✔ | ✔ | | | +| `'X448'` [^1] | | | | | ✔ | ✔ | | | +| `'ECDSA'` | | | ✔ | ✔ | | | | | +| `'Ed25519'` [^1] | | | ✔ | ✔ | | | | | +| `'Ed448'` [^1] | | | ✔ | ✔ | | | | | +| `'HDKF'` | | | | | ✔ | ✔ | | | +| `'HMAC'` | | | ✔ | ✔ | | | | | +| `'PBKDF2'` | | | | | ✔ | ✔ | | | +| `'RSA-OAEP'` | ✔ | ✔ | | | | | ✔ | ✔ | +| `'RSA-PSS'` | | | ✔ | ✔ | | | | | +| `'RSASSA-PKCS1-v1_5'` | | | ✔ | ✔ | | | | | ## Class: `CryptoKeyPair` @@ -575,7 +575,7 @@ The Node.js implementation requires that when `length` is a number it must be multiple of `8`. When `length` is `null` the maximum number of bits for a given algorithm is -generated. This is allowed for the `'ECDH'`, `'X25519'`[^1], and `'X448'`[^1] +generated. This is allowed for the `'ECDH'`, `'X25519'`, and `'X448'` algorithms. If successful, the returned promise will be resolved with an {ArrayBuffer} @@ -584,8 +584,8 @@ containing the generated data. The algorithms currently supported include: * `'ECDH'` -* `'X25519'`[^1] -* `'X448'`[^1] +* `'X25519'` [^1] +* `'X448'` [^1] * `'HKDF'` * `'PBKDF2'` @@ -622,8 +622,8 @@ generate raw keying material, then passing the result into the The algorithms currently supported include: * `'ECDH'` -* `'X25519'`[^1] -* `'X448'`[^1] +* `'X25519'` [^1] +* `'X448'` [^1] * `'HKDF'` * `'PBKDF2'` @@ -703,22 +703,22 @@ When `format` is `'jwk'` and the export is successful, the returned promise will be resolved with a JavaScript object conforming to the [JSON Web Key][] specification. -| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` | -| --------------------- | -------- | --------- | ------- | ------- | -| `'AES-CBC'` | | | ✔ | ✔ | -| `'AES-CTR'` | | | ✔ | ✔ | -| `'AES-GCM'` | | | ✔ | ✔ | -| `'AES-KW'` | | | ✔ | ✔ | -| `'ECDH'` | ✔ | ✔ | ✔ | ✔ | -| `'ECDSA'` | ✔ | ✔ | ✔ | ✔ | -| `'Ed25519'`[^1] | ✔ | ✔ | ✔ | ✔ | -| `'Ed448'`[^1] | ✔ | ✔ | ✔ | ✔ | -| `'HDKF'` | | | | | -| `'HMAC'` | | | ✔ | ✔ | -| `'PBKDF2'` | | | | | -| `'RSA-OAEP'` | ✔ | ✔ | ✔ | | -| `'RSA-PSS'` | ✔ | ✔ | ✔ | | -| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | | +| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` | +| --------------------------------------------------------- | -------- | --------- | ------- | ------- | +| `'AES-CBC'` | | | ✔ | ✔ | +| `'AES-CTR'` | | | ✔ | ✔ | +| `'AES-GCM'` | | | ✔ | ✔ | +| `'AES-KW'` | | | ✔ | ✔ | +| `'ECDH'` | ✔ | ✔ | ✔ | ✔ | +| `'ECDSA'` | ✔ | ✔ | ✔ | ✔ | +| `'Ed25519'` [^1] | ✔ | ✔ | ✔ | ✔ | +| `'Ed448'` [^1] | ✔ | ✔ | ✔ | ✔ | +| `'HDKF'` | | | | | +| `'HMAC'` | | | ✔ | ✔ | +| `'PBKDF2'` | | | | | +| `'RSA-OAEP'` | ✔ | ✔ | ✔ | | +| `'RSA-PSS'` | ✔ | ✔ | ✔ | | +| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | | ### `subtle.generateKey(algorithm, extractable, keyUsages)` @@ -747,11 +747,11 @@ include: * `'RSA-PSS'` * `'RSA-OAEP'` * `'ECDSA'` -* `'Ed25519'`[^1] -* `'Ed448'`[^1] +* `'Ed25519'` [^1] +* `'Ed448'` [^1] * `'ECDH'` -* `'X25519'`[^1] -* `'X448'`[^1] +* `'X25519'` [^1] +* `'X448'` [^1] The {CryptoKey} (secret key) generating algorithms supported include: @@ -797,24 +797,24 @@ If importing a `'PBKDF2'` key, `extractable` must be `false`. The algorithms currently supported include: -| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` | -| --------------------- | -------- | --------- | ------- | ------- | -| `'AES-CBC'` | | | ✔ | ✔ | -| `'AES-CTR'` | | | ✔ | ✔ | -| `'AES-GCM'` | | | ✔ | ✔ | -| `'AES-KW'` | | | ✔ | ✔ | -| `'ECDH'` | ✔ | ✔ | ✔ | ✔ | -| `'X25519'`[^1] | ✔ | ✔ | ✔ | ✔ | -| `'X448'`[^1] | ✔ | ✔ | ✔ | ✔ | -| `'ECDSA'` | ✔ | ✔ | ✔ | ✔ | -| `'Ed25519'`[^1] | ✔ | ✔ | ✔ | ✔ | -| `'Ed448'`[^1] | ✔ | ✔ | ✔ | ✔ | -| `'HDKF'` | | | | ✔ | -| `'HMAC'` | | | ✔ | ✔ | -| `'PBKDF2'` | | | | ✔ | -| `'RSA-OAEP'` | ✔ | ✔ | ✔ | | -| `'RSA-PSS'` | ✔ | ✔ | ✔ | | -| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | | +| Key Type | `'spki'` | `'pkcs8'` | `'jwk'` | `'raw'` | +| --------------------------------------------------------- | -------- | --------- | ------- | ------- | +| `'AES-CBC'` | | | ✔ | ✔ | +| `'AES-CTR'` | | | ✔ | ✔ | +| `'AES-GCM'` | | | ✔ | ✔ | +| `'AES-KW'` | | | ✔ | ✔ | +| `'ECDH'` | ✔ | ✔ | ✔ | ✔ | +| `'X25519'` [^1] | ✔ | ✔ | ✔ | ✔ | +| `'X448'` [^1] | ✔ | ✔ | ✔ | ✔ | +| `'ECDSA'` | ✔ | ✔ | ✔ | ✔ | +| `'Ed25519'` [^1] | ✔ | ✔ | ✔ | ✔ | +| `'Ed448'` [^1] | ✔ | ✔ | ✔ | ✔ | +| `'HDKF'` | | | | ✔ | +| `'HMAC'` | | | ✔ | ✔ | +| `'PBKDF2'` | | | | ✔ | +| `'RSA-OAEP'` | ✔ | ✔ | ✔ | | +| `'RSA-PSS'` | ✔ | ✔ | ✔ | | +| `'RSASSA-PKCS1-v1_5'` | ✔ | ✔ | ✔ | | ### `subtle.sign(algorithm, key, data)` @@ -845,8 +845,8 @@ The algorithms currently supported include: * `'RSASSA-PKCS1-v1_5'` * `'RSA-PSS'` * `'ECDSA'` -* `'Ed25519'`[^1] -* `'Ed448'`[^1] +* `'Ed25519'` [^1] +* `'Ed448'` [^1] * `'HMAC'` ### `subtle.unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgo, unwrappedKeyAlgo, extractable, keyUsages)` @@ -893,11 +893,11 @@ The unwrapped key algorithms supported include: * `'RSA-PSS'` * `'RSA-OAEP'` * `'ECDSA'` -* `'Ed25519'`[^1] -* `'Ed448'`[^1] +* `'Ed25519'` [^1] +* `'Ed448'` [^1] * `'ECDH'` -* `'X25519'`[^1] -* `'X448'`[^1] +* `'X25519'` [^1] +* `'X448'` [^1] * `'HMAC'` * `'AES-CTR'` * `'AES-CBC'` @@ -934,8 +934,8 @@ The algorithms currently supported include: * `'RSASSA-PKCS1-v1_5'` * `'RSA-PSS'` * `'ECDSA'` -* `'Ed25519'`[^1] -* `'Ed448'`[^1] +* `'Ed25519'` [^1] +* `'Ed448'` [^1] * `'HMAC'` ### `subtle.wrapKey(format, key, wrappingKey, wrapAlgo)` diff --git a/doc/api_assets/style.css b/doc/api_assets/style.css index 43d7994e287c3e..42126949d55d5c 100644 --- a/doc/api_assets/style.css +++ b/doc/api_assets/style.css @@ -616,6 +616,15 @@ hr { border-radius: 3px; } +.experimental-inline::after { + background-color: var(--red3); + color: var(--white); + content: "experimental"; + margin-left: .25rem; + padding: 1px 3px; + border-radius: 3px; +} + #apicontent li { margin-bottom: .5rem; }