hpke 1.1.7 → 1.1.9

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.
Files changed (6) hide show
  1. package/README.md +30 -19
  2. package/index.d.ts +133 -90
  3. package/index.d.ts.map +1 -1
  4. package/index.js +301 -253
  5. package/index.ts +389 -341
  6. package/package.json +12 -11
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,10 +850,12 @@ 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
  *
819
- * Mode selection:
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.
820
855
  *
821
- * - If the options `psk` and `pskId` are omitted: Base mode (unauthenticated)
822
- * - If the options `psk` and `pskId` are provided: PSK mode (authenticated with pre-shared key)
856
+ * Omitted PSK options default to empty byte arrays. When `psk` and `pskId` are both empty, the
857
+ * suite uses unauthenticated Base mode. PSK mode requires a `psk` of at least 32 bytes and a
858
+ * nonempty `pskId`.
823
859
  *
824
860
  * @category Single-Shot APIs
825
861
  * @example
@@ -844,7 +880,8 @@ export class CipherSuite<K extends Key = Key> {
844
880
  * @returns A Promise that resolves to an object containing the encapsulated secret and
845
881
  * ciphertext. The ciphertext is {@link CipherSuite.AEAD Nt} bytes longer than the plaintext. The
846
882
  * 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)
883
+ * @see [Single-Shot Encryption](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-6.1)
884
+ * @see [Auxiliary Authenticated Application Information](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-8.1)
848
885
  */
849
886
  async Seal(
850
887
  publicKey: K,
@@ -864,10 +901,12 @@ export class CipherSuite<K extends Key = Key> {
864
901
  *
865
902
  * It combines context setup and decryption in one call.
866
903
  *
867
- * Mode selection:
904
+ * Applications should prefer `options.info` for authenticated information that applies to the
905
+ * whole context, reserving `options.aad` for information specific to the message.
868
906
  *
869
- * - If the options `psk` and `pskId` are omitted: Base mode (unauthenticated)
870
- * - If the options `psk` and `pskId` are provided: PSK mode (authenticated with pre-shared key)
907
+ * Omitted PSK options default to empty byte arrays. When `psk` and `pskId` are both empty, the
908
+ * suite uses unauthenticated Base mode. PSK mode requires a `psk` of at least 32 bytes and a
909
+ * nonempty `pskId`.
871
910
  *
872
911
  * @category Single-Shot APIs
873
912
  * @example
@@ -893,7 +932,8 @@ export class CipherSuite<K extends Key = Key> {
893
932
  * @param options.pskId - Pre-shared key identifier (for PSK mode)
894
933
  *
895
934
  * @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)
935
+ * @see [Single-Shot Decryption](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-6.1)
936
+ * @see [Auxiliary Authenticated Application Information](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-8.1)
897
937
  */
898
938
  async Open(
899
939
  privateKey: K | KeyPair<K>,
@@ -913,8 +953,20 @@ export class CipherSuite<K extends Key = Key> {
913
953
  *
914
954
  * It combines context setup and secret export in one call.
915
955
  *
956
+ * Omitted PSK options default to empty byte arrays. When `psk` and `pskId` are both empty, the
957
+ * suite uses unauthenticated Base mode. PSK mode requires a `psk` of at least 32 bytes and a
958
+ * nonempty `pskId`.
959
+ *
960
+ * Applications should prefer `options.info` for authenticated information that applies to the
961
+ * whole context, reserving `exporterContext` for information specific to the exported secret.
962
+ *
916
963
  * The exported secret is indistinguishable from a uniformly random bitstring of equal length.
917
964
  *
965
+ * HPKE does not provide replay protection. A replayed encapsulated secret produces the same
966
+ * exported secrets. Applications must only use these secrets where repeated values are safe.
967
+ * Deriving AEAD keys and nonces requires a fresh value for each derivation, such as a
968
+ * recipient-provided nonce.
969
+ *
918
970
  * @category Single-Shot APIs
919
971
  * @example
920
972
  *
@@ -941,7 +993,8 @@ export class CipherSuite<K extends Key = Key> {
941
993
  *
942
994
  * @returns A Promise that resolves to an object containing the encapsulated secret and the
943
995
  * exported secret.
944
- * @see [Single-Shot Secret Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-6.2)
996
+ * @see [Single-Shot Secret Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-6.2)
997
+ * @see [Auxiliary Authenticated Application Information](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-8.1)
945
998
  */
946
999
  async SendExport(
947
1000
  publicKey: K,
@@ -959,6 +1012,18 @@ export class CipherSuite<K extends Key = Key> {
959
1012
  *
960
1013
  * It combines context setup and secret export in one call.
961
1014
  *
1015
+ * Omitted PSK options default to empty byte arrays. When `psk` and `pskId` are both empty, the
1016
+ * suite uses unauthenticated Base mode. PSK mode requires a `psk` of at least 32 bytes and a
1017
+ * nonempty `pskId`.
1018
+ *
1019
+ * Applications should prefer `options.info` for authenticated information that applies to the
1020
+ * whole context, reserving `exporterContext` for information specific to the exported secret.
1021
+ *
1022
+ * HPKE does not provide replay protection. A replayed encapsulated secret produces the same
1023
+ * exported secrets. Applications must only use these secrets where repeated values are safe.
1024
+ * Deriving AEAD keys and nonces requires a fresh value for each derivation, such as a
1025
+ * recipient-provided nonce.
1026
+ *
962
1027
  * @category Single-Shot APIs
963
1028
  * @example
964
1029
  *
@@ -989,7 +1054,8 @@ export class CipherSuite<K extends Key = Key> {
989
1054
  * @param options.pskId - Pre-shared key identifier (for PSK mode)
990
1055
  *
991
1056
  * @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)
1057
+ * @see [Single-Shot Secret Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-6.2)
1058
+ * @see [Auxiliary Authenticated Application Information](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-8.1)
993
1059
  */
994
1060
  async ReceiveExport(
995
1061
  privateKey: K | KeyPair<K>,
@@ -1008,10 +1074,9 @@ export class CipherSuite<K extends Key = Key> {
1008
1074
  * Creates a context that can be used to encrypt multiple messages to the same recipient,
1009
1075
  * amortizing the cost of the public key operations.
1010
1076
  *
1011
- * Mode selection:
1012
- *
1013
- * - If the options `psk` and `pskId` are omitted: Base mode (unauthenticated)
1014
- * - If the options `psk` and `pskId` are provided: PSK mode (authenticated with pre-shared key)
1077
+ * Omitted PSK options default to empty byte arrays. When `psk` and `pskId` are both empty, the
1078
+ * suite uses unauthenticated Base mode. PSK mode requires a `psk` of at least 32 bytes and a
1079
+ * nonempty `pskId`.
1015
1080
  *
1016
1081
  * The returned context maintains a sequence number that increments with each encryption, ensuring
1017
1082
  * nonce uniqueness.
@@ -1043,7 +1108,7 @@ export class CipherSuite<K extends Key = Key> {
1043
1108
  *
1044
1109
  * @returns A Promise that resolves to an object containing the encapsulated secret and the sender
1045
1110
  * 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)
1111
+ * @see [SetupBaseS / SetupPSKS](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5.1.1)
1047
1112
  */
1048
1113
  async SetupSender(
1049
1114
  publicKey: K,
@@ -1083,10 +1148,9 @@ export class CipherSuite<K extends Key = Key> {
1083
1148
  *
1084
1149
  * Creates a context that can be used to decrypt multiple messages from the same sender.
1085
1150
  *
1086
- * Mode selection:
1087
- *
1088
- * - If the options `psk` and `pskId` are omitted: Base mode (unauthenticated)
1089
- * - If the options `psk` and `pskId` are provided: PSK mode (authenticated with pre-shared key)
1151
+ * Omitted PSK options default to empty byte arrays. When `psk` and `pskId` are both empty, the
1152
+ * suite uses unauthenticated Base mode. PSK mode requires a `psk` of at least 32 bytes and a
1153
+ * nonempty `pskId`.
1090
1154
  *
1091
1155
  * @category Encryption Context
1092
1156
  * @example
@@ -1124,7 +1188,7 @@ export class CipherSuite<K extends Key = Key> {
1124
1188
  * @param options.pskId - Pre-shared key identifier (for PSK mode)
1125
1189
  *
1126
1190
  * @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)
1191
+ * @see [SetupBaseR / SetupPSKR](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5.1.1)
1128
1192
  */
1129
1193
  async SetupRecipient(
1130
1194
  privateKey: K | KeyPair<K>,
@@ -1311,7 +1375,7 @@ interface Triple<K extends Key = Key> {
1311
1375
  * Base mode provides encryption to a public key without sender authentication. The recipient cannot
1312
1376
  * verify who encrypted the message, only that someone with access to their public key did.
1313
1377
  *
1314
- * @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5)
1378
+ * @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5)
1315
1379
  */
1316
1380
  export const MODE_BASE = 0x00
1317
1381
 
@@ -1322,7 +1386,7 @@ export const MODE_BASE = 0x00
1322
1386
  * sender and recipient must possess the same PSK and PSK ID. This provides implicit sender
1323
1387
  * authentication.
1324
1388
  *
1325
- * @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5)
1389
+ * @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5)
1326
1390
  */
1327
1391
  export const MODE_PSK = 0x01
1328
1392
 
@@ -1533,6 +1597,38 @@ export function encode(string: string): Uint8Array {
1533
1597
  return bytes
1534
1598
  }
1535
1599
 
1600
+ /**
1601
+ * Integer to Octet String Primitive (I2OSP) as defined in RFC 8017. Converts a non-negative integer
1602
+ * into a byte string of specified length. It's exported for use in custom KEM, KDF, or AEAD
1603
+ * implementations.
1604
+ *
1605
+ * @param n - Non-negative safe integer to convert
1606
+ * @param w - Desired length of output in bytes
1607
+ *
1608
+ * @returns A Uint8Array of length w containing the big-endian representation of n
1609
+ * @group Utilities
1610
+ * @see [I2OSP](https://www.rfc-editor.org/rfc/rfc8017#section-4.1)
1611
+ */
1612
+ export function I2OSP(n: number, w: number): Uint8Array {
1613
+ if (!Number.isSafeInteger(w) || w <= 0) {
1614
+ throw new Error('w must be a positive safe integer')
1615
+ }
1616
+ if (!Number.isSafeInteger(n) || n < 0) {
1617
+ throw new Error('n must be a non-negative safe integer')
1618
+ }
1619
+ const max = Math.pow(256, w)
1620
+ if (n >= max) {
1621
+ throw new Error('n too large to fit in w-length byte string')
1622
+ }
1623
+ const ret = new Uint8Array(w)
1624
+ let num = n
1625
+ for (let i = 0; i < w && num; i++) {
1626
+ ret[w - (i + 1)] = num % 256
1627
+ num = Math.floor(num / 256)
1628
+ }
1629
+ return ret
1630
+ }
1631
+
1536
1632
  // Module-level cached encodings of static ASCII labels used on HPKE hot paths.
1537
1633
  // Each is a freshly-allocated Uint8Array held as a constant to avoid repeating
1538
1634
  // the per-call `encode()` validation+allocation loop. These are only ever read
@@ -1560,88 +1656,13 @@ function lengthPrefixed(x: Uint8Array): Uint8Array {
1560
1656
  }
1561
1657
 
1562
1658
  // ============================================================================
1563
- // KDF (Key Derivation Function) - Helper Functions
1659
+ // Input Validation
1564
1660
  // ============================================================================
1565
1661
 
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
1662
+ // Apply a 65535-byte implementation limit to two-stage KDF inputs.
1643
1663
  const MAX_LENGTH_TWO_STAGE = 0xffff
1644
- // that is also applied to Two-Stage KDF for consistency
1664
+ // One-stage length-prefixed PSK, PSK ID, and info inputs are limited to 65535 bytes.
1665
+ // Apply the same bound to one-stage exporter contexts as an implementation limit.
1645
1666
  const MAX_LENGTH_ONE_STAGE = 0xffff
1646
1667
 
1647
1668
  function checkLength(data: Uint8Array, name: string, maxLength: number) {
@@ -1663,60 +1684,9 @@ function checkExtractable(extractable: unknown): asserts extractable is boolean
1663
1684
  }
1664
1685
  }
1665
1686
 
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
- }
1687
+ // ============================================================================
1688
+ // KDF (Key Derivation Function) - Types and Interfaces
1689
+ // ============================================================================
1720
1690
 
1721
1691
  /**
1722
1692
  * Key Derivation Function (KDF) implementation interface.
@@ -1737,6 +1707,9 @@ async function Export_TwoStage(
1737
1707
  * - Two-stage KDFs only implement {@link Extract} and {@link Expand}. The {@link Derive} method will not
1738
1708
  * be called and may be a no-op implementation.
1739
1709
  *
1710
+ * Custom KDF implementations must also meet the [KDF security
1711
+ * requirements](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-9.3).
1712
+ *
1740
1713
  * @example
1741
1714
  *
1742
1715
  * ```ts
@@ -1783,7 +1756,7 @@ async function Export_TwoStage(
1783
1756
  * )
1784
1757
  * ```
1785
1758
  *
1786
- * @see [HPKE Key Derivation Functions](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.2)
1759
+ * @see [HPKE Key Derivation Functions](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-4.2)
1787
1760
  */
1788
1761
  export interface KDF {
1789
1762
  /** KDF algorithm identifier */
@@ -1838,9 +1811,40 @@ export interface KDF {
1838
1811
  }
1839
1812
 
1840
1813
  // ============================================================================
1841
- // KDF (Key Derivation Function) - Labeled Extract/Expand Functions
1814
+ // KDF (Key Derivation Function) - Labeled Derivation Functions
1842
1815
  // ============================================================================
1843
1816
 
1817
+ /**
1818
+ * Performs labeled key derivation for one-stage KDFs.
1819
+ *
1820
+ * This function implements the LabeledDerive operation as specified in the HPKE specification for
1821
+ * use with one-stage KDFs. It constructs a labeled input by concatenating:
1822
+ *
1823
+ * - The input keying material (`ikm`)
1824
+ * - The version string "HPKE-v1"
1825
+ * - The suite identifier (`suite_id`)
1826
+ * - A length-prefixed label
1827
+ * - The desired output length as a 2-byte encoding
1828
+ * - Additional context
1829
+ *
1830
+ * The labeled input is then passed to the KDF's Derive function to produce L bytes of output. This
1831
+ * ensures domain separation between different uses of the KDF in HPKE.
1832
+ *
1833
+ * @group Utilities
1834
+ * @see [LabeledDerive](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-4.4)
1835
+ */
1836
+ export async function LabeledDerive(
1837
+ KDF: Pick<KDF, 'Derive'>,
1838
+ suite_id: Uint8Array,
1839
+ ikm: Uint8Array,
1840
+ label: Uint8Array,
1841
+ context: Uint8Array,
1842
+ L: number,
1843
+ ): Promise<Uint8Array> {
1844
+ const labeled_ikm = concat(ikm, L_HPKE_v1, suite_id, lengthPrefixed(label), I2OSP(L, 2), context)
1845
+ return await KDF.Derive(labeled_ikm, L)
1846
+ }
1847
+
1844
1848
  /**
1845
1849
  * Performs labeled extraction for two-stage KDFs.
1846
1850
  *
@@ -1856,7 +1860,7 @@ export interface KDF {
1856
1860
  * pseudorandom key. This ensures domain separation between different uses of the KDF in HPKE.
1857
1861
  *
1858
1862
  * @group Utilities
1859
- * @see [LabeledExtract](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.4)
1863
+ * @see [LabeledExtract](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-4.4)
1860
1864
  */
1861
1865
  export async function LabeledExtract(
1862
1866
  KDF: Pick<KDF, 'Extract'>,
@@ -1886,7 +1890,7 @@ export async function LabeledExtract(
1886
1890
  * of the KDF in HPKE.
1887
1891
  *
1888
1892
  * @group Utilities
1889
- * @see [LabeledExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.4)
1893
+ * @see [LabeledExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-4.4)
1890
1894
  */
1891
1895
  export async function LabeledExpand(
1892
1896
  KDF: Pick<KDF, 'Expand'>,
@@ -1996,7 +2000,7 @@ export async function LabeledExpand(
1996
2000
  * ```
1997
2001
  *
1998
2002
  * @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)
2003
+ * @see [HPKE Key Encapsulation Mechanisms](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-4.1)
2000
2004
  */
2001
2005
  export interface KEM<K extends Key = Key> {
2002
2006
  /** KEM algorithm identifier */
@@ -2198,7 +2202,7 @@ function isKey(key: unknown, type: string, extractable?: boolean): asserts key i
2198
2202
  * )
2199
2203
  * ```
2200
2204
  *
2201
- * @see [HPKE AEAD Encryption Algorithm](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.3)
2205
+ * @see [HPKE AEAD Encryption Algorithm](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-4.3)
2202
2206
  */
2203
2207
  export interface AEAD {
2204
2208
  /** AEAD algorithm identifier */
@@ -2233,7 +2237,7 @@ export interface AEAD {
2233
2237
  * @param pt - Plaintext to encrypt
2234
2238
  *
2235
2239
  * @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)
2240
+ * @see [Context.Seal P_MAX handling](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5.2)
2237
2241
  */
2238
2242
  Seal(key: Uint8Array, nonce: Uint8Array, aad: Uint8Array, pt: Uint8Array): Promise<Uint8Array>
2239
2243
 
@@ -2254,38 +2258,6 @@ export interface AEAD {
2254
2258
  // HPKE Core Functions - Key Schedule
2255
2259
  // ============================================================================
2256
2260
 
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
2261
  function KDFStages(KDF: KDF): 1 | 2 {
2290
2262
  if (KDF.stages === 1 || KDF.stages === 2) {
2291
2263
  return KDF.stages
@@ -2294,7 +2266,82 @@ function KDFStages(KDF: KDF): 1 | 2 {
2294
2266
  throw new Error('unreachable')
2295
2267
  }
2296
2268
 
2297
- /** @see [KeySchedule](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.1) */
2269
+ /** @see [CombineSecrets](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5.1) */
2270
+ async function CombineSecrets_OneStage(
2271
+ suite: Triple,
2272
+ mode: number,
2273
+ shared_secret: Uint8Array,
2274
+ info: Uint8Array,
2275
+ psk: Uint8Array,
2276
+ psk_id: Uint8Array,
2277
+ ) {
2278
+ checkLength(psk, 'PSK', MAX_LENGTH_ONE_STAGE)
2279
+ checkLength(psk_id, 'PSK ID', MAX_LENGTH_ONE_STAGE)
2280
+ checkLength(info, 'Info', MAX_LENGTH_ONE_STAGE)
2281
+
2282
+ const secrets = concat(lengthPrefixed(psk), lengthPrefixed(shared_secret))
2283
+ const context = concat(I2OSP(mode, 1), lengthPrefixed(psk_id), lengthPrefixed(info))
2284
+
2285
+ const secret = await LabeledDerive(
2286
+ suite.KDF,
2287
+ suite.id,
2288
+ secrets,
2289
+ L_secret,
2290
+ context,
2291
+ suite.AEAD.Nk + suite.AEAD.Nn + suite.KDF.Nh,
2292
+ )
2293
+
2294
+ const key = slice(secret, 0, suite.AEAD.Nk)
2295
+ const base_nonce = slice(secret, suite.AEAD.Nk, suite.AEAD.Nk + suite.AEAD.Nn)
2296
+ const exporter_secret = slice(secret, suite.AEAD.Nk + suite.AEAD.Nn)
2297
+
2298
+ return { key, base_nonce, exporter_secret }
2299
+ }
2300
+
2301
+ /** @see [CombineSecrets](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5.1) */
2302
+ async function CombineSecrets_TwoStage(
2303
+ suite: Triple,
2304
+ mode: number,
2305
+ shared_secret: Uint8Array,
2306
+ info: Uint8Array,
2307
+ psk: Uint8Array,
2308
+ psk_id: Uint8Array,
2309
+ ) {
2310
+ checkLength(psk, 'PSK', MAX_LENGTH_TWO_STAGE)
2311
+ checkLength(psk_id, 'PSK ID', MAX_LENGTH_TWO_STAGE)
2312
+ checkLength(info, 'Info', MAX_LENGTH_TWO_STAGE)
2313
+
2314
+ const [psk_id_hash, info_hash] = await Promise.all([
2315
+ LabeledExtract(suite.KDF, suite.id, new Uint8Array(), L_psk_id_hash, psk_id),
2316
+ LabeledExtract(suite.KDF, suite.id, new Uint8Array(), L_info_hash, info),
2317
+ ])
2318
+
2319
+ const key_schedule_context = concat(I2OSP(mode, 1), psk_id_hash, info_hash)
2320
+ const secret = await LabeledExtract(suite.KDF, suite.id, shared_secret, L_secret, psk)
2321
+
2322
+ // For export-only AEAD, we only need the exporter_secret
2323
+ if (suite.AEAD.id === EXPORT_ONLY) {
2324
+ const exporter_secret = await LabeledExpand(
2325
+ suite.KDF,
2326
+ suite.id,
2327
+ secret,
2328
+ L_exp,
2329
+ key_schedule_context,
2330
+ suite.KDF.Nh,
2331
+ )
2332
+ return { key: new Uint8Array(), base_nonce: new Uint8Array(), exporter_secret }
2333
+ }
2334
+
2335
+ const [key, base_nonce, exporter_secret] = await Promise.all([
2336
+ LabeledExpand(suite.KDF, suite.id, secret, L_key, key_schedule_context, suite.AEAD.Nk),
2337
+ LabeledExpand(suite.KDF, suite.id, secret, L_base_nonce, key_schedule_context, suite.AEAD.Nn),
2338
+ LabeledExpand(suite.KDF, suite.id, secret, L_exp, key_schedule_context, suite.KDF.Nh),
2339
+ ])
2340
+
2341
+ return { key, base_nonce, exporter_secret }
2342
+ }
2343
+
2344
+ /** @see [KeySchedule](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5.1) */
2298
2345
  async function KeySchedule(
2299
2346
  suite: Triple,
2300
2347
  mode: number,
@@ -2317,7 +2364,7 @@ async function KeySchedule(
2317
2364
  return await CombineSecrets(suite, mode, shared_secret, info, psk, pskId)
2318
2365
  }
2319
2366
 
2320
- /** @see [VerifyPSKInputs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.1) */
2367
+ /** @see [VerifyPSKInputs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-5.1) */
2321
2368
  function VerifyPSKInputs(psk: Uint8Array, psk_id: Uint8Array) {
2322
2369
  if (psk.byteLength && psk_id.byteLength) {
2323
2370
  if (psk.byteLength < 32) {
@@ -2349,7 +2396,7 @@ const CHACHA20_POLY1305_P_MAX = 2 ** 38 - 64
2349
2396
  * This is a factory function that must be passed to the {@link CipherSuite} constructor.
2350
2397
  *
2351
2398
  * @group AEAD Algorithms
2352
- * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.3)
2399
+ * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.3)
2353
2400
  */
2354
2401
  export const AEAD_EXPORT_ONLY: AEADFactory = function (): AEAD {
2355
2402
  return {
@@ -2492,7 +2539,7 @@ function HKDF_SHARED(): KDF_BASE {
2492
2539
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2493
2540
  *
2494
2541
  * @group KDF Algorithms
2495
- * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.2)
2542
+ * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.2)
2496
2543
  */
2497
2544
  export const KDF_HKDF_SHA256: KDFFactory = function (): HKDF {
2498
2545
  return { id: 0x0001, type: 'KDF', name: 'HKDF-SHA256', Nh: 32, hash: 'SHA-256', ...HKDF_SHARED() }
@@ -2515,7 +2562,7 @@ export const KDF_HKDF_SHA256: KDFFactory = function (): HKDF {
2515
2562
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2516
2563
  *
2517
2564
  * @group KDF Algorithms
2518
- * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.2)
2565
+ * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.2)
2519
2566
  */
2520
2567
  export const KDF_HKDF_SHA384: KDFFactory = function (): HKDF {
2521
2568
  return { id: 0x0002, type: 'KDF', name: 'HKDF-SHA384', Nh: 48, hash: 'SHA-384', ...HKDF_SHARED() }
@@ -2538,7 +2585,7 @@ export const KDF_HKDF_SHA384: KDFFactory = function (): HKDF {
2538
2585
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2539
2586
  *
2540
2587
  * @group KDF Algorithms
2541
- * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.2)
2588
+ * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.2)
2542
2589
  */
2543
2590
  export const KDF_HKDF_SHA512: KDFFactory = function (): HKDF {
2544
2591
  return { id: 0x0003, type: 'KDF', name: 'HKDF-SHA512', Nh: 64, hash: 'SHA-512', ...HKDF_SHARED() }
@@ -2586,7 +2633,7 @@ function SHAKE_SHARED(): KDF_BASE {
2586
2633
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2587
2634
  *
2588
2635
  * @group KDF Algorithms
2589
- * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
2636
+ * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05#section-5)
2590
2637
  */
2591
2638
  export const KDF_SHAKE128: KDFFactory = function (): SHAKE {
2592
2639
  return {
@@ -2616,7 +2663,7 @@ export const KDF_SHAKE128: KDFFactory = function (): SHAKE {
2616
2663
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2617
2664
  *
2618
2665
  * @group KDF Algorithms
2619
- * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
2666
+ * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05#section-5)
2620
2667
  */
2621
2668
  export const KDF_SHAKE256: KDFFactory = function (): SHAKE {
2622
2669
  return {
@@ -2646,7 +2693,7 @@ export const KDF_SHAKE256: KDFFactory = function (): SHAKE {
2646
2693
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2647
2694
  *
2648
2695
  * @group KDF Algorithms
2649
- * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
2696
+ * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05#section-5)
2650
2697
  */
2651
2698
  export const KDF_TurboSHAKE128: KDFFactory = function (): SHAKE {
2652
2699
  return {
@@ -2676,7 +2723,7 @@ export const KDF_TurboSHAKE128: KDFFactory = function (): SHAKE {
2676
2723
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2677
2724
  *
2678
2725
  * @group KDF Algorithms
2679
- * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
2726
+ * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05#section-5)
2680
2727
  */
2681
2728
  export const KDF_TurboSHAKE256: KDFFactory = function (): SHAKE {
2682
2729
  return {
@@ -2771,7 +2818,7 @@ function b64u(input: string): Uint8Array {
2771
2818
  // KEM (Key Encapsulation Mechanism) - DHKEM Helper Functions
2772
2819
  // ============================================================================
2773
2820
 
2774
- /** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1.3) */
2821
+ /** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.1.3) */
2775
2822
  async function DeriveKeyPairBytes(
2776
2823
  DHKEM: DHKEM,
2777
2824
  ikm: Uint8Array,
@@ -2828,7 +2875,7 @@ function assertCryptoKey(key: Key): asserts key is CryptoKey {
2828
2875
  }
2829
2876
  }
2830
2877
 
2831
- /** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.5) */
2878
+ /** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-4.5) */
2832
2879
  async function ExtractAndExpand_OneStage(
2833
2880
  DHKEM: DHKEM,
2834
2881
  dh: Uint8Array,
@@ -2844,7 +2891,7 @@ async function ExtractAndExpand_OneStage(
2844
2891
  )
2845
2892
  }
2846
2893
 
2847
- /** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.5) */
2894
+ /** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-4.5) */
2848
2895
  async function ExtractAndExpand_TwoStage(
2849
2896
  DHKEM: DHKEM,
2850
2897
  dh: Uint8Array,
@@ -2861,7 +2908,7 @@ async function ExtractAndExpand_TwoStage(
2861
2908
  )
2862
2909
  }
2863
2910
 
2864
- /** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.5) */
2911
+ /** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-4.5) */
2865
2912
  async function ExtractAndExpand(
2866
2913
  DHKEM: DHKEM,
2867
2914
  dh: Uint8Array,
@@ -3119,7 +3166,7 @@ async function DeserializePrivateKeyNist(
3119
3166
  return (await importKeyNist(this, key, this.name, extractable, false)).privateKey
3120
3167
  }
3121
3168
 
3122
- /** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1.3) */
3169
+ /** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.1.3) */
3123
3170
  async function DeriveKeyPairNist(
3124
3171
  this: DHKEM & NistCurveConfig,
3125
3172
  ikm: Uint8Array,
@@ -3154,7 +3201,7 @@ async function GetKeyPairNist(
3154
3201
  // KEM (Key Encapsulation Mechanism) - DHKEM X Curve Implementations
3155
3202
  // ============================================================================
3156
3203
 
3157
- /** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1.3) */
3204
+ /** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.1.3) */
3158
3205
  async function DeriveKeyPairX(this: DHKEM, ikm: Uint8Array, extractable: boolean) {
3159
3206
  const sk = await DeriveKeyPairBytes(this, ikm, L_sk, new Uint8Array())
3160
3207
  return await createKeyPairFromPrivateKey(this, sk, extractable)
@@ -3194,7 +3241,7 @@ const P256: NistCurveConfig = {
3194
3241
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3195
3242
  *
3196
3243
  * @group KEM Algorithms
3197
- * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
3244
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.1)
3198
3245
  */
3199
3246
  export const KEM_DHKEM_P256_HKDF_SHA256: KEMFactory<CryptoKey> = function (): DHKEM &
3200
3247
  NistCurveConfig {
@@ -3250,7 +3297,7 @@ const P384: NistCurveConfig = {
3250
3297
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3251
3298
  *
3252
3299
  * @group KEM Algorithms
3253
- * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
3300
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.1)
3254
3301
  */
3255
3302
  export const KEM_DHKEM_P384_HKDF_SHA384: KEMFactory<CryptoKey> = function (): DHKEM &
3256
3303
  NistCurveConfig {
@@ -3306,7 +3353,7 @@ const P521: NistCurveConfig = {
3306
3353
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3307
3354
  *
3308
3355
  * @group KEM Algorithms
3309
- * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
3356
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.1)
3310
3357
  */
3311
3358
  export const KEM_DHKEM_P521_HKDF_SHA512: KEMFactory<CryptoKey> = function (): DHKEM &
3312
3359
  NistCurveConfig {
@@ -3353,7 +3400,7 @@ export const KEM_DHKEM_P521_HKDF_SHA512: KEMFactory<CryptoKey> = function (): DH
3353
3400
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3354
3401
  *
3355
3402
  * @group KEM Algorithms
3356
- * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
3403
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.1)
3357
3404
  */
3358
3405
  export const KEM_DHKEM_X25519_HKDF_SHA256: KEMFactory<CryptoKey> = function (): DHKEM & {
3359
3406
  pkcs8: Uint8Array
@@ -3402,7 +3449,7 @@ export const KEM_DHKEM_X25519_HKDF_SHA256: KEMFactory<CryptoKey> = function ():
3402
3449
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3403
3450
  *
3404
3451
  * @group KEM Algorithms
3405
- * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
3452
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.1)
3406
3453
  */
3407
3454
  export const KEM_DHKEM_X448_HKDF_SHA512: KEMFactory<CryptoKey> = function (): DHKEM & {
3408
3455
  pkcs8: Uint8Array
@@ -3574,7 +3621,7 @@ function createDirectKEM({ id, name, Nsecret, Nenc, Npk, Nsk }: KEMParams): Dire
3574
3621
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3575
3622
  *
3576
3623
  * @group KEM Algorithms
3577
- * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-3)
3624
+ * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05#section-3)
3578
3625
  */
3579
3626
  export const KEM_ML_KEM_512: KEMFactory<CryptoKey> = function (): DirectKEM {
3580
3627
  const id = 0x0040
@@ -3603,7 +3650,7 @@ export const KEM_ML_KEM_512: KEMFactory<CryptoKey> = function (): DirectKEM {
3603
3650
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3604
3651
  *
3605
3652
  * @group KEM Algorithms
3606
- * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-3)
3653
+ * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05#section-3)
3607
3654
  */
3608
3655
  export const KEM_ML_KEM_768: KEMFactory<CryptoKey> = function (): DirectKEM {
3609
3656
  const id = 0x0041
@@ -3632,7 +3679,7 @@ export const KEM_ML_KEM_768: KEMFactory<CryptoKey> = function (): DirectKEM {
3632
3679
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3633
3680
  *
3634
3681
  * @group KEM Algorithms
3635
- * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-3)
3682
+ * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05#section-3)
3636
3683
  */
3637
3684
  export const KEM_ML_KEM_1024: KEMFactory<CryptoKey> = function (): DirectKEM {
3638
3685
  const id = 0x0042
@@ -3731,7 +3778,7 @@ function AEAD_SHARED(P_MAX: number): AEAD_BASE {
3731
3778
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3732
3779
  *
3733
3780
  * @group AEAD Algorithms
3734
- * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.3)
3781
+ * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.3)
3735
3782
  */
3736
3783
  export const AEAD_AES_128_GCM: AEADFactory = function (): WebCryptoAEAD {
3737
3784
  return {
@@ -3763,7 +3810,7 @@ export const AEAD_AES_128_GCM: AEADFactory = function (): WebCryptoAEAD {
3763
3810
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3764
3811
  *
3765
3812
  * @group AEAD Algorithms
3766
- * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.3)
3813
+ * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.3)
3767
3814
  */
3768
3815
  export const AEAD_AES_256_GCM: AEADFactory = function (): WebCryptoAEAD {
3769
3816
  return {
@@ -3795,7 +3842,7 @@ export const AEAD_AES_256_GCM: AEADFactory = function (): WebCryptoAEAD {
3795
3842
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3796
3843
  *
3797
3844
  * @group AEAD Algorithms
3798
- * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.3)
3845
+ * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-06#section-7.3)
3799
3846
  */
3800
3847
  export const AEAD_ChaCha20Poly1305: AEADFactory = function AEAD_ChaCha20Poly1305(): WebCryptoAEAD {
3801
3848
  return {
@@ -3816,91 +3863,95 @@ export const AEAD_ChaCha20Poly1305: AEADFactory = function AEAD_ChaCha20Poly1305
3816
3863
  // KEM (Key Encapsulation Mechanism) - Composite Hybrid KEM Types and Implementation
3817
3864
  // ============================================================================
3818
3865
 
3819
- /* c8 ignore next 5 */
3820
- const InvalidInvocation = (_: typeof priv) => {
3821
- if (_ !== priv) {
3822
- throw new Error('invalid invocation')
3823
- }
3824
- }
3825
- const priv = /* @__PURE__ */ Symbol()
3826
- class HybridKey implements Key {
3827
- #algorithm: KeyAlgorithm
3828
- #type: 'public' | 'private'
3829
- #extractable: boolean
3830
- #t: CryptoKey
3831
- #pq: CryptoKey
3832
- #seed?: Uint8Array | undefined
3833
- #publicKey?: HybridKey | undefined
3834
-
3835
- static #isValid(key: HybridKey): boolean {
3836
- return key.#algorithm !== undefined
3837
- }
3838
-
3839
- static validate(key: unknown, extractable?: boolean): asserts key is HybridKey {
3840
- try {
3841
- if (!HybridKey.#isValid(key as HybridKey)) {
3842
- throw new TypeError('unexpected key constructor')
3866
+ type HybridKey = ReturnType<typeof hybridKeys.create>
3867
+
3868
+ const hybridKeys = /* @__PURE__ */ (() => {
3869
+ const priv = Symbol()
3870
+ let validate!: (key: HybridKey, extractable?: boolean) => void
3871
+ let getPublicKey!: (key: HybridKey) => HybridKey | undefined
3872
+ let getSeed!: (key: HybridKey) => Uint8Array
3873
+ let getTraditionalKey!: (key: HybridKey) => CryptoKey
3874
+ let getPostQuantumKey!: (key: HybridKey) => CryptoKey
3875
+
3876
+ class HybridKey implements Key {
3877
+ #algorithm: KeyAlgorithm
3878
+ #type: 'public' | 'private'
3879
+ #extractable: boolean
3880
+ #t: CryptoKey
3881
+ #pq: CryptoKey
3882
+ #seed?: Uint8Array | undefined
3883
+ #publicKey?: HybridKey | undefined
3884
+
3885
+ static {
3886
+ validate = (key, extractable) => {
3887
+ if (typeof key !== 'object' || key === null || !(#extractable in key)) {
3888
+ throw new TypeError('unexpected key constructor')
3889
+ }
3890
+ if (extractable && !key.#extractable) {
3891
+ throw new TypeError('key must be extractable')
3892
+ }
3843
3893
  }
3844
- } catch {
3845
- throw new TypeError('unexpected key constructor')
3894
+ getPublicKey = (key) => key.#publicKey
3895
+ getSeed = (key) => slice(key.#seed!)
3896
+ getTraditionalKey = (key) => key.#t
3897
+ getPostQuantumKey = (key) => key.#pq
3846
3898
  }
3847
- if (extractable && !(key as HybridKey).extractable) {
3848
- throw new TypeError('key must be extractable')
3849
- }
3850
- }
3851
3899
 
3852
- constructor(
3853
- _: typeof priv,
3854
- algorithm: KeyAlgorithm,
3855
- type: 'public' | 'private',
3856
- extractable: boolean,
3857
- pq: CryptoKey,
3858
- t: CryptoKey,
3859
- seed?: Uint8Array,
3860
- publicKey?: HybridKey,
3861
- ) {
3862
- InvalidInvocation(_)
3863
- this.#algorithm = algorithm
3864
- this.#type = type
3865
- this.#extractable = extractable
3866
- this.#pq = pq
3867
- this.#t = t
3868
- this.#seed = seed
3869
- this.#publicKey = publicKey
3870
- }
3871
-
3872
- get algorithm() {
3873
- return { name: this.#algorithm.name }
3874
- }
3875
-
3876
- get extractable() {
3877
- return this.#extractable
3878
- }
3879
-
3880
- get type() {
3881
- return this.#type
3882
- }
3900
+ constructor(
3901
+ _: typeof priv,
3902
+ algorithm: KeyAlgorithm,
3903
+ type: 'public' | 'private',
3904
+ extractable: boolean,
3905
+ pq: CryptoKey,
3906
+ t: CryptoKey,
3907
+ seed?: Uint8Array,
3908
+ publicKey?: HybridKey,
3909
+ ) {
3910
+ if (_ !== priv) throw new Error('invalid invocation')
3911
+ this.#algorithm = algorithm
3912
+ this.#type = type
3913
+ this.#extractable = extractable
3914
+ this.#pq = pq
3915
+ this.#t = t
3916
+ this.#seed = seed
3917
+ this.#publicKey = publicKey
3918
+ Object.freeze(this)
3919
+ }
3883
3920
 
3884
- getPublicKey(_: typeof priv) {
3885
- InvalidInvocation(_)
3886
- return this.#publicKey
3887
- }
3921
+ get algorithm() {
3922
+ return { name: this.#algorithm.name }
3923
+ }
3888
3924
 
3889
- getSeed(_: typeof priv) {
3890
- InvalidInvocation(_)
3891
- return slice(this.#seed!)
3892
- }
3925
+ get extractable() {
3926
+ return this.#extractable
3927
+ }
3893
3928
 
3894
- getT(_: typeof priv) {
3895
- InvalidInvocation(_)
3896
- return this.#t
3929
+ get type() {
3930
+ return this.#type
3931
+ }
3897
3932
  }
3898
3933
 
3899
- getPq(_: typeof priv) {
3900
- InvalidInvocation(_)
3901
- return this.#pq
3934
+ Object.freeze(HybridKey)
3935
+ Object.freeze(HybridKey.prototype)
3936
+ return {
3937
+ create(
3938
+ algorithm: KeyAlgorithm,
3939
+ type: 'public' | 'private',
3940
+ extractable: boolean,
3941
+ pq: CryptoKey,
3942
+ t: CryptoKey,
3943
+ seed?: Uint8Array,
3944
+ publicKey?: HybridKey,
3945
+ ) {
3946
+ return new HybridKey(priv, algorithm, type, extractable, pq, t, seed, publicKey)
3947
+ },
3948
+ validate,
3949
+ getPublicKey,
3950
+ getSeed,
3951
+ getTraditionalKey,
3952
+ getPostQuantumKey,
3902
3953
  }
3903
- }
3954
+ })()
3904
3955
 
3905
3956
  function split(N1: number, N2: number, x: Uint8Array): [Uint8Array, Uint8Array] {
3906
3957
  if (x.byteLength !== N1 + N2) {
@@ -3930,7 +3981,7 @@ function RandomScalarNist(t: CompositeHybridKEM['t'], seed: Uint8Array): Uint8Ar
3930
3981
  return bigIntToUint8Array(sk_bigint, t.Nscalar!)
3931
3982
  }
3932
3983
 
3933
- /** @see [expandDecapsKeyG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.1) */
3984
+ /** @see [expandDecapsKeyG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12#section-5.1.1) */
3934
3985
  async function expandDecapsKeyG(kem: CompositeHybridKEM, seed: Uint8Array) {
3935
3986
  const Nout = kem.pq.Nseed + kem.t.Nseed
3936
3987
  const bits = Nout << 3
@@ -3956,7 +4007,7 @@ async function expandDecapsKeyG(kem: CompositeHybridKEM, seed: Uint8Array) {
3956
4007
  return { ek_PQ, ek_T, dk_PQ, dk_T }
3957
4008
  }
3958
4009
 
3959
- /** @see [C2PRICombiner](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.3) */
4010
+ /** @see [C2PRICombiner](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12#section-5.1.3) */
3960
4011
  async function C2PRICombiner(
3961
4012
  kem: CompositeHybridKEM,
3962
4013
  ss_PQ: Uint8Array,
@@ -3970,7 +4021,7 @@ async function C2PRICombiner(
3970
4021
  return new Uint8Array(await subtle((c) => c.digest('SHA3-256', data), kem.name))
3971
4022
  }
3972
4023
 
3973
- /** @see [prepareEncapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.1) */
4024
+ /** @see [prepareEncapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12#section-5.1.1) */
3974
4025
  async function prepareEncapsG(
3975
4026
  kem: CompositeHybridKEM,
3976
4027
  ek_PQ: CryptoKey,
@@ -4000,7 +4051,7 @@ async function prepareEncapsG(
4000
4051
  return [ss_PQ, ss_T, ct_PQ, ct_T]
4001
4052
  }
4002
4053
 
4003
- /** @see [prepareDecapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.1) */
4054
+ /** @see [prepareDecapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12#section-5.1.1) */
4004
4055
  async function prepareDecapsG(
4005
4056
  kem: CompositeHybridKEM,
4006
4057
  dk_PQ: CryptoKey,
@@ -4062,7 +4113,6 @@ interface CompositeHybridKEM extends KEM<HybridKey> {
4062
4113
  type CompositeHybridKEMParams = KEMParams & Pick<CompositeHybridKEM, 'pq' | 't' | 'label'>
4063
4114
 
4064
4115
  function COMPOSITE_HYBRID_KEM_SHARED(): KEM_BASE<HybridKey> {
4065
- Object.freeze(HybridKey.prototype)
4066
4116
  return {
4067
4117
  async DeriveKeyPair(this: CompositeHybridKEM, ikm: Uint8Array, extractable) {
4068
4118
  const seed = await LabeledDerive(
@@ -4076,9 +4126,8 @@ function COMPOSITE_HYBRID_KEM_SHARED(): KEM_BASE<HybridKey> {
4076
4126
 
4077
4127
  const { ek_PQ, ek_T, dk_PQ, dk_T } = await expandDecapsKeyG(this, seed)
4078
4128
 
4079
- const publicKey = new HybridKey(priv, this.algorithm, 'public', true, ek_PQ, ek_T)
4080
- const privateKey = new HybridKey(
4081
- priv,
4129
+ const publicKey = hybridKeys.create(this.algorithm, 'public', true, ek_PQ, ek_T)
4130
+ const privateKey = hybridKeys.create(
4082
4131
  this.algorithm,
4083
4132
  'private',
4084
4133
  extractable,
@@ -4095,14 +4144,14 @@ function COMPOSITE_HYBRID_KEM_SHARED(): KEM_BASE<HybridKey> {
4095
4144
  },
4096
4145
  async SerializePublicKey(this: CompositeHybridKEM, key) {
4097
4146
  assertKeyAlgorithm(key, this.algorithm)
4098
- HybridKey.validate(key, true)
4147
+ hybridKeys.validate(key, true)
4099
4148
  // @ts-expect-error
4100
4149
  const format: Exclude<KeyFormat, 'jwk'> = 'raw-public'
4101
4150
  const ek_PQ = new Uint8Array(
4102
- await subtle((c) => c.exportKey(format, key.getPq(priv)), this.name),
4151
+ await subtle((c) => c.exportKey(format, hybridKeys.getPostQuantumKey(key)), this.name),
4103
4152
  )
4104
4153
  const ek_T = new Uint8Array(
4105
- await subtle((c) => c.exportKey('raw', key.getT(priv)), this.name),
4154
+ await subtle((c) => c.exportKey('raw', hybridKeys.getTraditionalKey(key)), this.name),
4106
4155
  )
4107
4156
 
4108
4157
  return concat(ek_PQ, ek_T)
@@ -4119,20 +4168,19 @@ function COMPOSITE_HYBRID_KEM_SHARED(): KEM_BASE<HybridKey> {
4119
4168
  subtle((c) => c.importKey('raw', pubT, this.t.algorithm, true, []), this.name),
4120
4169
  ])
4121
4170
 
4122
- return new HybridKey(priv, this.algorithm, 'public', true, ek_PQ, ek_T)
4171
+ return hybridKeys.create(this.algorithm, 'public', true, ek_PQ, ek_T)
4123
4172
  },
4124
4173
  async SerializePrivateKey(this: CompositeHybridKEM, key) {
4125
4174
  assertKeyAlgorithm(key, this.algorithm)
4126
- HybridKey.validate(key, true)
4175
+ hybridKeys.validate(key, true)
4127
4176
 
4128
- return key.getSeed(priv)
4177
+ return hybridKeys.getSeed(key)
4129
4178
  },
4130
4179
  async DeserializePrivateKey(this: CompositeHybridKEM, key, extractable) {
4131
4180
  const seed = slice(key)
4132
4181
  const { ek_PQ, ek_T, dk_PQ, dk_T } = await expandDecapsKeyG(this, seed)
4133
- const publicKey = new HybridKey(priv, this.algorithm, 'public', true, ek_PQ, ek_T)
4134
- const privateKey = new HybridKey(
4135
- priv,
4182
+ const publicKey = hybridKeys.create(this.algorithm, 'public', true, ek_PQ, ek_T)
4183
+ const privateKey = hybridKeys.create(
4136
4184
  this.algorithm,
4137
4185
  'private',
4138
4186
  extractable,
@@ -4146,10 +4194,10 @@ function COMPOSITE_HYBRID_KEM_SHARED(): KEM_BASE<HybridKey> {
4146
4194
  },
4147
4195
  async Encap(this: CompositeHybridKEM, pkR) {
4148
4196
  assertKeyAlgorithm(pkR, this.algorithm)
4149
- HybridKey.validate(pkR)
4197
+ hybridKeys.validate(pkR)
4150
4198
 
4151
- const ek_PQ = pkR.getPq(priv)
4152
- const ek_T = pkR.getT(priv)
4199
+ const ek_PQ = hybridKeys.getPostQuantumKey(pkR)
4200
+ const ek_T = hybridKeys.getTraditionalKey(pkR)
4153
4201
  const [ss_PQ, ss_T, ct_PQ, ct_T] = await prepareEncapsG(this, ek_PQ, ek_T)
4154
4202
  const ss_H = await C2PRICombiner(this, ss_PQ, ss_T, ct_T, ek_T, this.label)
4155
4203
  const ct_H = concat(ct_PQ, ct_T)
@@ -4158,18 +4206,18 @@ function COMPOSITE_HYBRID_KEM_SHARED(): KEM_BASE<HybridKey> {
4158
4206
  },
4159
4207
  async Decap(this: CompositeHybridKEM, enc, skR, pkR) {
4160
4208
  assertKeyAlgorithm(skR, this.algorithm)
4161
- HybridKey.validate(skR)
4209
+ hybridKeys.validate(skR)
4162
4210
 
4163
4211
  if (pkR) {
4164
4212
  assertKeyAlgorithm(pkR, this.algorithm)
4165
- HybridKey.validate(pkR)
4213
+ hybridKeys.validate(pkR)
4166
4214
  }
4167
4215
 
4168
4216
  const [ct_PQ, ct_T] = split(this.pq.Nct, this.t.Nct, enc)
4169
- const ek = pkR ?? skR.getPublicKey(priv)!
4170
- const ek_T = ek.getT(priv)
4171
- const dk_PQ = skR.getPq(priv)
4172
- const dk_T = skR.getT(priv)
4217
+ const ek = pkR ?? hybridKeys.getPublicKey(skR)!
4218
+ const ek_T = hybridKeys.getTraditionalKey(ek)
4219
+ const dk_PQ = hybridKeys.getPostQuantumKey(skR)
4220
+ const dk_T = hybridKeys.getTraditionalKey(skR)
4173
4221
  const [ss_PQ, ss_T] = await prepareDecapsG(this, dk_PQ, dk_T, ct_PQ, ct_T)
4174
4222
  const ss_H = await C2PRICombiner(this, ss_PQ, ss_T, ct_T, ek_T, this.label)
4175
4223
 
@@ -4219,7 +4267,7 @@ function createCompositeHybridKEM(parameters: CompositeHybridKEMParams): Composi
4219
4267
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
4220
4268
  *
4221
4269
  * @group KEM Algorithms
4222
- * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-4)
4270
+ * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05#section-4)
4223
4271
  */
4224
4272
  export const KEM_MLKEM768_X25519: KEMFactory = function (): CompositeHybridKEM | DirectKEM {
4225
4273
  const id = 0x647a
@@ -4279,7 +4327,7 @@ export const KEM_MLKEM768_X25519: KEMFactory = function (): CompositeHybridKEM |
4279
4327
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
4280
4328
  *
4281
4329
  * @group KEM Algorithms
4282
- * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-4)
4330
+ * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05#section-4)
4283
4331
  */
4284
4332
  export const KEM_MLKEM768_P256: KEMFactory = function (): CompositeHybridKEM | DirectKEM {
4285
4333
  const id = 0x0050
@@ -4338,7 +4386,7 @@ export const KEM_MLKEM768_P256: KEMFactory = function (): CompositeHybridKEM | D
4338
4386
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
4339
4387
  *
4340
4388
  * @group KEM Algorithms
4341
- * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-4)
4389
+ * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05#section-4)
4342
4390
  */
4343
4391
  export const KEM_MLKEM1024_P384: KEMFactory = function (): CompositeHybridKEM | DirectKEM {
4344
4392
  const id = 0x0051