hpke 1.1.7 → 1.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/index.ts CHANGED
@@ -5,7 +5,7 @@
5
5
  * asymmetric key exchange with a symmetric cipher. This was originally defined in an Informational
6
6
  * document on the IRTF stream as [RFC 9180](https://www.rfc-editor.org/rfc/rfc9180.html) and is now
7
7
  * being republished as a Standards Track document of the IETF as
8
- * [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04).
8
+ * [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06).
9
9
  *
10
10
  * HPKE provides a variant of public key encryption for arbitrary-sized plaintexts using a recipient
11
11
  * public key.
@@ -42,7 +42,7 @@
42
42
  // HPKE Context Classes - Sender and Recipient Contexts
43
43
  // ============================================================================
44
44
 
45
- /** @see [ComputeNonce](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.2) */
45
+ /** @see [ComputeNonce](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5.2) */
46
46
  function ComputeNonce(base_nonce: Uint8Array, seq: number, Nn: number): Uint8Array {
47
47
  // Equivalent to xor(base_nonce, I2OSP(seq, Nn)) but avoids allocating the
48
48
  // intermediate seq_bytes array and fuses the two byte-wise passes into one.
@@ -63,7 +63,7 @@ function MaxSeq(Nn: number): number {
63
63
  return Math.min(2 ** (8 * Nn) - 1, Number.MAX_SAFE_INTEGER)
64
64
  }
65
65
 
66
- /** @see [Context.IncrementSeq](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.2) */
66
+ /** @see [Context.IncrementSeq](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5.2) */
67
67
  function IncrementSeq(seq: number, maxSeq: number): number {
68
68
  if (seq >= maxSeq) {
69
69
  throw new MessageLimitReachedError('Sequence number overflow')
@@ -71,7 +71,31 @@ function IncrementSeq(seq: number, maxSeq: number): number {
71
71
  return ++seq
72
72
  }
73
73
 
74
- /** @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.3) */
74
+ /** @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5.3) */
75
+ async function Export_OneStage(
76
+ KDF: KDF,
77
+ suite_id: Uint8Array,
78
+ exporter_secret: Uint8Array,
79
+ exporter_context: Uint8Array,
80
+ L: number,
81
+ ) {
82
+ checkLength(exporter_context, 'Exporter context', MAX_LENGTH_ONE_STAGE)
83
+ return await LabeledDerive(KDF, suite_id, exporter_secret, L_sec, exporter_context, L)
84
+ }
85
+
86
+ /** @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5.3) */
87
+ async function Export_TwoStage(
88
+ KDF: KDF,
89
+ suite_id: Uint8Array,
90
+ exporter_secret: Uint8Array,
91
+ exporter_context: Uint8Array,
92
+ L: number,
93
+ ) {
94
+ checkLength(exporter_context, 'Exporter context', MAX_LENGTH_TWO_STAGE)
95
+ return await LabeledExpand(KDF, suite_id, exporter_secret, L_sec, exporter_context, L)
96
+ }
97
+
98
+ /** @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5.3) */
75
99
  async function ContextExport(
76
100
  suite: Triple,
77
101
  exporterSecret: Uint8Array,
@@ -210,7 +234,7 @@ class SenderContext {
210
234
  *
211
235
  * @returns A Promise that resolves to the ciphertext. The ciphertext is {@link Nt} bytes longer
212
236
  * than the plaintext.
213
- * @see [Context.Seal](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.2)
237
+ * @see [Context.Seal](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5.2)
214
238
  */
215
239
  async Seal(plaintext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array> {
216
240
  checkUint8Array(plaintext, 'plaintext')
@@ -243,6 +267,11 @@ class SenderContext {
243
267
  *
244
268
  * The exported secret is indistinguishable from a uniformly random bitstring of equal length.
245
269
  *
270
+ * HPKE does not provide replay protection. A replayed encapsulated secret produces the same
271
+ * exported secrets. Applications must only use these secrets where repeated values are safe.
272
+ * Deriving AEAD keys and nonces requires a fresh value for each derivation, such as a
273
+ * recipient-provided nonce.
274
+ *
246
275
  * @example
247
276
  *
248
277
  * ```ts
@@ -259,7 +288,7 @@ class SenderContext {
259
288
  * @param length - Desired length of exported secret in bytes
260
289
  *
261
290
  * @returns A Promise that resolves to the exported secret.
262
- * @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.3)
291
+ * @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5.3)
263
292
  */
264
293
  async Export(exporterContext: Uint8Array, length: number): Promise<Uint8Array> {
265
294
  return await ContextExport(
@@ -356,7 +385,7 @@ class RecipientContext {
356
385
  * @param aad - Additional authenticated data
357
386
  *
358
387
  * @returns A Promise that resolves to the decrypted plaintext.
359
- * @see [Context.Open](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.2)
388
+ * @see [Context.Open](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5.2)
360
389
  */
361
390
  async Open(ciphertext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array> {
362
391
  checkUint8Array(ciphertext, 'ciphertext')
@@ -398,6 +427,11 @@ class RecipientContext {
398
427
  *
399
428
  * The exported secret is indistinguishable from a uniformly random bitstring of equal length.
400
429
  *
430
+ * HPKE does not provide replay protection. A replayed encapsulated secret produces the same
431
+ * exported secrets. Applications must only use these secrets where repeated values are safe.
432
+ * Deriving AEAD keys and nonces requires a fresh value for each derivation, such as a
433
+ * recipient-provided nonce.
434
+ *
401
435
  * @example
402
436
  *
403
437
  * ```ts
@@ -414,7 +448,7 @@ class RecipientContext {
414
448
  * @param length - Desired length of exported secret in bytes
415
449
  *
416
450
  * @returns A Promise that resolves to the exported secret.
417
- * @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.3)
451
+ * @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5.3)
418
452
  */
419
453
  async Export(exporterContext: Uint8Array, length: number): Promise<Uint8Array> {
420
454
  return await ContextExport(
@@ -450,7 +484,7 @@ const validate = <T extends { type: string }>(factory: () => T, type: string): T
450
484
  * asymmetric key exchange with a symmetric cipher. This was originally defined in an Informational
451
485
  * document on the IRTF stream as [RFC 9180](https://www.rfc-editor.org/rfc/rfc9180.html) and is now
452
486
  * being republished as a Standards Track document of the IETF as
453
- * [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04).
487
+ * [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06).
454
488
  *
455
489
  * HPKE provides a variant of public key encryption for arbitrary-sized plaintexts using a recipient
456
490
  * public key. It supports two modes:
@@ -521,12 +555,12 @@ export class CipherSuite<K extends Key = Key> {
521
555
  * )
522
556
  * ```
523
557
  *
524
- * @param KEM - KEM implementation factory. Must return an object conforming to the {@link KEM}
525
- * interface.
526
- * @param KDF - KDF implementation factory. Must return an object conforming to the {@link KDF}
527
- * interface.
528
- * @param AEAD - AEAD implementation factory. Must return an object conforming to the {@link AEAD}
529
- * interface.
558
+ * @param KEM - KEM implementation factory. Must return an object conforming to the
559
+ * {@link !KEM KEM} interface.
560
+ * @param KDF - KDF implementation factory. Must return an object conforming to the
561
+ * {@link !KDF KDF} interface.
562
+ * @param AEAD - AEAD implementation factory. Must return an object conforming to the
563
+ * {@link !AEAD AEAD} interface.
530
564
  * @see {@link KEMFactory Available KEMs}
531
565
  * @see {@link KDFFactory Available KDFs}
532
566
  * @see {@link AEADFactory Available AEADs}
@@ -816,6 +850,9 @@ export class CipherSuite<K extends Key = Key> {
816
850
  * Single-shot API for encrypting a single message. It combines context setup and encryption in
817
851
  * one call.
818
852
  *
853
+ * Applications should prefer `options.info` for authenticated information that applies to the
854
+ * whole context, reserving `options.aad` for information specific to the message.
855
+ *
819
856
  * Mode selection:
820
857
  *
821
858
  * - If the options `psk` and `pskId` are omitted: Base mode (unauthenticated)
@@ -844,7 +881,8 @@ export class CipherSuite<K extends Key = Key> {
844
881
  * @returns A Promise that resolves to an object containing the encapsulated secret and
845
882
  * ciphertext. The ciphertext is {@link CipherSuite.AEAD Nt} bytes longer than the plaintext. The
846
883
  * encapsulated secret is {@link CipherSuite.KEM Nenc} bytes.
847
- * @see [Single-Shot Encryption](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-6.1)
884
+ * @see [Single-Shot Encryption](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-6.1)
885
+ * @see [Auxiliary Authenticated Application Information](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-8.1)
848
886
  */
849
887
  async Seal(
850
888
  publicKey: K,
@@ -864,6 +902,9 @@ export class CipherSuite<K extends Key = Key> {
864
902
  *
865
903
  * It combines context setup and decryption in one call.
866
904
  *
905
+ * Applications should prefer `options.info` for authenticated information that applies to the
906
+ * whole context, reserving `options.aad` for information specific to the message.
907
+ *
867
908
  * Mode selection:
868
909
  *
869
910
  * - If the options `psk` and `pskId` are omitted: Base mode (unauthenticated)
@@ -893,7 +934,8 @@ export class CipherSuite<K extends Key = Key> {
893
934
  * @param options.pskId - Pre-shared key identifier (for PSK mode)
894
935
  *
895
936
  * @returns A Promise that resolves to the decrypted plaintext.
896
- * @see [Single-Shot Decryption](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-6.1)
937
+ * @see [Single-Shot Decryption](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-6.1)
938
+ * @see [Auxiliary Authenticated Application Information](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-8.1)
897
939
  */
898
940
  async Open(
899
941
  privateKey: K | KeyPair<K>,
@@ -913,8 +955,16 @@ export class CipherSuite<K extends Key = Key> {
913
955
  *
914
956
  * It combines context setup and secret export in one call.
915
957
  *
958
+ * Applications should prefer `options.info` for authenticated information that applies to the
959
+ * whole context, reserving `exporterContext` for information specific to the exported secret.
960
+ *
916
961
  * The exported secret is indistinguishable from a uniformly random bitstring of equal length.
917
962
  *
963
+ * HPKE does not provide replay protection. A replayed encapsulated secret produces the same
964
+ * exported secrets. Applications must only use these secrets where repeated values are safe.
965
+ * Deriving AEAD keys and nonces requires a fresh value for each derivation, such as a
966
+ * recipient-provided nonce.
967
+ *
918
968
  * @category Single-Shot APIs
919
969
  * @example
920
970
  *
@@ -941,7 +991,8 @@ export class CipherSuite<K extends Key = Key> {
941
991
  *
942
992
  * @returns A Promise that resolves to an object containing the encapsulated secret and the
943
993
  * exported secret.
944
- * @see [Single-Shot Secret Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-6.2)
994
+ * @see [Single-Shot Secret Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-6.2)
995
+ * @see [Auxiliary Authenticated Application Information](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-8.1)
945
996
  */
946
997
  async SendExport(
947
998
  publicKey: K,
@@ -959,6 +1010,14 @@ export class CipherSuite<K extends Key = Key> {
959
1010
  *
960
1011
  * It combines context setup and secret export in one call.
961
1012
  *
1013
+ * Applications should prefer `options.info` for authenticated information that applies to the
1014
+ * whole context, reserving `exporterContext` for information specific to the exported secret.
1015
+ *
1016
+ * HPKE does not provide replay protection. A replayed encapsulated secret produces the same
1017
+ * exported secrets. Applications must only use these secrets where repeated values are safe.
1018
+ * Deriving AEAD keys and nonces requires a fresh value for each derivation, such as a
1019
+ * recipient-provided nonce.
1020
+ *
962
1021
  * @category Single-Shot APIs
963
1022
  * @example
964
1023
  *
@@ -989,7 +1048,8 @@ export class CipherSuite<K extends Key = Key> {
989
1048
  * @param options.pskId - Pre-shared key identifier (for PSK mode)
990
1049
  *
991
1050
  * @returns A Promise that resolves to the exported secret.
992
- * @see [Single-Shot Secret Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-6.2)
1051
+ * @see [Single-Shot Secret Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-6.2)
1052
+ * @see [Auxiliary Authenticated Application Information](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-8.1)
993
1053
  */
994
1054
  async ReceiveExport(
995
1055
  privateKey: K | KeyPair<K>,
@@ -1043,7 +1103,7 @@ export class CipherSuite<K extends Key = Key> {
1043
1103
  *
1044
1104
  * @returns A Promise that resolves to an object containing the encapsulated secret and the sender
1045
1105
  * context (`ctx`). The encapsulated secret is {@link CipherSuite.KEM Nenc} bytes.
1046
- * @see [SetupBaseS / SetupPSKS](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.1.1)
1106
+ * @see [SetupBaseS / SetupPSKS](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5.1.1)
1047
1107
  */
1048
1108
  async SetupSender(
1049
1109
  publicKey: K,
@@ -1124,7 +1184,7 @@ export class CipherSuite<K extends Key = Key> {
1124
1184
  * @param options.pskId - Pre-shared key identifier (for PSK mode)
1125
1185
  *
1126
1186
  * @returns A Promise that resolves to the recipient context.
1127
- * @see [SetupBaseR / SetupPSKR](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.1.1)
1187
+ * @see [SetupBaseR / SetupPSKR](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5.1.1)
1128
1188
  */
1129
1189
  async SetupRecipient(
1130
1190
  privateKey: K | KeyPair<K>,
@@ -1311,7 +1371,7 @@ interface Triple<K extends Key = Key> {
1311
1371
  * Base mode provides encryption to a public key without sender authentication. The recipient cannot
1312
1372
  * verify who encrypted the message, only that someone with access to their public key did.
1313
1373
  *
1314
- * @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5)
1374
+ * @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5)
1315
1375
  */
1316
1376
  export const MODE_BASE = 0x00
1317
1377
 
@@ -1322,7 +1382,7 @@ export const MODE_BASE = 0x00
1322
1382
  * sender and recipient must possess the same PSK and PSK ID. This provides implicit sender
1323
1383
  * authentication.
1324
1384
  *
1325
- * @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5)
1385
+ * @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5)
1326
1386
  */
1327
1387
  export const MODE_PSK = 0x01
1328
1388
 
@@ -1533,6 +1593,38 @@ export function encode(string: string): Uint8Array {
1533
1593
  return bytes
1534
1594
  }
1535
1595
 
1596
+ /**
1597
+ * Integer to Octet String Primitive (I2OSP) as defined in RFC 8017. Converts a non-negative integer
1598
+ * into a byte string of specified length. It's exported for use in custom KEM, KDF, or AEAD
1599
+ * implementations.
1600
+ *
1601
+ * @param n - Non-negative safe integer to convert
1602
+ * @param w - Desired length of output in bytes
1603
+ *
1604
+ * @returns A Uint8Array of length w containing the big-endian representation of n
1605
+ * @group Utilities
1606
+ * @see [I2OSP](https://www.rfc-editor.org/rfc/rfc8017#section-4.1)
1607
+ */
1608
+ export function I2OSP(n: number, w: number): Uint8Array {
1609
+ if (!Number.isSafeInteger(w) || w <= 0) {
1610
+ throw new Error('w must be a positive safe integer')
1611
+ }
1612
+ if (!Number.isSafeInteger(n) || n < 0) {
1613
+ throw new Error('n must be a non-negative safe integer')
1614
+ }
1615
+ const max = Math.pow(256, w)
1616
+ if (n >= max) {
1617
+ throw new Error('n too large to fit in w-length byte string')
1618
+ }
1619
+ const ret = new Uint8Array(w)
1620
+ let num = n
1621
+ for (let i = 0; i < w && num; i++) {
1622
+ ret[w - (i + 1)] = num % 256
1623
+ num = Math.floor(num / 256)
1624
+ }
1625
+ return ret
1626
+ }
1627
+
1536
1628
  // Module-level cached encodings of static ASCII labels used on HPKE hot paths.
1537
1629
  // Each is a freshly-allocated Uint8Array held as a constant to avoid repeating
1538
1630
  // the per-call `encode()` validation+allocation loop. These are only ever read
@@ -1560,88 +1652,13 @@ function lengthPrefixed(x: Uint8Array): Uint8Array {
1560
1652
  }
1561
1653
 
1562
1654
  // ============================================================================
1563
- // KDF (Key Derivation Function) - Helper Functions
1655
+ // Input Validation
1564
1656
  // ============================================================================
1565
1657
 
1566
- /**
1567
- * Performs labeled key derivation for one-stage KDFs.
1568
- *
1569
- * This function implements the LabeledDerive operation as specified in the HPKE specification for
1570
- * use with one-stage KDFs. It constructs a labeled input by concatenating:
1571
- *
1572
- * - The input keying material (`ikm`)
1573
- * - The version string "HPKE-v1"
1574
- * - The suite identifier (`suite_id`)
1575
- * - A length-prefixed label
1576
- * - The desired output length as a 2-byte encoding
1577
- * - Additional context
1578
- *
1579
- * The labeled input is then passed to the KDF's Derive function to produce L bytes of output. This
1580
- * ensures domain separation between different uses of the KDF in HPKE.
1581
- *
1582
- * @group Utilities
1583
- * @see [LabeledDerive](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
1584
- */
1585
- export async function LabeledDerive(
1586
- KDF: Pick<KDF, 'Derive'>,
1587
- suite_id: Uint8Array,
1588
- ikm: Uint8Array,
1589
- label: Uint8Array,
1590
- context: Uint8Array,
1591
- L: number,
1592
- ): Promise<Uint8Array> {
1593
- const labeled_ikm = concat(ikm, L_HPKE_v1, suite_id, lengthPrefixed(label), I2OSP(L, 2), context)
1594
- return await KDF.Derive(labeled_ikm, L)
1595
- }
1596
-
1597
- /** @see [Export_OneStage](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5) */
1598
- async function Export_OneStage(
1599
- KDF: KDF,
1600
- suite_id: Uint8Array,
1601
- exporter_secret: Uint8Array,
1602
- exporter_context: Uint8Array,
1603
- L: number,
1604
- ) {
1605
- checkLength(exporter_context, 'Exporter context', MAX_LENGTH_ONE_STAGE)
1606
- return await LabeledDerive(KDF, suite_id, exporter_secret, L_sec, exporter_context, L)
1607
- }
1608
-
1609
- /** @see [CombineSecrets_OneStage](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5) */
1610
- async function CombineSecrets_OneStage(
1611
- suite: Triple,
1612
- mode: number,
1613
- shared_secret: Uint8Array,
1614
- info: Uint8Array,
1615
- psk: Uint8Array,
1616
- psk_id: Uint8Array,
1617
- ) {
1618
- checkLength(psk, 'PSK', MAX_LENGTH_ONE_STAGE)
1619
- checkLength(psk_id, 'PSK ID', MAX_LENGTH_ONE_STAGE)
1620
- checkLength(info, 'Info', MAX_LENGTH_ONE_STAGE)
1621
-
1622
- const secrets = concat(lengthPrefixed(psk), lengthPrefixed(shared_secret))
1623
- const context = concat(I2OSP(mode, 1), lengthPrefixed(psk_id), lengthPrefixed(info))
1624
-
1625
- const secret = await LabeledDerive(
1626
- suite.KDF,
1627
- suite.id,
1628
- secrets,
1629
- L_secret,
1630
- context,
1631
- suite.AEAD.Nk + suite.AEAD.Nn + suite.KDF.Nh,
1632
- )
1633
-
1634
- const key = slice(secret, 0, suite.AEAD.Nk)
1635
- const base_nonce = slice(secret, suite.AEAD.Nk, suite.AEAD.Nk + suite.AEAD.Nn)
1636
- const exporter_secret = slice(secret, suite.AEAD.Nk + suite.AEAD.Nn)
1637
-
1638
- return { key, base_nonce, exporter_secret }
1639
- }
1640
-
1641
- // Two-stage KDF input length limits (0xffff = 65535 bytes)
1642
- // this is an actual limit for One-Stage KDF
1658
+ // Apply a 65535-byte implementation limit to two-stage KDF inputs.
1643
1659
  const MAX_LENGTH_TWO_STAGE = 0xffff
1644
- // that is also applied to Two-Stage KDF for consistency
1660
+ // One-stage length-prefixed PSK, PSK ID, and info inputs are limited to 65535 bytes.
1661
+ // Apply the same bound to one-stage exporter contexts as an implementation limit.
1645
1662
  const MAX_LENGTH_ONE_STAGE = 0xffff
1646
1663
 
1647
1664
  function checkLength(data: Uint8Array, name: string, maxLength: number) {
@@ -1663,60 +1680,9 @@ function checkExtractable(extractable: unknown): asserts extractable is boolean
1663
1680
  }
1664
1681
  }
1665
1682
 
1666
- /** @see [KeySchedule (CombineSecrets)](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.1) */
1667
- async function CombineSecrets_TwoStage(
1668
- suite: Triple,
1669
- mode: number,
1670
- shared_secret: Uint8Array,
1671
- info: Uint8Array,
1672
- psk: Uint8Array,
1673
- psk_id: Uint8Array,
1674
- ) {
1675
- checkLength(psk, 'PSK', MAX_LENGTH_TWO_STAGE)
1676
- checkLength(psk_id, 'PSK ID', MAX_LENGTH_TWO_STAGE)
1677
- checkLength(info, 'Info', MAX_LENGTH_TWO_STAGE)
1678
-
1679
- const [psk_id_hash, info_hash] = await Promise.all([
1680
- LabeledExtract(suite.KDF, suite.id, new Uint8Array(), L_psk_id_hash, psk_id),
1681
- LabeledExtract(suite.KDF, suite.id, new Uint8Array(), L_info_hash, info),
1682
- ])
1683
-
1684
- const key_schedule_context = concat(I2OSP(mode, 1), psk_id_hash, info_hash)
1685
- const secret = await LabeledExtract(suite.KDF, suite.id, shared_secret, L_secret, psk)
1686
-
1687
- // For export-only AEAD, we only need the exporter_secret
1688
- if (suite.AEAD.id === EXPORT_ONLY) {
1689
- const exporter_secret = await LabeledExpand(
1690
- suite.KDF,
1691
- suite.id,
1692
- secret,
1693
- L_exp,
1694
- key_schedule_context,
1695
- suite.KDF.Nh,
1696
- )
1697
- return { key: new Uint8Array(), base_nonce: new Uint8Array(), exporter_secret }
1698
- }
1699
-
1700
- const [key, base_nonce, exporter_secret] = await Promise.all([
1701
- LabeledExpand(suite.KDF, suite.id, secret, L_key, key_schedule_context, suite.AEAD.Nk),
1702
- LabeledExpand(suite.KDF, suite.id, secret, L_base_nonce, key_schedule_context, suite.AEAD.Nn),
1703
- LabeledExpand(suite.KDF, suite.id, secret, L_exp, key_schedule_context, suite.KDF.Nh),
1704
- ])
1705
-
1706
- return { key, base_nonce, exporter_secret }
1707
- }
1708
-
1709
- /** @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.3) */
1710
- async function Export_TwoStage(
1711
- KDF: KDF,
1712
- suite_id: Uint8Array,
1713
- exporter_secret: Uint8Array,
1714
- exporter_context: Uint8Array,
1715
- L: number,
1716
- ) {
1717
- checkLength(exporter_context, 'Exporter context', MAX_LENGTH_TWO_STAGE)
1718
- return await LabeledExpand(KDF, suite_id, exporter_secret, L_sec, exporter_context, L)
1719
- }
1683
+ // ============================================================================
1684
+ // KDF (Key Derivation Function) - Types and Interfaces
1685
+ // ============================================================================
1720
1686
 
1721
1687
  /**
1722
1688
  * Key Derivation Function (KDF) implementation interface.
@@ -1737,6 +1703,9 @@ async function Export_TwoStage(
1737
1703
  * - Two-stage KDFs only implement {@link Extract} and {@link Expand}. The {@link Derive} method will not
1738
1704
  * be called and may be a no-op implementation.
1739
1705
  *
1706
+ * Custom KDF implementations must also meet the [KDF security
1707
+ * requirements](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-9.3).
1708
+ *
1740
1709
  * @example
1741
1710
  *
1742
1711
  * ```ts
@@ -1783,7 +1752,7 @@ async function Export_TwoStage(
1783
1752
  * )
1784
1753
  * ```
1785
1754
  *
1786
- * @see [HPKE Key Derivation Functions](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.2)
1755
+ * @see [HPKE Key Derivation Functions](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-4.2)
1787
1756
  */
1788
1757
  export interface KDF {
1789
1758
  /** KDF algorithm identifier */
@@ -1838,9 +1807,40 @@ export interface KDF {
1838
1807
  }
1839
1808
 
1840
1809
  // ============================================================================
1841
- // KDF (Key Derivation Function) - Labeled Extract/Expand Functions
1810
+ // KDF (Key Derivation Function) - Labeled Derivation Functions
1842
1811
  // ============================================================================
1843
1812
 
1813
+ /**
1814
+ * Performs labeled key derivation for one-stage KDFs.
1815
+ *
1816
+ * This function implements the LabeledDerive operation as specified in the HPKE specification for
1817
+ * use with one-stage KDFs. It constructs a labeled input by concatenating:
1818
+ *
1819
+ * - The input keying material (`ikm`)
1820
+ * - The version string "HPKE-v1"
1821
+ * - The suite identifier (`suite_id`)
1822
+ * - A length-prefixed label
1823
+ * - The desired output length as a 2-byte encoding
1824
+ * - Additional context
1825
+ *
1826
+ * The labeled input is then passed to the KDF's Derive function to produce L bytes of output. This
1827
+ * ensures domain separation between different uses of the KDF in HPKE.
1828
+ *
1829
+ * @group Utilities
1830
+ * @see [LabeledDerive](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-4.4)
1831
+ */
1832
+ export async function LabeledDerive(
1833
+ KDF: Pick<KDF, 'Derive'>,
1834
+ suite_id: Uint8Array,
1835
+ ikm: Uint8Array,
1836
+ label: Uint8Array,
1837
+ context: Uint8Array,
1838
+ L: number,
1839
+ ): Promise<Uint8Array> {
1840
+ const labeled_ikm = concat(ikm, L_HPKE_v1, suite_id, lengthPrefixed(label), I2OSP(L, 2), context)
1841
+ return await KDF.Derive(labeled_ikm, L)
1842
+ }
1843
+
1844
1844
  /**
1845
1845
  * Performs labeled extraction for two-stage KDFs.
1846
1846
  *
@@ -1856,7 +1856,7 @@ export interface KDF {
1856
1856
  * pseudorandom key. This ensures domain separation between different uses of the KDF in HPKE.
1857
1857
  *
1858
1858
  * @group Utilities
1859
- * @see [LabeledExtract](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.4)
1859
+ * @see [LabeledExtract](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-4.4)
1860
1860
  */
1861
1861
  export async function LabeledExtract(
1862
1862
  KDF: Pick<KDF, 'Extract'>,
@@ -1886,7 +1886,7 @@ export async function LabeledExtract(
1886
1886
  * of the KDF in HPKE.
1887
1887
  *
1888
1888
  * @group Utilities
1889
- * @see [LabeledExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.4)
1889
+ * @see [LabeledExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-4.4)
1890
1890
  */
1891
1891
  export async function LabeledExpand(
1892
1892
  KDF: Pick<KDF, 'Expand'>,
@@ -1996,7 +1996,7 @@ export async function LabeledExpand(
1996
1996
  * ```
1997
1997
  *
1998
1998
  * @typeParam K - Key representation produced and consumed by the KEM
1999
- * @see [HPKE Key Encapsulation Mechanisms](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.1)
1999
+ * @see [HPKE Key Encapsulation Mechanisms](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-4.1)
2000
2000
  */
2001
2001
  export interface KEM<K extends Key = Key> {
2002
2002
  /** KEM algorithm identifier */
@@ -2198,7 +2198,7 @@ function isKey(key: unknown, type: string, extractable?: boolean): asserts key i
2198
2198
  * )
2199
2199
  * ```
2200
2200
  *
2201
- * @see [HPKE AEAD Encryption Algorithm](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.3)
2201
+ * @see [HPKE AEAD Encryption Algorithm](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-4.3)
2202
2202
  */
2203
2203
  export interface AEAD {
2204
2204
  /** AEAD algorithm identifier */
@@ -2233,7 +2233,7 @@ export interface AEAD {
2233
2233
  * @param pt - Plaintext to encrypt
2234
2234
  *
2235
2235
  * @returns A promise resolving to the ciphertext with authentication tag appended
2236
- * @see [Context.Seal P_MAX handling](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.2)
2236
+ * @see [Context.Seal P_MAX handling](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5.2)
2237
2237
  */
2238
2238
  Seal(key: Uint8Array, nonce: Uint8Array, aad: Uint8Array, pt: Uint8Array): Promise<Uint8Array>
2239
2239
 
@@ -2254,38 +2254,6 @@ export interface AEAD {
2254
2254
  // HPKE Core Functions - Key Schedule
2255
2255
  // ============================================================================
2256
2256
 
2257
- /**
2258
- * Integer to Octet String Primitive (I2OSP) as defined in RFC 8017. Converts a non-negative integer
2259
- * into a byte string of specified length. It's exported for use in custom KEM, KDF, or AEAD
2260
- * implementations.
2261
- *
2262
- * @param n - Non-negative safe integer to convert
2263
- * @param w - Desired length of output in bytes
2264
- *
2265
- * @returns A Uint8Array of length w containing the big-endian representation of n
2266
- * @group Utilities
2267
- * @see [I2OSP](https://www.rfc-editor.org/rfc/rfc8017#section-4.1)
2268
- */
2269
- export function I2OSP(n: number, w: number): Uint8Array {
2270
- if (!Number.isSafeInteger(w) || w <= 0) {
2271
- throw new Error('w must be a positive safe integer')
2272
- }
2273
- if (!Number.isSafeInteger(n) || n < 0) {
2274
- throw new Error('n must be a non-negative safe integer')
2275
- }
2276
- const max = Math.pow(256, w)
2277
- if (n >= max) {
2278
- throw new Error('n too large to fit in w-length byte string')
2279
- }
2280
- const ret = new Uint8Array(w)
2281
- let num = n
2282
- for (let i = 0; i < w && num; i++) {
2283
- ret[w - (i + 1)] = num % 256
2284
- num = Math.floor(num / 256)
2285
- }
2286
- return ret
2287
- }
2288
-
2289
2257
  function KDFStages(KDF: KDF): 1 | 2 {
2290
2258
  if (KDF.stages === 1 || KDF.stages === 2) {
2291
2259
  return KDF.stages
@@ -2294,7 +2262,82 @@ function KDFStages(KDF: KDF): 1 | 2 {
2294
2262
  throw new Error('unreachable')
2295
2263
  }
2296
2264
 
2297
- /** @see [KeySchedule](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.1) */
2265
+ /** @see [CombineSecrets](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5.1) */
2266
+ async function CombineSecrets_OneStage(
2267
+ suite: Triple,
2268
+ mode: number,
2269
+ shared_secret: Uint8Array,
2270
+ info: Uint8Array,
2271
+ psk: Uint8Array,
2272
+ psk_id: Uint8Array,
2273
+ ) {
2274
+ checkLength(psk, 'PSK', MAX_LENGTH_ONE_STAGE)
2275
+ checkLength(psk_id, 'PSK ID', MAX_LENGTH_ONE_STAGE)
2276
+ checkLength(info, 'Info', MAX_LENGTH_ONE_STAGE)
2277
+
2278
+ const secrets = concat(lengthPrefixed(psk), lengthPrefixed(shared_secret))
2279
+ const context = concat(I2OSP(mode, 1), lengthPrefixed(psk_id), lengthPrefixed(info))
2280
+
2281
+ const secret = await LabeledDerive(
2282
+ suite.KDF,
2283
+ suite.id,
2284
+ secrets,
2285
+ L_secret,
2286
+ context,
2287
+ suite.AEAD.Nk + suite.AEAD.Nn + suite.KDF.Nh,
2288
+ )
2289
+
2290
+ const key = slice(secret, 0, suite.AEAD.Nk)
2291
+ const base_nonce = slice(secret, suite.AEAD.Nk, suite.AEAD.Nk + suite.AEAD.Nn)
2292
+ const exporter_secret = slice(secret, suite.AEAD.Nk + suite.AEAD.Nn)
2293
+
2294
+ return { key, base_nonce, exporter_secret }
2295
+ }
2296
+
2297
+ /** @see [CombineSecrets](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5.1) */
2298
+ async function CombineSecrets_TwoStage(
2299
+ suite: Triple,
2300
+ mode: number,
2301
+ shared_secret: Uint8Array,
2302
+ info: Uint8Array,
2303
+ psk: Uint8Array,
2304
+ psk_id: Uint8Array,
2305
+ ) {
2306
+ checkLength(psk, 'PSK', MAX_LENGTH_TWO_STAGE)
2307
+ checkLength(psk_id, 'PSK ID', MAX_LENGTH_TWO_STAGE)
2308
+ checkLength(info, 'Info', MAX_LENGTH_TWO_STAGE)
2309
+
2310
+ const [psk_id_hash, info_hash] = await Promise.all([
2311
+ LabeledExtract(suite.KDF, suite.id, new Uint8Array(), L_psk_id_hash, psk_id),
2312
+ LabeledExtract(suite.KDF, suite.id, new Uint8Array(), L_info_hash, info),
2313
+ ])
2314
+
2315
+ const key_schedule_context = concat(I2OSP(mode, 1), psk_id_hash, info_hash)
2316
+ const secret = await LabeledExtract(suite.KDF, suite.id, shared_secret, L_secret, psk)
2317
+
2318
+ // For export-only AEAD, we only need the exporter_secret
2319
+ if (suite.AEAD.id === EXPORT_ONLY) {
2320
+ const exporter_secret = await LabeledExpand(
2321
+ suite.KDF,
2322
+ suite.id,
2323
+ secret,
2324
+ L_exp,
2325
+ key_schedule_context,
2326
+ suite.KDF.Nh,
2327
+ )
2328
+ return { key: new Uint8Array(), base_nonce: new Uint8Array(), exporter_secret }
2329
+ }
2330
+
2331
+ const [key, base_nonce, exporter_secret] = await Promise.all([
2332
+ LabeledExpand(suite.KDF, suite.id, secret, L_key, key_schedule_context, suite.AEAD.Nk),
2333
+ LabeledExpand(suite.KDF, suite.id, secret, L_base_nonce, key_schedule_context, suite.AEAD.Nn),
2334
+ LabeledExpand(suite.KDF, suite.id, secret, L_exp, key_schedule_context, suite.KDF.Nh),
2335
+ ])
2336
+
2337
+ return { key, base_nonce, exporter_secret }
2338
+ }
2339
+
2340
+ /** @see [KeySchedule](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5.1) */
2298
2341
  async function KeySchedule(
2299
2342
  suite: Triple,
2300
2343
  mode: number,
@@ -2317,7 +2360,7 @@ async function KeySchedule(
2317
2360
  return await CombineSecrets(suite, mode, shared_secret, info, psk, pskId)
2318
2361
  }
2319
2362
 
2320
- /** @see [VerifyPSKInputs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.1) */
2363
+ /** @see [VerifyPSKInputs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5.1) */
2321
2364
  function VerifyPSKInputs(psk: Uint8Array, psk_id: Uint8Array) {
2322
2365
  if (psk.byteLength && psk_id.byteLength) {
2323
2366
  if (psk.byteLength < 32) {
@@ -2349,7 +2392,7 @@ const CHACHA20_POLY1305_P_MAX = 2 ** 38 - 64
2349
2392
  * This is a factory function that must be passed to the {@link CipherSuite} constructor.
2350
2393
  *
2351
2394
  * @group AEAD Algorithms
2352
- * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.3)
2395
+ * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.3)
2353
2396
  */
2354
2397
  export const AEAD_EXPORT_ONLY: AEADFactory = function (): AEAD {
2355
2398
  return {
@@ -2492,7 +2535,7 @@ function HKDF_SHARED(): KDF_BASE {
2492
2535
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2493
2536
  *
2494
2537
  * @group KDF Algorithms
2495
- * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.2)
2538
+ * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.2)
2496
2539
  */
2497
2540
  export const KDF_HKDF_SHA256: KDFFactory = function (): HKDF {
2498
2541
  return { id: 0x0001, type: 'KDF', name: 'HKDF-SHA256', Nh: 32, hash: 'SHA-256', ...HKDF_SHARED() }
@@ -2515,7 +2558,7 @@ export const KDF_HKDF_SHA256: KDFFactory = function (): HKDF {
2515
2558
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2516
2559
  *
2517
2560
  * @group KDF Algorithms
2518
- * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.2)
2561
+ * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.2)
2519
2562
  */
2520
2563
  export const KDF_HKDF_SHA384: KDFFactory = function (): HKDF {
2521
2564
  return { id: 0x0002, type: 'KDF', name: 'HKDF-SHA384', Nh: 48, hash: 'SHA-384', ...HKDF_SHARED() }
@@ -2538,7 +2581,7 @@ export const KDF_HKDF_SHA384: KDFFactory = function (): HKDF {
2538
2581
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2539
2582
  *
2540
2583
  * @group KDF Algorithms
2541
- * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.2)
2584
+ * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.2)
2542
2585
  */
2543
2586
  export const KDF_HKDF_SHA512: KDFFactory = function (): HKDF {
2544
2587
  return { id: 0x0003, type: 'KDF', name: 'HKDF-SHA512', Nh: 64, hash: 'SHA-512', ...HKDF_SHARED() }
@@ -2586,7 +2629,7 @@ function SHAKE_SHARED(): KDF_BASE {
2586
2629
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2587
2630
  *
2588
2631
  * @group KDF Algorithms
2589
- * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
2632
+ * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05#section-5)
2590
2633
  */
2591
2634
  export const KDF_SHAKE128: KDFFactory = function (): SHAKE {
2592
2635
  return {
@@ -2616,7 +2659,7 @@ export const KDF_SHAKE128: KDFFactory = function (): SHAKE {
2616
2659
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2617
2660
  *
2618
2661
  * @group KDF Algorithms
2619
- * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
2662
+ * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05#section-5)
2620
2663
  */
2621
2664
  export const KDF_SHAKE256: KDFFactory = function (): SHAKE {
2622
2665
  return {
@@ -2646,7 +2689,7 @@ export const KDF_SHAKE256: KDFFactory = function (): SHAKE {
2646
2689
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2647
2690
  *
2648
2691
  * @group KDF Algorithms
2649
- * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
2692
+ * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05#section-5)
2650
2693
  */
2651
2694
  export const KDF_TurboSHAKE128: KDFFactory = function (): SHAKE {
2652
2695
  return {
@@ -2676,7 +2719,7 @@ export const KDF_TurboSHAKE128: KDFFactory = function (): SHAKE {
2676
2719
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2677
2720
  *
2678
2721
  * @group KDF Algorithms
2679
- * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
2722
+ * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05#section-5)
2680
2723
  */
2681
2724
  export const KDF_TurboSHAKE256: KDFFactory = function (): SHAKE {
2682
2725
  return {
@@ -2771,7 +2814,7 @@ function b64u(input: string): Uint8Array {
2771
2814
  // KEM (Key Encapsulation Mechanism) - DHKEM Helper Functions
2772
2815
  // ============================================================================
2773
2816
 
2774
- /** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1.3) */
2817
+ /** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.1.3) */
2775
2818
  async function DeriveKeyPairBytes(
2776
2819
  DHKEM: DHKEM,
2777
2820
  ikm: Uint8Array,
@@ -2828,7 +2871,7 @@ function assertCryptoKey(key: Key): asserts key is CryptoKey {
2828
2871
  }
2829
2872
  }
2830
2873
 
2831
- /** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.5) */
2874
+ /** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-4.5) */
2832
2875
  async function ExtractAndExpand_OneStage(
2833
2876
  DHKEM: DHKEM,
2834
2877
  dh: Uint8Array,
@@ -2844,7 +2887,7 @@ async function ExtractAndExpand_OneStage(
2844
2887
  )
2845
2888
  }
2846
2889
 
2847
- /** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.5) */
2890
+ /** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-4.5) */
2848
2891
  async function ExtractAndExpand_TwoStage(
2849
2892
  DHKEM: DHKEM,
2850
2893
  dh: Uint8Array,
@@ -2861,7 +2904,7 @@ async function ExtractAndExpand_TwoStage(
2861
2904
  )
2862
2905
  }
2863
2906
 
2864
- /** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.5) */
2907
+ /** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-4.5) */
2865
2908
  async function ExtractAndExpand(
2866
2909
  DHKEM: DHKEM,
2867
2910
  dh: Uint8Array,
@@ -3119,7 +3162,7 @@ async function DeserializePrivateKeyNist(
3119
3162
  return (await importKeyNist(this, key, this.name, extractable, false)).privateKey
3120
3163
  }
3121
3164
 
3122
- /** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1.3) */
3165
+ /** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.1.3) */
3123
3166
  async function DeriveKeyPairNist(
3124
3167
  this: DHKEM & NistCurveConfig,
3125
3168
  ikm: Uint8Array,
@@ -3154,7 +3197,7 @@ async function GetKeyPairNist(
3154
3197
  // KEM (Key Encapsulation Mechanism) - DHKEM X Curve Implementations
3155
3198
  // ============================================================================
3156
3199
 
3157
- /** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1.3) */
3200
+ /** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.1.3) */
3158
3201
  async function DeriveKeyPairX(this: DHKEM, ikm: Uint8Array, extractable: boolean) {
3159
3202
  const sk = await DeriveKeyPairBytes(this, ikm, L_sk, new Uint8Array())
3160
3203
  return await createKeyPairFromPrivateKey(this, sk, extractable)
@@ -3194,7 +3237,7 @@ const P256: NistCurveConfig = {
3194
3237
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3195
3238
  *
3196
3239
  * @group KEM Algorithms
3197
- * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
3240
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.1)
3198
3241
  */
3199
3242
  export const KEM_DHKEM_P256_HKDF_SHA256: KEMFactory<CryptoKey> = function (): DHKEM &
3200
3243
  NistCurveConfig {
@@ -3250,7 +3293,7 @@ const P384: NistCurveConfig = {
3250
3293
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3251
3294
  *
3252
3295
  * @group KEM Algorithms
3253
- * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
3296
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.1)
3254
3297
  */
3255
3298
  export const KEM_DHKEM_P384_HKDF_SHA384: KEMFactory<CryptoKey> = function (): DHKEM &
3256
3299
  NistCurveConfig {
@@ -3306,7 +3349,7 @@ const P521: NistCurveConfig = {
3306
3349
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3307
3350
  *
3308
3351
  * @group KEM Algorithms
3309
- * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
3352
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.1)
3310
3353
  */
3311
3354
  export const KEM_DHKEM_P521_HKDF_SHA512: KEMFactory<CryptoKey> = function (): DHKEM &
3312
3355
  NistCurveConfig {
@@ -3353,7 +3396,7 @@ export const KEM_DHKEM_P521_HKDF_SHA512: KEMFactory<CryptoKey> = function (): DH
3353
3396
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3354
3397
  *
3355
3398
  * @group KEM Algorithms
3356
- * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
3399
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.1)
3357
3400
  */
3358
3401
  export const KEM_DHKEM_X25519_HKDF_SHA256: KEMFactory<CryptoKey> = function (): DHKEM & {
3359
3402
  pkcs8: Uint8Array
@@ -3402,7 +3445,7 @@ export const KEM_DHKEM_X25519_HKDF_SHA256: KEMFactory<CryptoKey> = function ():
3402
3445
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3403
3446
  *
3404
3447
  * @group KEM Algorithms
3405
- * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
3448
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.1)
3406
3449
  */
3407
3450
  export const KEM_DHKEM_X448_HKDF_SHA512: KEMFactory<CryptoKey> = function (): DHKEM & {
3408
3451
  pkcs8: Uint8Array
@@ -3574,7 +3617,7 @@ function createDirectKEM({ id, name, Nsecret, Nenc, Npk, Nsk }: KEMParams): Dire
3574
3617
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3575
3618
  *
3576
3619
  * @group KEM Algorithms
3577
- * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-3)
3620
+ * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05#section-3)
3578
3621
  */
3579
3622
  export const KEM_ML_KEM_512: KEMFactory<CryptoKey> = function (): DirectKEM {
3580
3623
  const id = 0x0040
@@ -3603,7 +3646,7 @@ export const KEM_ML_KEM_512: KEMFactory<CryptoKey> = function (): DirectKEM {
3603
3646
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3604
3647
  *
3605
3648
  * @group KEM Algorithms
3606
- * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-3)
3649
+ * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05#section-3)
3607
3650
  */
3608
3651
  export const KEM_ML_KEM_768: KEMFactory<CryptoKey> = function (): DirectKEM {
3609
3652
  const id = 0x0041
@@ -3632,7 +3675,7 @@ export const KEM_ML_KEM_768: KEMFactory<CryptoKey> = function (): DirectKEM {
3632
3675
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3633
3676
  *
3634
3677
  * @group KEM Algorithms
3635
- * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-3)
3678
+ * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05#section-3)
3636
3679
  */
3637
3680
  export const KEM_ML_KEM_1024: KEMFactory<CryptoKey> = function (): DirectKEM {
3638
3681
  const id = 0x0042
@@ -3731,7 +3774,7 @@ function AEAD_SHARED(P_MAX: number): AEAD_BASE {
3731
3774
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3732
3775
  *
3733
3776
  * @group AEAD Algorithms
3734
- * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.3)
3777
+ * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.3)
3735
3778
  */
3736
3779
  export const AEAD_AES_128_GCM: AEADFactory = function (): WebCryptoAEAD {
3737
3780
  return {
@@ -3763,7 +3806,7 @@ export const AEAD_AES_128_GCM: AEADFactory = function (): WebCryptoAEAD {
3763
3806
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3764
3807
  *
3765
3808
  * @group AEAD Algorithms
3766
- * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.3)
3809
+ * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.3)
3767
3810
  */
3768
3811
  export const AEAD_AES_256_GCM: AEADFactory = function (): WebCryptoAEAD {
3769
3812
  return {
@@ -3795,7 +3838,7 @@ export const AEAD_AES_256_GCM: AEADFactory = function (): WebCryptoAEAD {
3795
3838
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3796
3839
  *
3797
3840
  * @group AEAD Algorithms
3798
- * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.3)
3841
+ * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.3)
3799
3842
  */
3800
3843
  export const AEAD_ChaCha20Poly1305: AEADFactory = function AEAD_ChaCha20Poly1305(): WebCryptoAEAD {
3801
3844
  return {
@@ -3930,7 +3973,7 @@ function RandomScalarNist(t: CompositeHybridKEM['t'], seed: Uint8Array): Uint8Ar
3930
3973
  return bigIntToUint8Array(sk_bigint, t.Nscalar!)
3931
3974
  }
3932
3975
 
3933
- /** @see [expandDecapsKeyG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.1) */
3976
+ /** @see [expandDecapsKeyG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12#section-5.1.1) */
3934
3977
  async function expandDecapsKeyG(kem: CompositeHybridKEM, seed: Uint8Array) {
3935
3978
  const Nout = kem.pq.Nseed + kem.t.Nseed
3936
3979
  const bits = Nout << 3
@@ -3956,7 +3999,7 @@ async function expandDecapsKeyG(kem: CompositeHybridKEM, seed: Uint8Array) {
3956
3999
  return { ek_PQ, ek_T, dk_PQ, dk_T }
3957
4000
  }
3958
4001
 
3959
- /** @see [C2PRICombiner](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.3) */
4002
+ /** @see [C2PRICombiner](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12#section-5.1.3) */
3960
4003
  async function C2PRICombiner(
3961
4004
  kem: CompositeHybridKEM,
3962
4005
  ss_PQ: Uint8Array,
@@ -3970,7 +4013,7 @@ async function C2PRICombiner(
3970
4013
  return new Uint8Array(await subtle((c) => c.digest('SHA3-256', data), kem.name))
3971
4014
  }
3972
4015
 
3973
- /** @see [prepareEncapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.1) */
4016
+ /** @see [prepareEncapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12#section-5.1.1) */
3974
4017
  async function prepareEncapsG(
3975
4018
  kem: CompositeHybridKEM,
3976
4019
  ek_PQ: CryptoKey,
@@ -4000,7 +4043,7 @@ async function prepareEncapsG(
4000
4043
  return [ss_PQ, ss_T, ct_PQ, ct_T]
4001
4044
  }
4002
4045
 
4003
- /** @see [prepareDecapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.1) */
4046
+ /** @see [prepareDecapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12#section-5.1.1) */
4004
4047
  async function prepareDecapsG(
4005
4048
  kem: CompositeHybridKEM,
4006
4049
  dk_PQ: CryptoKey,
@@ -4219,7 +4262,7 @@ function createCompositeHybridKEM(parameters: CompositeHybridKEMParams): Composi
4219
4262
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
4220
4263
  *
4221
4264
  * @group KEM Algorithms
4222
- * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-4)
4265
+ * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05#section-4)
4223
4266
  */
4224
4267
  export const KEM_MLKEM768_X25519: KEMFactory = function (): CompositeHybridKEM | DirectKEM {
4225
4268
  const id = 0x647a
@@ -4279,7 +4322,7 @@ export const KEM_MLKEM768_X25519: KEMFactory = function (): CompositeHybridKEM |
4279
4322
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
4280
4323
  *
4281
4324
  * @group KEM Algorithms
4282
- * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-4)
4325
+ * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05#section-4)
4283
4326
  */
4284
4327
  export const KEM_MLKEM768_P256: KEMFactory = function (): CompositeHybridKEM | DirectKEM {
4285
4328
  const id = 0x0050
@@ -4338,7 +4381,7 @@ export const KEM_MLKEM768_P256: KEMFactory = function (): CompositeHybridKEM | D
4338
4381
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
4339
4382
  *
4340
4383
  * @group KEM Algorithms
4341
- * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-4)
4384
+ * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05#section-4)
4342
4385
  */
4343
4386
  export const KEM_MLKEM1024_P384: KEMFactory = function (): CompositeHybridKEM | DirectKEM {
4344
4387
  const id = 0x0051