Skip to content

Commit ccd756d

Browse files
panvasxa
panva
authored and
sxa
committed
crypto: add TurboSHAKE and KangarooTwelve Web Cryptography algorithms
PR-URL: #62183 Backport-PR-URL: #63563 Refs: https://wicg.github.io/webcrypto-modern-algos/#kangarootwelve Refs: https://wicg.github.io/webcrypto-modern-algos/#turboshake Refs: https://www.rfc-editor.org/rfc/rfc9861.html Refs: https://redirect.github.com/openssl/openssl/issues/30304 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>
1 parent a002974 commit ccd756d

14 files changed

Lines changed: 1523 additions & 8 deletions

File tree

‎doc/api/webcrypto.md‎

Lines changed: 85 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@
22

33
<!-- YAML
44
changes:
5+
- version: REPLACEME
6+
pr-url: https://github.com/nodejs/node/pull/62183
7+
description: TurboSHAKE and KangarooTwelve algorithms
8+
are now supported.
59
- version: v24.8.0
610
pr-url: https://github.com/nodejs/node/pull/59647
711
description: KMAC algorithms are now supported.
@@ -121,6 +125,8 @@ Algorithms:
121125
* `'cSHAKE256'`
122126
* `'KMAC128'`[^openssl30]
123127
* `'KMAC256'`[^openssl30]
128+
* `'KT128'`
129+
* `'KT256'`
124130
* `'ML-DSA-44'`[^openssl35]
125131
* `'ML-DSA-65'`[^openssl35]
126132
* `'ML-DSA-87'`[^openssl35]
@@ -130,6 +136,8 @@ Algorithms:
130136
* `'SHA3-256'`
131137
* `'SHA3-384'`
132138
* `'SHA3-512'`
139+
* `'TurboSHAKE128'`
140+
* `'TurboSHAKE256'`
133141

134142
Key Formats:
135143

@@ -574,6 +582,8 @@ Crypto API implementation and the APIs supported for each:
574582
| `'HMAC'` | | ✔ | | | | |
575583
| `'KMAC128'`[^modern-algos] | | ✔ | | | | |
576584
| `'KMAC256'`[^modern-algos] | | ✔ | | | | |
585+
| `'KT128'`[^modern-algos] | | | | | | ✔ |
586+
| `'KT256'`[^modern-algos] | | | | | | ✔ |
577587
| `'ML-DSA-44'`[^modern-algos] | | ✔ | | | | |
578588
| `'ML-DSA-65'`[^modern-algos] | | ✔ | | | | |
579589
| `'ML-DSA-87'`[^modern-algos] | | ✔ | | | | |
@@ -591,6 +601,8 @@ Crypto API implementation and the APIs supported for each:
591601
| `'SHA3-256'`[^modern-algos] | | | | | | ✔ |
592602
| `'SHA3-384'`[^modern-algos] | | | | | | ✔ |
593603
| `'SHA3-512'`[^modern-algos] | | | | | | ✔ |
604+
| `'TurboSHAKE128'`[^modern-algos] | | | | | | ✔ |
605+
| `'TurboSHAKE256'`[^modern-algos] | | | | | | ✔ |
594606
| `'X25519'` | | | ✔ | | | |
595607
| `'X448'`[^secure-curves] | | | ✔ | | | |
596608
@@ -998,6 +1010,10 @@ The algorithms currently supported include:
9981010
<!-- YAML
9991011
added: v15.0.0
10001012
changes:
1013+
- version: REPLACEME
1014+
pr-url: https://github.com/nodejs/node/pull/62183
1015+
description: TurboSHAKE and KangarooTwelve algorithms
1016+
are now supported.
10011017
- version: v24.7.0
10021018
pr-url: https://github.com/nodejs/node/pull/59365
10031019
description: SHA-3 algorithms are now supported.
@@ -1006,7 +1022,7 @@ changes:
10061022
description: SHAKE algorithms are now supported.
10071023
-->
10081024
1009-
* `algorithm` {string|Algorithm|CShakeParams}
1025+
* `algorithm` {string|Algorithm|CShakeParams|TurboShakeParams|KangarooTwelveParams}
10101026
* `data` {ArrayBuffer|TypedArray|DataView|Buffer}
10111027
* Returns: {Promise} Fulfills with an {ArrayBuffer} upon success.
10121028
@@ -1018,13 +1034,17 @@ If `algorithm` is provided as a {string}, it must be one of:
10181034
10191035
* `'cSHAKE128'`[^modern-algos]
10201036
* `'cSHAKE256'`[^modern-algos]
1037+
* `'KT128'`[^modern-algos]
1038+
* `'KT256'`[^modern-algos]
10211039
* `'SHA-1'`
10221040
* `'SHA-256'`
10231041
* `'SHA-384'`
10241042
* `'SHA-512'`
10251043
* `'SHA3-256'`[^modern-algos]
10261044
* `'SHA3-384'`[^modern-algos]
10271045
* `'SHA3-512'`[^modern-algos]
1046+
* `'TurboSHAKE128'`[^modern-algos]
1047+
* `'TurboSHAKE256'`[^modern-algos]
10281048
10291049
If `algorithm` is provided as an {Object}, it must have a `name` property
10301050
whose value is one of the above.
@@ -2315,6 +2335,38 @@ added: v15.0.0
23152335
23162336
* Type: {string}
23172337
2338+
### Class: `KangarooTwelveParams`
2339+
2340+
<!-- YAML
2341+
added: REPLACEME
2342+
-->
2343+
2344+
#### `kangarooTwelveParams.customization`
2345+
2346+
<!-- YAML
2347+
added: REPLACEME
2348+
-->
2349+
2350+
* Type: {ArrayBuffer|TypedArray|DataView|Buffer|undefined}
2351+
2352+
The optional customization string for KangarooTwelve.
2353+
2354+
#### `kangarooTwelveParams.name`
2355+
2356+
<!-- YAML
2357+
added: REPLACEME
2358+
-->
2359+
2360+
* Type: {string} Must be `'KT128'`[^modern-algos] or `'KT256'`[^modern-algos]
2361+
2362+
#### `kangarooTwelveParams.outputLength`
2363+
2364+
<!-- YAML
2365+
added: REPLACEME
2366+
-->
2367+
2368+
* Type: {number} represents the requested output length in bits.
2369+
23182370
### Class: `KmacImportParams`
23192371
23202372
<!-- YAML
@@ -2685,6 +2737,38 @@ added: v15.0.0
26852737
26862738
The length (in bytes) of the random salt to use.
26872739
2740+
### Class: `TurboShakeParams`
2741+
2742+
<!-- YAML
2743+
added: REPLACEME
2744+
-->
2745+
2746+
#### `turboShakeParams.domainSeparation`
2747+
2748+
<!-- YAML
2749+
added: REPLACEME
2750+
-->
2751+
2752+
* Type: {number|undefined}
2753+
2754+
The optional domain separation byte (0x01-0x7f). Defaults to `0x1f`.
2755+
2756+
#### `turboShakeParams.name`
2757+
2758+
<!-- YAML
2759+
added: REPLACEME
2760+
-->
2761+
2762+
* Type: {string} Must be `'TurboSHAKE128'`[^modern-algos] or `'TurboSHAKE256'`[^modern-algos]
2763+
2764+
#### `turboShakeParams.outputLength`
2765+
2766+
<!-- YAML
2767+
added: REPLACEME
2768+
-->
2769+
2770+
* Type: {number} represents the requested output length in bits.
2771+
26882772
[^secure-curves]: See [Secure Curves in the Web Cryptography API][]
26892773
26902774
[^modern-algos]: See [Modern Algorithms in the Web Cryptography API][]

‎lib/internal/crypto/hash.js‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ const {
1414
Hmac: _Hmac,
1515
kCryptoJobAsync,
1616
oneShotDigest,
17+
TurboShakeJob,
18+
KangarooTwelveJob,
1719
} = internalBinding('crypto');
1820

1921
const {
@@ -226,6 +228,24 @@ async function asyncDigest(algorithm, data) {
226228
normalizeHashName(algorithm.name),
227229
data,
228230
algorithm.outputLength));
231+
case 'TurboSHAKE128':
232+
// Fall through
233+
case 'TurboSHAKE256':
234+
return await jobPromise(() => new TurboShakeJob(
235+
kCryptoJobAsync,
236+
algorithm.name,
237+
algorithm.domainSeparation ?? 0x1f,
238+
algorithm.outputLength / 8,
239+
data));
240+
case 'KT128':
241+
// Fall through
242+
case 'KT256':
243+
return await jobPromise(() => new KangarooTwelveJob(
244+
kCryptoJobAsync,
245+
algorithm.name,
246+
algorithm.customization,
247+
algorithm.outputLength / 8,
248+
data));
229249
}
230250

231251
throw lazyDOMException('Unrecognized algorithm name', 'NotSupportedError');

‎lib/internal/crypto/util.js‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -246,6 +246,10 @@ const kAlgorithmDefinitions = {
246246
},
247247
'cSHAKE128': { 'digest': 'CShakeParams' },
248248
'cSHAKE256': { 'digest': 'CShakeParams' },
249+
'KT128': { 'digest': 'KangarooTwelveParams' },
250+
'KT256': { 'digest': 'KangarooTwelveParams' },
251+
'TurboSHAKE128': { 'digest': 'TurboShakeParams' },
252+
'TurboSHAKE256': { 'digest': 'TurboShakeParams' },
249253
'ECDH': {
250254
'generateKey': 'EcKeyGenParams',
251255
'exportKey': null,
@@ -443,6 +447,10 @@ const experimentalAlgorithms = [
443447
'SHA3-256',
444448
'SHA3-384',
445449
'SHA3-512',
450+
'TurboSHAKE128',
451+
'TurboSHAKE256',
452+
'KT128',
453+
'KT256',
446454
'X448',
447455
];
448456

@@ -515,6 +523,10 @@ const simpleAlgorithmDictionaries = {
515523
KmacParams: {
516524
customization: 'BufferSource',
517525
},
526+
KangarooTwelveParams: {
527+
customization: 'BufferSource',
528+
},
529+
TurboShakeParams: {},
518530
};
519531

520532
function validateMaxBufferLength(data, name) {

‎lib/internal/crypto/webidl.js‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -877,6 +877,52 @@ converters.KmacParams = createDictionaryConverter(
877877
},
878878
]);
879879

880+
converters.KangarooTwelveParams = createDictionaryConverter(
881+
'KangarooTwelveParams', [
882+
...new SafeArrayIterator(dictAlgorithm),
883+
{
884+
key: 'outputLength',
885+
converter: (V, opts) =>
886+
converters['unsigned long'](V, { ...opts, enforceRange: true }),
887+
validator: (V, opts) => {
888+
if (V === 0 || V % 8)
889+
throw lazyDOMException('Invalid KangarooTwelveParams outputLength', 'OperationError');
890+
},
891+
required: true,
892+
},
893+
{
894+
key: 'customization',
895+
converter: converters.BufferSource,
896+
},
897+
]);
898+
899+
converters.TurboShakeParams = createDictionaryConverter(
900+
'TurboShakeParams', [
901+
...new SafeArrayIterator(dictAlgorithm),
902+
{
903+
key: 'outputLength',
904+
converter: (V, opts) =>
905+
converters['unsigned long'](V, { ...opts, enforceRange: true }),
906+
validator: (V, opts) => {
907+
if (V === 0 || V % 8)
908+
throw lazyDOMException('Invalid TurboShakeParams outputLength', 'OperationError');
909+
},
910+
required: true,
911+
},
912+
{
913+
key: 'domainSeparation',
914+
converter: (V, opts) =>
915+
converters.octet(V, { ...opts, enforceRange: true }),
916+
validator: (V) => {
917+
if (V < 0x01 || V > 0x7F) {
918+
throw lazyDOMException(
919+
'TurboShakeParams.domainSeparation must be in range 0x01-0x7f',
920+
'OperationError');
921+
}
922+
},
923+
},
924+
]);
925+
880926
module.exports = {
881927
converters,
882928
requiredArguments,

‎node.gyp‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -388,6 +388,7 @@
388388
'src/crypto/crypto_kem.cc',
389389
'src/crypto/crypto_hmac.cc',
390390
'src/crypto/crypto_kmac.cc',
391+
'src/crypto/crypto_turboshake.cc',
391392
'src/crypto/crypto_random.cc',
392393
'src/crypto/crypto_rsa.cc',
393394
'src/crypto/crypto_spkac.cc',
@@ -406,6 +407,7 @@
406407
'src/crypto/crypto_dh.h',
407408
'src/crypto/crypto_hmac.h',
408409
'src/crypto/crypto_kmac.h',
410+
'src/crypto/crypto_turboshake.h',
409411
'src/crypto/crypto_rsa.h',
410412
'src/crypto/crypto_spkac.h',
411413
'src/crypto/crypto_util.h',

0 commit comments

Comments
 (0)