Skip to content

Commit b505cd5

Browse files
panvaaduh95
authored andcommitted
crypto: support non-byte WebCrypto lengths and cSHAKE
Add shared bit-length helpers for WebCrypto operations that accept bit sequences whose length is not byte-aligned. Use the helpers for cSHAKE output, ECDH-derived bits, HMAC/KMAC key generation/import/derivation, and KMAC sign/verify output. Preserve the requested bit length in CryptoKey algorithm metadata while storing and exporting rounded-up byte material with unused low bits cleared. Keep byte-multiple validation for algorithms whose specs require it. Extend the lower-end of KMAC's key length support. Enable cSHAKE customization and functionName parameters. Signed-off-by: Filip Skokan <panva.ip@gmail.com> PR-URL: #63988 Backport-PR-URL: #64629 Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
1 parent 0f54a87 commit b505cd5

29 files changed

Lines changed: 1389 additions & 146 deletions

‎doc/api/webcrypto.md‎

Lines changed: 21 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1924,26 +1924,39 @@ added: v24.15.0
19241924
19251925
<!-- YAML
19261926
added: v24.7.0
1927+
changes:
1928+
- version: REPLACEME
1929+
pr-url: https://github.com/nodejs/node/pull/63988
1930+
description: Named cSHAKE variants are now accepted.
19271931
-->
19281932
19291933
* Type: {ArrayBuffer|TypedArray|DataView|Buffer|undefined}
19301934
1931-
The `functionName` member represents the function name, used by NIST to define
1932-
functions based on cSHAKE.
1933-
The Node.js Web Crypto API implementation only supports zero-length functionName
1934-
which is equivalent to not providing functionName at all.
1935+
The `functionName` member represents the NIST function-name byte string used to
1936+
domain-separate functions built on top of cSHAKE. Accepted values are:
1937+
1938+
* empty or `undefined`, in which case cSHAKE is equivalent to plain SHAKE
1939+
* the ASCII byte sequence `'KMAC'`
1940+
* the ASCII byte sequence `'TupleHash'`
1941+
* the ASCII byte sequence `'ParallelHash'`
19351942
19361943
#### `cShakeParams.customization`
19371944
19381945
<!-- YAML
19391946
added: v24.7.0
1947+
changes:
1948+
- version: REPLACEME
1949+
pr-url: https://github.com/nodejs/node/pull/63988
1950+
description: Non-empty customization is now supported.
19401951
-->
19411952
19421953
* Type: {ArrayBuffer|TypedArray|DataView|Buffer|undefined}
19431954
1944-
The `customization` member represents the customization string.
1945-
The Node.js Web Crypto API implementation only supports zero-length customization
1946-
which is equivalent to not providing customization at all.
1955+
The `customization` member represents the customization data. Accepted
1956+
values are:
1957+
1958+
* empty or `undefined`, in which case cSHAKE is equivalent to plain SHAKE
1959+
* up to 512 bytes of arbitrary data
19471960
19481961
### Class: `EcdhKeyDeriveParams`
19491962
@@ -2472,9 +2485,7 @@ added: v24.8.0
24722485
added: v24.15.0
24732486
-->
24742487
2475-
* Type: {number}
2476-
2477-
The length of the output in bytes. This must be a positive integer.
2488+
* Type: {number} represents the requested output length in bits.
24782489
24792490