Skip to content

Commit 90ec543

Browse files
panvapanva
committed
crypto: add SubtleCrypto.supports feature detection in Web Cryptography
PR-URL: nodejs#59365 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Ethan Arrowood <ethan@arrowood.dev> Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
1 parent 87f4f99 commit 90ec543

9 files changed

Lines changed: 598 additions & 0 deletions

File tree

‎doc/api/webcrypto.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,10 @@ Key Formats:
102102
* `'raw-secret'`
103103
* `'raw-seed'`
104104

105+
Methods:
106+
107+
* [`SubtleCrypto.supports()`][]
108+
105109
## Secure Curves in the Web Cryptography API
106110

107111
> Stability: 1.1 - Active development
@@ -388,6 +392,76 @@ async function digest(data, algorithm = 'SHA-512') {
388392
}
389393
```
390394

395+
### Checking for runtime algorithm support
396+
397+
[`SubtleCrypto.supports()`][] allows feature detection in Web Crypto API,
398+
which can be used to detect whether a given algorithm identifier
399+
(including its parameters) is supported for the given operation.
400+
401+
This example derives a key from a password using Argon2, if available,
402+
or PBKDF2, otherwise; and then encrypts and decrypts some text with it
403+
using AES-OCB, if available, and AES-GCM, otherwise.
404+
405+
```mjs
406+
const { SubtleCrypto, crypto } = globalThis;
407+
408+
const password = 'correct horse battery staple';
409+
const derivationAlg =
410+
SubtleCrypto.supports?.('importKey', 'Argon2id') ?
411+
'Argon2id' :
412+
'PBKDF2';
413+
const encryptionAlg =
414+
SubtleCrypto.supports?.('importKey', 'AES-OCB') ?
415+
'AES-OCB' :
416+
'AES-GCM';
417+
const passwordKey = await crypto.subtle.importKey(
418+
derivationAlg === 'Argon2id' ? 'raw-secret' : 'raw',
419+
new TextEncoder().encode(password),
420+
derivationAlg,
421+
false,
422+
['deriveKey'],
423+
);
424+
const nonce = crypto.getRandomValues(new Uint8Array(16));
425+
const derivationParams =
426+
derivationAlg === 'Argon2id' ?
427+
{
428+
nonce,
429+
parallelism: 4,
430+
memory: 2 ** 21,
431+
passes: 1,
432+
} :
433+
{
434+
salt: nonce,
435+
iterations: 100_000,
436+
hash: 'SHA-256',
437+
};
438+
const key = await crypto.subtle.deriveKey(
439+
{
440+
name: derivationAlg,
441+
...derivationParams,
442+
},
443+
passwordKey,
444+
{
445+
name: encryptionAlg,
446+
length: 256,
447+
},
448+
false,
449+
['encrypt', 'decrypt'],
450+
);
451+
const plaintext = 'Hello, world!';
452+
const iv = crypto.getRandomValues(new Uint8Array(16));
453+
const encrypted = await crypto.subtle.encrypt(
454+
{ name: encryptionAlg, iv },
455+
key,
456+
new TextEncoder().encode(plaintext),
457+
);
458+
const decrypted = new TextDecoder().decode(await crypto.subtle.decrypt(
459+
{ name: encryptionAlg, iv },
460+
key,
461+
encrypted,
462+
));
463+
```
464+
391465
## Algorithm matrix
392466
393467
The table details the algorithms supported by the Node.js Web Crypto API
@@ -592,6 +666,27 @@ added: v15.0.0
592666
added: v15.0.0
593667
-->
594668
669+
### Static method: `SubtleCrypto.supports(operation, algorithm[, lengthOrAdditionalAlgorithm])`
670+
671+
<!-- YAML
672+
added: REPLACEME
673+
-->
674+
675+
> Stability: 1.1 - Active development
676+
677+
<!--lint disable maximum-line-length remark-lint-->
678+
679+
* `operation` {string} "encrypt", "decrypt", "sign", "verify", "digest", "generateKey", "deriveKey", "deriveBits", "importKey", "exportKey", "wrapKey", or "unwrapKey"
680+
* `algorithm` {string|Algorithm}
681+
* `lengthOrAdditionalAlgorithm` {null|number|string|Algorithm|undefined} Depending on the operation this is either ignored, the value of the length argument when operation is "deriveBits", the algorithm of key to be derived when operation is "deriveKey", the algorithm of key to be exported before wrapping when operation is "wrapKey", or the algorithm of key to be imported after unwrapping when operation is "unwrapKey". **Default:** `null` when operation is "deriveBits", `undefined` otherwise.
682+
* Returns: {boolean} Indicating whether the implementation supports the given operation
683+
684+
<!--lint enable maximum-line-length remark-lint-->
685+
686+
Allows feature detection in Web Crypto API,
687+
which can be used to detect whether a given algorithm identifier
688+
(including its parameters) is supported for the given operation.
689+
595690
### `subtle.decrypt(algorithm, key, data)`
596691
597692
<!-- YAML
@@ -1923,3 +2018,4 @@ The length (in bytes) of the random salt to use.
19232018
[RFC 4122]: https://www.rfc-editor.org/rfc/rfc4122.txt
19242019
[Secure Curves in the Web Cryptography API]: #secure-curves-in-the-web-cryptography-api
19252020
[Web Crypto API]: https://www.w3.org/TR/WebCryptoAPI/
2021+
[`SubtleCrypto.supports()`]: #static-method-subtlecryptosupportsoperation-algorithm-lengthoradditionalalgorithm

‎lib/internal/crypto/hkdf.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -170,4 +170,5 @@ module.exports = {
170170
hkdf,
171171
hkdfSync,
172172
hkdfDeriveBits,
173+
validateHkdfDeriveBitsLength,
173174
};

‎lib/internal/crypto/pbkdf2.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,4 +128,5 @@ module.exports = {
128128
pbkdf2,
129129
pbkdf2Sync,
130130
pbkdf2DeriveBits,
131+
validatePbkdf2DeriveBitsLength,
131132
};

‎lib/internal/crypto/webcrypto.js‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ const {
4747
} = require('internal/crypto/util');
4848

4949
const {
50+
emitExperimentalWarning,
5051
kEnumerableProperty,
5152
lazyDOMException,
5253
} = require('internal/util');
@@ -1026,7 +1027,147 @@ class SubtleCrypto {
10261027
constructor() {
10271028
throw new ERR_ILLEGAL_CONSTRUCTOR();
10281029
}
1030+
1031+
// Implements https://wicg.github.io/webcrypto-modern-algos/#SubtleCrypto-method-supports
1032+
static supports(operation, algorithm, lengthOrAdditionalAlgorithm = null) {
1033+
emitExperimentalWarning('The supports Web Crypto API method');
1034+
if (this !== SubtleCrypto) throw new ERR_INVALID_THIS('SubtleCrypto constructor');
1035+
webidl ??= require('internal/crypto/webidl');
1036+
const prefix = "Failed to execute 'supports' on 'SubtleCrypto'";
1037+
webidl.requiredArguments(arguments.length, 2, { prefix });
1038+
1039+
operation = webidl.converters.DOMString(operation, {
1040+
prefix,
1041+
context: '1st argument',
1042+
});
1043+
algorithm = webidl.converters.AlgorithmIdentifier(algorithm, {
1044+
prefix,
1045+
context: '2nd argument',
1046+
});
1047+
1048+
switch (operation) {
1049+
case 'encrypt':
1050+
case 'decrypt':
1051+
case 'sign':
1052+
case 'verify':
1053+
case 'digest':
1054+
case 'generateKey':
1055+
case 'deriveKey':
1056+
case 'deriveBits':
1057+
case 'importKey':
1058+
case 'exportKey':
1059+
case 'wrapKey':
1060+
case 'unwrapKey':
1061+
break;
1062+
default:
1063+
return false;
1064+
}
1065+
1066+
let length;
1067+
let additionalAlgorithm;
1068+
if (operation === 'deriveKey') {
1069+
additionalAlgorithm = webidl.converters.AlgorithmIdentifier(lengthOrAdditionalAlgorithm, {
1070+
prefix,
1071+
context: '3rd argument',
1072+
});
1073+
1074+
if (!check('importKey', additionalAlgorithm)) {
1075+
return false;
1076+
}
1077+
1078+
try {
1079+
length = getKeyLength(normalizeAlgorithm(additionalAlgorithm, 'get key length'));
1080+
} catch {
1081+
return false;
1082+
}
1083+
1084+
operation = 'deriveBits';
1085+
} else if (operation === 'wrapKey') {
1086+
additionalAlgorithm = webidl.converters.AlgorithmIdentifier(lengthOrAdditionalAlgorithm, {
1087+
prefix,
1088+
context: '3rd argument',
1089+
});
1090+
1091+
if (!check('exportKey', additionalAlgorithm)) {
1092+
return false;
1093+
}
1094+
} else if (operation === 'unwrapKey') {
1095+
additionalAlgorithm = webidl.converters.AlgorithmIdentifier(lengthOrAdditionalAlgorithm, {
1096+
prefix,
1097+
context: '3rd argument',
1098+
});
1099+
1100+
if (!check('importKey', additionalAlgorithm)) {
1101+
return false;
1102+
}
1103+
} else if (operation === 'deriveBits') {
1104+
length = lengthOrAdditionalAlgorithm;
1105+
if (length !== null) {
1106+
length = webidl.converters['unsigned long'](length, {
1107+
prefix,
1108+
context: '3rd argument',
1109+
});
1110+
}
1111+
}
1112+
1113+
return check(operation, algorithm, length);
1114+
}
10291115
}
1116+
1117+
function check(op, alg, length) {
1118+
let normalizedAlgorithm;
1119+
try {
1120+
normalizedAlgorithm = normalizeAlgorithm(alg, op);
1121+
} catch {
1122+
if (op === 'wrapKey') {
1123+
return check('encrypt', alg);
1124+
}
1125+
1126+
if (op === 'unwrapKey') {
1127+
return check('decrypt', alg);
1128+
}
1129+
1130+
return false;
1131+
}
1132+
1133+
switch (op) {
1134+
case 'encrypt':
1135+
case 'decrypt':
1136+
case 'sign':
1137+
case 'verify':
1138+
case 'digest':
1139+
case 'generateKey':
1140+
case 'importKey':
1141+
case 'exportKey':
1142+
case 'wrapKey':
1143+
case 'unwrapKey':
1144+
return true;
1145+
case 'deriveBits': {
1146+
if (normalizedAlgorithm.name === 'HKDF') {
1147+
try {
1148+
require('internal/crypto/hkdf').validateHkdfDeriveBitsLength(length);
1149+
} catch {
1150+
return false;
1151+
}
1152+
}
1153+
1154+
if (normalizedAlgorithm.name === 'PBKDF2') {
1155+
try {
1156+
require('internal/crypto/pbkdf2').validatePbkdf2DeriveBitsLength(length);
1157+
} catch {
1158+
return false;
1159+
}
1160+
}
1161+
1162+
return true;
1163+
}
1164+
default: {
1165+
const assert = require('internal/assert');
1166+
assert.fail('Unreachable code');
1167+
}
1168+
}
1169+
}
1170+
10301171
const subtle = ReflectConstruct(function() {}, [], SubtleCrypto);
10311172

10321173
class Crypto {

0 commit comments

Comments
 (0)