hpke 1.0.3 → 1.0.5

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-02).
8
+ * [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03).
9
9
  *
10
10
  * HPKE provides a variant of public key encryption for arbitrary-sized plaintexts using a recipient
11
11
  * public key.
@@ -42,11 +42,13 @@
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-03.html#section-5.2) */
45
46
  function ComputeNonce(base_nonce: Uint8Array, seq: number, Nn: number): Uint8Array {
46
47
  const seq_bytes = I2OSP(seq, Nn)
47
48
  return xor(base_nonce, seq_bytes)
48
49
  }
49
50
 
51
+ /** @see [Context.IncrementSeq](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.2) */
50
52
  function IncrementSeq(seq: number): number {
51
53
  // seq is guaranteed to be a safe integer due to:
52
54
  // 1. Initial value is 0
@@ -57,6 +59,7 @@ function IncrementSeq(seq: number): number {
57
59
  return ++seq
58
60
  }
59
61
 
62
+ /** @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.3) */
60
63
  async function ContextExport(
61
64
  suite: Triple,
62
65
  exporterSecret: Uint8Array,
@@ -68,7 +71,7 @@ async function ContextExport(
68
71
  if (!Number.isInteger(L) || L <= 0 || L > 0xffff) {
69
72
  throw new TypeError('"L" must be a positive integer not exceeding 65535')
70
73
  }
71
- const Export = stages === 1 ? ExportOneStage : ExportTwoStage
74
+ const Export = stages === 1 ? Export_OneStage : Export_TwoStage
72
75
  return await Export(suite.KDF, suite.id, exporterSecret, exporterContext, L)
73
76
  }
74
77
 
@@ -171,6 +174,7 @@ class SenderContext {
171
174
  *
172
175
  * @returns A Promise that resolves to the ciphertext. The ciphertext is {@link Nt} bytes longer
173
176
  * than the plaintext.
177
+ * @see [Context.Seal](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.2)
174
178
  */
175
179
  async Seal(plaintext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array> {
176
180
  checkUint8Array(plaintext, 'plaintext')
@@ -218,6 +222,7 @@ class SenderContext {
218
222
  * @param length - Desired length of exported secret in bytes
219
223
  *
220
224
  * @returns A Promise that resolves to the exported secret.
225
+ * @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.3)
221
226
  */
222
227
  async Export(exporterContext: Uint8Array, length: number): Promise<Uint8Array> {
223
228
  return await ContextExport(this.#suite, this.#exporter_secret, exporterContext, length)
@@ -318,6 +323,7 @@ class RecipientContext {
318
323
  * @param aad - Additional authenticated data
319
324
  *
320
325
  * @returns A Promise that resolves to the decrypted plaintext.
326
+ * @see [Context.Open](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.2)
321
327
  */
322
328
  async Open(ciphertext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array> {
323
329
  checkUint8Array(ciphertext, 'ciphertext')
@@ -374,6 +380,7 @@ class RecipientContext {
374
380
  * @param length - Desired length of exported secret in bytes
375
381
  *
376
382
  * @returns A Promise that resolves to the exported secret.
383
+ * @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.3)
377
384
  */
378
385
  async Export(exporterContext: Uint8Array, length: number): Promise<Uint8Array> {
379
386
  return await ContextExport(this.#suite, this.#exporter_secret, exporterContext, length)
@@ -404,7 +411,7 @@ const validate = <T extends { type: string }>(factory: () => T, type: string): T
404
411
  * asymmetric key exchange with a symmetric cipher. This was originally defined in an Informational
405
412
  * document on the IRTF stream as [RFC 9180](https://www.rfc-editor.org/rfc/rfc9180.html) and is now
406
413
  * being republished as a Standards Track document of the IETF as
407
- * [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-02).
414
+ * [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03).
408
415
  *
409
416
  * HPKE provides a variant of public key encryption for arbitrary-sized plaintexts using a recipient
410
417
  * public key. It supports two modes:
@@ -797,6 +804,7 @@ export class CipherSuite {
797
804
  * @returns A Promise that resolves to an object containing the encapsulated secret and
798
805
  * ciphertext. The ciphertext is {@link CipherSuite.AEAD Nt} bytes longer than the plaintext. The
799
806
  * encapsulated secret is {@link CipherSuite.KEM Nenc} bytes.
807
+ * @see [Single-Shot Encryption](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-6.1)
800
808
  */
801
809
  async Seal(
802
810
  publicKey: Key,
@@ -845,6 +853,7 @@ export class CipherSuite {
845
853
  * @param options.pskId - Pre-shared key identifier (for PSK mode)
846
854
  *
847
855
  * @returns A Promise that resolves to the decrypted plaintext.
856
+ * @see [Single-Shot Decryption](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-6.1)
848
857
  */
849
858
  async Open(
850
859
  privateKey: Key | KeyPair,
@@ -892,6 +901,7 @@ export class CipherSuite {
892
901
  *
893
902
  * @returns A Promise that resolves to an object containing the encapsulated secret and the
894
903
  * exported secret.
904
+ * @see [Single-Shot Secret Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-6.2)
895
905
  */
896
906
  async SendExport(
897
907
  publicKey: Key,
@@ -939,6 +949,7 @@ export class CipherSuite {
939
949
  * @param options.pskId - Pre-shared key identifier (for PSK mode)
940
950
  *
941
951
  * @returns A Promise that resolves to the exported secret.
952
+ * @see [Single-Shot Secret Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-6.2)
942
953
  */
943
954
  async ReceiveExport(
944
955
  privateKey: Key | KeyPair,
@@ -992,6 +1003,7 @@ export class CipherSuite {
992
1003
  *
993
1004
  * @returns A Promise that resolves to an object containing the encapsulated secret and the sender
994
1005
  * context (`ctx`). The encapsulated secret is {@link CipherSuite.KEM Nenc} bytes.
1006
+ * @see [SetupBaseS / SetupPSKS](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.1.1)
995
1007
  */
996
1008
  async SetupSender(
997
1009
  publicKey: Key,
@@ -1072,6 +1084,7 @@ export class CipherSuite {
1072
1084
  * @param options.pskId - Pre-shared key identifier (for PSK mode)
1073
1085
  *
1074
1086
  * @returns A Promise that resolves to the recipient context.
1087
+ * @see [SetupBaseR / SetupPSKR](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.1.1)
1075
1088
  */
1076
1089
  async SetupRecipient(
1077
1090
  privateKey: Key | KeyPair,
@@ -1257,6 +1270,8 @@ interface Triple {
1257
1270
  *
1258
1271
  * Base mode provides encryption to a public key without sender authentication. The recipient cannot
1259
1272
  * verify who encrypted the message, only that someone with access to their public key did.
1273
+ *
1274
+ * @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5)
1260
1275
  */
1261
1276
  export const MODE_BASE = 0x00
1262
1277
 
@@ -1266,6 +1281,8 @@ export const MODE_BASE = 0x00
1266
1281
  * PSK (Pre-Shared Key) mode provides encryption with authentication using a pre-shared secret. Both
1267
1282
  * sender and recipient must possess the same PSK and PSK ID. This provides implicit sender
1268
1283
  * authentication.
1284
+ *
1285
+ * @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5)
1269
1286
  */
1270
1287
  export const MODE_PSK = 0x01
1271
1288
 
@@ -1286,7 +1303,7 @@ export const MODE_PSK = 0x01
1286
1303
  * Post-quantum/Traditional (PQ/T Hybrid):
1287
1304
  *
1288
1305
  * - {@link KEM_MLKEM768_P256 | MLKEM768-P256}
1289
- * - {@link KEM_MLKEM768_X25519 | MLKEM768-X25519 (aka X-Wing)}
1306
+ * - {@link KEM_MLKEM768_X25519 | MLKEM768-X25519}
1290
1307
  * - {@link KEM_MLKEM1024_P384 | MLKEM1024-P384}
1291
1308
  *
1292
1309
  * Post-quantum (PQ):
@@ -1475,6 +1492,7 @@ function lengthPrefixed(x: Uint8Array): Uint8Array {
1475
1492
  * ensures domain separation between different uses of the KDF in HPKE.
1476
1493
  *
1477
1494
  * @group Utilities
1495
+ * @see [LabeledDerive](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-5)
1478
1496
  */
1479
1497
  export async function LabeledDerive(
1480
1498
  KDF: Pick<KDF, 'Derive'>,
@@ -1495,7 +1513,8 @@ export async function LabeledDerive(
1495
1513
  return await KDF.Derive(labeled_ikm, L)
1496
1514
  }
1497
1515
 
1498
- async function ExportOneStage(
1516
+ /** @see [Export_OneStage](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-5) */
1517
+ async function Export_OneStage(
1499
1518
  KDF: KDF,
1500
1519
  suite_id: Uint8Array,
1501
1520
  exporter_secret: Uint8Array,
@@ -1506,7 +1525,8 @@ async function ExportOneStage(
1506
1525
  return await LabeledDerive(KDF, suite_id, exporter_secret, encode('sec'), exporter_context, L)
1507
1526
  }
1508
1527
 
1509
- async function CombineSecretsOneStage(
1528
+ /** @see [CombineSecrets_OneStage](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-5) */
1529
+ async function CombineSecrets_OneStage(
1510
1530
  suite: Triple,
1511
1531
  mode: number,
1512
1532
  shared_secret: Uint8Array,
@@ -1559,7 +1579,8 @@ function checkExtractable(extractable: unknown): asserts extractable is boolean
1559
1579
  }
1560
1580
  }
1561
1581
 
1562
- async function CombineSecretsTwoStage(
1582
+ /** @see [KeySchedule (CombineSecrets)](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.1) */
1583
+ async function CombineSecrets_TwoStage(
1563
1584
  suite: Triple,
1564
1585
  mode: number,
1565
1586
  shared_secret: Uint8Array,
@@ -1608,7 +1629,8 @@ async function CombineSecretsTwoStage(
1608
1629
  return { key, base_nonce, exporter_secret }
1609
1630
  }
1610
1631
 
1611
- async function ExportTwoStage(
1632
+ /** @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.3) */
1633
+ async function Export_TwoStage(
1612
1634
  KDF: KDF,
1613
1635
  suite_id: Uint8Array,
1614
1636
  exporter_secret: Uint8Array,
@@ -1684,7 +1706,7 @@ async function ExportTwoStage(
1684
1706
  * )
1685
1707
  * ```
1686
1708
  *
1687
- * @see [HPKE Cryptographic Dependencies](https://www.ietf.org/archive/id/draft-ietf-hpke-hpke-02.html#section-4)
1709
+ * @see [HPKE Key Derivation Functions](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-4.2)
1688
1710
  */
1689
1711
  export interface KDF {
1690
1712
  /** KDF algorithm identifier */
@@ -1757,6 +1779,7 @@ export interface KDF {
1757
1779
  * pseudorandom key. This ensures domain separation between different uses of the KDF in HPKE.
1758
1780
  *
1759
1781
  * @group Utilities
1782
+ * @see [LabeledExtract](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-4.4)
1760
1783
  */
1761
1784
  export async function LabeledExtract(
1762
1785
  KDF: Pick<KDF, 'Extract'>,
@@ -1786,6 +1809,7 @@ export async function LabeledExtract(
1786
1809
  * of the KDF in HPKE.
1787
1810
  *
1788
1811
  * @group Utilities
1812
+ * @see [LabeledExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-4.4)
1789
1813
  */
1790
1814
  export async function LabeledExpand(
1791
1815
  KDF: Pick<KDF, 'Expand'>,
@@ -1894,7 +1918,7 @@ export async function LabeledExpand(
1894
1918
  * )
1895
1919
  * ```
1896
1920
  *
1897
- * @see [HPKE Cryptographic Dependencies](https://www.ietf.org/archive/id/draft-ietf-hpke-hpke-02.html#section-4)
1921
+ * @see [HPKE Key Encapsulation Mechanisms](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-4.1)
1898
1922
  */
1899
1923
  export interface KEM {
1900
1924
  /** KEM algorithm identifier */
@@ -2096,7 +2120,7 @@ function isKey(key: unknown, type: string, extractable?: boolean): asserts key i
2096
2120
  * )
2097
2121
  * ```
2098
2122
  *
2099
- * @see [HPKE Cryptographic Dependencies](https://www.ietf.org/archive/id/draft-ietf-hpke-hpke-02.html#section-4)
2123
+ * @see [HPKE AEAD Encryption Algorithm](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-4.3)
2100
2124
  */
2101
2125
  export interface AEAD {
2102
2126
  /** AEAD algorithm identifier */
@@ -2156,6 +2180,7 @@ export interface AEAD {
2156
2180
  *
2157
2181
  * @returns A Uint8Array of length w containing the big-endian representation of n
2158
2182
  * @group Utilities
2183
+ * @see [I2OSP](https://www.rfc-editor.org/rfc/rfc8017#section-4.1)
2159
2184
  */
2160
2185
  export function I2OSP(n: number, w: number): Uint8Array {
2161
2186
  if (!Number.isSafeInteger(w) || w <= 0) {
@@ -2185,6 +2210,7 @@ function KDFStages(KDF: KDF): 1 | 2 {
2185
2210
  throw new Error('unreachable')
2186
2211
  }
2187
2212
 
2213
+ /** @see [KeySchedule](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.1) */
2188
2214
  async function KeySchedule(
2189
2215
  suite: Triple,
2190
2216
  mode: number,
@@ -2201,12 +2227,13 @@ async function KeySchedule(
2201
2227
  checkUint8Array(pskId, 'pskId')
2202
2228
 
2203
2229
  const stages = KDFStages(suite.KDF)
2204
- const CombineSecrets = stages === 1 ? CombineSecretsOneStage : CombineSecretsTwoStage
2230
+ const CombineSecrets = stages === 1 ? CombineSecrets_OneStage : CombineSecrets_TwoStage
2205
2231
 
2206
2232
  VerifyPSKInputs(psk, pskId)
2207
2233
  return await CombineSecrets(suite, mode, shared_secret, info, psk, pskId)
2208
2234
  }
2209
2235
 
2236
+ /** @see [VerifyPSKInputs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-5.1) */
2210
2237
  function VerifyPSKInputs(psk: Uint8Array, psk_id: Uint8Array) {
2211
2238
  if (psk.byteLength && psk_id.byteLength) {
2212
2239
  if (psk.byteLength < 32) {
@@ -2236,6 +2263,7 @@ const EXPORT_ONLY = 0xffff
2236
2263
  * This is a factory function that must be passed to the {@link CipherSuite} constructor.
2237
2264
  *
2238
2265
  * @group AEAD Algorithms
2266
+ * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.3)
2239
2267
  */
2240
2268
  export const AEAD_EXPORT_ONLY: AEADFactory = function (): AEAD {
2241
2269
  return {
@@ -2367,6 +2395,7 @@ function HKDF_SHARED(): KDF_BASE {
2367
2395
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2368
2396
  *
2369
2397
  * @group KDF Algorithms
2398
+ * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.2)
2370
2399
  */
2371
2400
  export const KDF_HKDF_SHA256: KDFFactory = function (): HKDF {
2372
2401
  return { id: 0x0001, type: 'KDF', name: 'HKDF-SHA256', Nh: 32, hash: 'SHA-256', ...HKDF_SHARED() }
@@ -2389,6 +2418,7 @@ export const KDF_HKDF_SHA256: KDFFactory = function (): HKDF {
2389
2418
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2390
2419
  *
2391
2420
  * @group KDF Algorithms
2421
+ * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.2)
2392
2422
  */
2393
2423
  export const KDF_HKDF_SHA384: KDFFactory = function (): HKDF {
2394
2424
  return { id: 0x0002, type: 'KDF', name: 'HKDF-SHA384', Nh: 48, hash: 'SHA-384', ...HKDF_SHARED() }
@@ -2411,6 +2441,7 @@ export const KDF_HKDF_SHA384: KDFFactory = function (): HKDF {
2411
2441
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2412
2442
  *
2413
2443
  * @group KDF Algorithms
2444
+ * @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.2)
2414
2445
  */
2415
2446
  export const KDF_HKDF_SHA512: KDFFactory = function (): HKDF {
2416
2447
  return { id: 0x0003, type: 'KDF', name: 'HKDF-SHA512', Nh: 64, hash: 'SHA-512', ...HKDF_SHARED() }
@@ -2425,7 +2456,8 @@ interface SHAKE extends KDF {
2425
2456
  }
2426
2457
 
2427
2458
  async function ShakeDerive(name: string, variant: string, ikm: ArrayBuffer, L: number) {
2428
- const alg = { name: variant, length: L << 3 }
2459
+ const bits = L << 3
2460
+ const alg = { name: variant, length: bits, outputLength: bits }
2429
2461
  return new Uint8Array(await subtle((c) => c.digest(alg, ikm), name))
2430
2462
  }
2431
2463
 
@@ -2457,6 +2489,7 @@ function SHAKE_SHARED(): KDF_BASE {
2457
2489
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2458
2490
  *
2459
2491
  * @group KDF Algorithms
2492
+ * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-5)
2460
2493
  */
2461
2494
  export const KDF_SHAKE128: KDFFactory = function (): SHAKE {
2462
2495
  return {
@@ -2486,6 +2519,7 @@ export const KDF_SHAKE128: KDFFactory = function (): SHAKE {
2486
2519
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
2487
2520
  *
2488
2521
  * @group KDF Algorithms
2522
+ * @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-5)
2489
2523
  */
2490
2524
  export const KDF_SHAKE256: KDFFactory = function (): SHAKE {
2491
2525
  return {
@@ -2591,7 +2625,8 @@ function b64u(input: string): Uint8Array {
2591
2625
  // KEM (Key Encapsulation Mechanism) - DHKEM Helper Functions
2592
2626
  // ============================================================================
2593
2627
 
2594
- async function DeriveCandidate(
2628
+ /** @see [DeriveKeyPair (DeriveCandidate)](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1.3) */
2629
+ async function DeriveCandidate_TwoStage(
2595
2630
  DHKEM: DHKEM,
2596
2631
  suite_id: Uint8Array,
2597
2632
  ikm: Uint8Array,
@@ -2656,6 +2691,29 @@ function assertCryptoKey(key: Key): asserts key is CryptoKey {
2656
2691
  }
2657
2692
  }
2658
2693
 
2694
+ /** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-4.5) */
2695
+ async function ExtractAndExpand_TwoStage(
2696
+ DHKEM: DHKEM,
2697
+ dh: Uint8Array,
2698
+ kem_context: Uint8Array,
2699
+ ): Promise<Uint8Array> {
2700
+ const eae_prk = await LabeledExtract(
2701
+ DHKEM.kdf,
2702
+ DHKEM.suite_id,
2703
+ new Uint8Array(),
2704
+ encode('eae_prk'),
2705
+ dh,
2706
+ )
2707
+ return await LabeledExpand(
2708
+ DHKEM.kdf,
2709
+ DHKEM.suite_id,
2710
+ eae_prk,
2711
+ encode('shared_secret'),
2712
+ kem_context,
2713
+ DHKEM.Nsecret,
2714
+ )
2715
+ }
2716
+
2659
2717
  // ============================================================================
2660
2718
  // KEM (Key Encapsulation Mechanism) - DHKEM Shared Implementation
2661
2719
  // ============================================================================
@@ -2704,21 +2762,7 @@ function DHKEM_SHARED(): Required<Omit<KEM_BASE, 'DeriveKeyPair' | 'DeserializeP
2704
2762
  const enc = await this.SerializePublicKey(pkE)
2705
2763
  const pkRm = await this.SerializePublicKey(pkR)
2706
2764
  const kem_context = concat(enc, pkRm)
2707
- const eae_prk = await LabeledExtract(
2708
- this.kdf,
2709
- this.suite_id,
2710
- new Uint8Array(),
2711
- encode('eae_prk'),
2712
- dh,
2713
- )
2714
- const shared_secret = await LabeledExpand(
2715
- this.kdf,
2716
- this.suite_id,
2717
- eae_prk,
2718
- encode('shared_secret'),
2719
- kem_context,
2720
- this.Nsecret,
2721
- )
2765
+ const shared_secret = await ExtractAndExpand_TwoStage(this, dh, kem_context)
2722
2766
  return { shared_secret, enc }
2723
2767
  },
2724
2768
  async Decap(this: DHKEM, enc, skR, pkR) {
@@ -2745,21 +2789,7 @@ function DHKEM_SHARED(): Required<Omit<KEM_BASE, 'DeriveKeyPair' | 'DeserializeP
2745
2789
 
2746
2790
  const pkRm = await this.SerializePublicKey(pkR)
2747
2791
  const kem_context = concat(enc, pkRm)
2748
- const eae_prk = await LabeledExtract(
2749
- this.kdf,
2750
- this.suite_id,
2751
- new Uint8Array(),
2752
- encode('eae_prk'),
2753
- dh,
2754
- )
2755
- const shared_secret = await LabeledExpand(
2756
- this.kdf,
2757
- this.suite_id,
2758
- eae_prk,
2759
- encode('shared_secret'),
2760
- kem_context,
2761
- this.Nsecret,
2762
- )
2792
+ const shared_secret = await ExtractAndExpand_TwoStage(this, dh, kem_context)
2763
2793
  return shared_secret
2764
2794
  },
2765
2795
  }
@@ -2949,6 +2979,7 @@ async function DeserializePrivateKeyNist(
2949
2979
  return privateKey
2950
2980
  }
2951
2981
 
2982
+ /** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1.3) */
2952
2983
  async function DeriveKeyPairNist(
2953
2984
  this: DHKEM & NistCurveConfig,
2954
2985
  ikm: Uint8Array,
@@ -2956,18 +2987,18 @@ async function DeriveKeyPairNist(
2956
2987
  ) {
2957
2988
  let sk = 0n
2958
2989
  let counter = 0
2959
- let bytes: Uint8Array
2990
+ let candidate: Uint8Array
2960
2991
  while (sk === 0n || sk >= this.order) {
2961
2992
  if (counter > 255) {
2962
2993
  throw new DeriveKeyPairError('Key derivation exceeded maximum iterations')
2963
2994
  }
2964
- bytes = await DeriveCandidate(this, this.suite_id, ikm, counter)
2965
- bytes[0] = bytes[0]! & this.bitmask
2966
- sk = OS2IP(bytes)
2995
+ candidate = await DeriveCandidate_TwoStage(this, this.suite_id, ikm, counter)
2996
+ candidate[0] = candidate[0]! & this.bitmask
2997
+ sk = OS2IP(candidate)
2967
2998
  counter = counter + 1
2968
2999
  }
2969
3000
 
2970
- return GetKeyPairNist(this, bytes!, extractable, this.name)
3001
+ return GetKeyPairNist(this, candidate!, extractable, this.name)
2971
3002
  }
2972
3003
 
2973
3004
  async function GetKeyPairNist(
@@ -2996,6 +3027,7 @@ async function GetKeyPairNist(
2996
3027
  // KEM (Key Encapsulation Mechanism) - DHKEM X Curve Implementations
2997
3028
  // ============================================================================
2998
3029
 
3030
+ /** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1.3) */
2999
3031
  async function DeriveKeyPairX(this: DHKEM, ikm: Uint8Array, extractable: boolean) {
3000
3032
  const dkp_prk = await LabeledExtract(
3001
3033
  this.kdf,
@@ -3048,6 +3080,7 @@ const P256: NistCurveConfig = {
3048
3080
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3049
3081
  *
3050
3082
  * @group KEM Algorithms
3083
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1)
3051
3084
  */
3052
3085
  export const KEM_DHKEM_P256_HKDF_SHA256: KEMFactory = function (): DHKEM & NistCurveConfig {
3053
3086
  const id = 0x0010
@@ -3102,6 +3135,7 @@ const P384: NistCurveConfig = {
3102
3135
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3103
3136
  *
3104
3137
  * @group KEM Algorithms
3138
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1)
3105
3139
  */
3106
3140
  export const KEM_DHKEM_P384_HKDF_SHA384: KEMFactory = function (): DHKEM & NistCurveConfig {
3107
3141
  const id = 0x0011
@@ -3156,6 +3190,7 @@ const P521: NistCurveConfig = {
3156
3190
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3157
3191
  *
3158
3192
  * @group KEM Algorithms
3193
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1)
3159
3194
  */
3160
3195
  export const KEM_DHKEM_P521_HKDF_SHA512: KEMFactory = function (): DHKEM & NistCurveConfig {
3161
3196
  const id = 0x0012
@@ -3201,6 +3236,7 @@ export const KEM_DHKEM_P521_HKDF_SHA512: KEMFactory = function (): DHKEM & NistC
3201
3236
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3202
3237
  *
3203
3238
  * @group KEM Algorithms
3239
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1)
3204
3240
  */
3205
3241
  export const KEM_DHKEM_X25519_HKDF_SHA256: KEMFactory = function (): DHKEM & { pkcs8: Uint8Array } {
3206
3242
  const id = 0x0020
@@ -3247,6 +3283,7 @@ export const KEM_DHKEM_X25519_HKDF_SHA256: KEMFactory = function (): DHKEM & { p
3247
3283
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3248
3284
  *
3249
3285
  * @group KEM Algorithms
3286
+ * @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.1)
3250
3287
  */
3251
3288
  export const KEM_DHKEM_X448_HKDF_SHA512: KEMFactory = function (): DHKEM & { pkcs8: Uint8Array } {
3252
3289
  const id = 0x0021
@@ -3391,6 +3428,7 @@ function MLKEM_SHARED(): KEM_BASE {
3391
3428
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3392
3429
  *
3393
3430
  * @group KEM Algorithms
3431
+ * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-3)
3394
3432
  */
3395
3433
  export const KEM_ML_KEM_512: KEMFactory = function (): MLKEM {
3396
3434
  const id = 0x0040
@@ -3430,6 +3468,7 @@ export const KEM_ML_KEM_512: KEMFactory = function (): MLKEM {
3430
3468
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3431
3469
  *
3432
3470
  * @group KEM Algorithms
3471
+ * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-3)
3433
3472
  */
3434
3473
  export const KEM_ML_KEM_768: KEMFactory = function (): MLKEM {
3435
3474
  const id = 0x0041
@@ -3469,6 +3508,7 @@ export const KEM_ML_KEM_768: KEMFactory = function (): MLKEM {
3469
3508
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3470
3509
  *
3471
3510
  * @group KEM Algorithms
3511
+ * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-3)
3472
3512
  */
3473
3513
  export const KEM_ML_KEM_1024: KEMFactory = function (): MLKEM {
3474
3514
  const id = 0x0042
@@ -3557,6 +3597,7 @@ function AEAD_SHARED(): AEAD_BASE {
3557
3597
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3558
3598
  *
3559
3599
  * @group AEAD Algorithms
3600
+ * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.3)
3560
3601
  */
3561
3602
  export const AEAD_AES_128_GCM: AEADFactory = function (): WebCryptoAEAD {
3562
3603
  return {
@@ -3588,6 +3629,7 @@ export const AEAD_AES_128_GCM: AEADFactory = function (): WebCryptoAEAD {
3588
3629
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3589
3630
  *
3590
3631
  * @group AEAD Algorithms
3632
+ * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.3)
3591
3633
  */
3592
3634
  export const AEAD_AES_256_GCM: AEADFactory = function (): WebCryptoAEAD {
3593
3635
  return {
@@ -3619,6 +3661,7 @@ export const AEAD_AES_256_GCM: AEADFactory = function (): WebCryptoAEAD {
3619
3661
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
3620
3662
  *
3621
3663
  * @group AEAD Algorithms
3664
+ * @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03.html#section-7.3)
3622
3665
  */
3623
3666
  export const AEAD_ChaCha20Poly1305: AEADFactory = function AEAD_ChaCha20Poly1305(): WebCryptoAEAD {
3624
3667
  return {
@@ -3753,10 +3796,12 @@ function RandomScalarNist(t: HybridKEM['t'], seed: Uint8Array): Uint8Array {
3753
3796
  return bigIntToUint8Array(sk_bigint, t.Nscalar!)
3754
3797
  }
3755
3798
 
3799
+ /** @see [expandDecapsKeyG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-10.html#section-5.1.1) */
3756
3800
  async function expandDecapsKeyG(PQTKEM: HybridKEM, _seed: Uint8Array) {
3757
3801
  const Nout = PQTKEM.pq.Nseed + PQTKEM.t.Nseed
3802
+ const bits = Nout << 3
3758
3803
  // @ts-expect-error
3759
- const algorithm: CShakeParams = { name: 'cSHAKE256', length: Nout << 3 }
3804
+ const algorithm: CShakeParams = { name: 'cSHAKE256', length: bits, outputLength: bits }
3760
3805
  const seed = ab(_seed)
3761
3806
  const seed_full = await subtle((c) => c.digest(algorithm, seed), PQTKEM.name)
3762
3807
 
@@ -3779,6 +3824,7 @@ async function expandDecapsKeyG(PQTKEM: HybridKEM, _seed: Uint8Array) {
3779
3824
  return { ek_PQ, ek_T, dk_PQ, dk_T }
3780
3825
  }
3781
3826
 
3827
+ /** @see [C2PRICombiner](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-10.html#section-5.1.3) */
3782
3828
  async function C2PRICombiner(
3783
3829
  PQTKEM: HybridKEM,
3784
3830
  ss_PQ: Uint8Array,
@@ -3792,6 +3838,7 @@ async function C2PRICombiner(
3792
3838
  return new Uint8Array(await subtle((c) => c.digest('SHA3-256', data), PQTKEM.name))
3793
3839
  }
3794
3840
 
3841
+ /** @see [prepareEncapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-10.html#section-5.1.1) */
3795
3842
  async function prepareEncapsG(
3796
3843
  PQTKEM: HybridKEM,
3797
3844
  ek_PQ: CryptoKey,
@@ -3822,6 +3869,7 @@ async function prepareEncapsG(
3822
3869
  return [ss_PQ, ss_T, ct_PQ, ct_T]
3823
3870
  }
3824
3871
 
3872
+ /** @see [prepareDecapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-10.html#section-5.1.1) */
3825
3873
  async function prepareDecapsG(
3826
3874
  PQTKEM: HybridKEM,
3827
3875
  dk_PQ: CryptoKey,
@@ -4003,7 +4051,7 @@ function PQTKEM_SHARED(): KEM_BASE {
4003
4051
  // ============================================================================
4004
4052
 
4005
4053
  /**
4006
- * Hybrid KEM combining ML-KEM-768 with X25519 (MLKEM768-X25519 aka X-Wing).
4054
+ * Hybrid KEM combining ML-KEM-768 with X25519 (MLKEM768-X25519).
4007
4055
  *
4008
4056
  * Depends on the following Web Cryptography algorithms being supported in the runtime:
4009
4057
  *
@@ -4019,6 +4067,7 @@ function PQTKEM_SHARED(): KEM_BASE {
4019
4067
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
4020
4068
  *
4021
4069
  * @group KEM Algorithms
4070
+ * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-4)
4022
4071
  */
4023
4072
  export const KEM_MLKEM768_X25519: KEMFactory = function (): HybridKEM {
4024
4073
  const id = 0x647a
@@ -4075,6 +4124,7 @@ export const KEM_MLKEM768_X25519: KEMFactory = function (): HybridKEM {
4075
4124
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
4076
4125
  *
4077
4126
  * @group KEM Algorithms
4127
+ * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-4)
4078
4128
  */
4079
4129
  export const KEM_MLKEM768_P256: KEMFactory = function (): HybridKEM {
4080
4130
  const id = 0x0050
@@ -4130,6 +4180,7 @@ export const KEM_MLKEM768_P256: KEMFactory = function (): HybridKEM {
4130
4180
  * > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
4131
4181
  *
4132
4182
  * @group KEM Algorithms
4183
+ * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-04.html#section-4)
4133
4184
  */
4134
4185
  export const KEM_MLKEM1024_P384: KEMFactory = function (): HybridKEM {
4135
4186
  const id = 0x0051
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hpke",
3
- "version": "1.0.3",
3
+ "version": "1.0.5",
4
4
  "description": "Hybrid Public Key Encryption (HPKE) for Node.js, Browser, Cloudflare Workers, Deno, Bun, and other Web-interoperable runtimes",
5
5
  "keywords": [
6
6
  "browser",
@@ -43,30 +43,32 @@
43
43
  "build": "node build.cjs",
44
44
  "build:other": "npx tsc -p tsconfig.test.json && npx tsc -p tsconfig.examples.json",
45
45
  "docs": "npx typedoc",
46
- "format": "prettier --log-level silent --cache --write '**/*.{ts,mjs,cjs,json,yml}' '**/README.md'",
46
+ "format": "prettier --log-level silent --cache --write '**/*.{ts,js,mjs,cjs,json,yml}' '**/README.md'",
47
47
  "test": "node --test --no-warnings test/*.ts",
48
48
  "test:browsers": "node test/browser.mjs",
49
49
  "test:bun": "bun test ./test/*.ts",
50
50
  "test:deno": "deno test --no-check --allow-read test/*.ts",
51
- "test:docs": "./check-examples.sh"
51
+ "test:docs": "./check-examples.sh",
52
+ "test:workerd": "./test/.workerd.sh"
52
53
  },
53
54
  "devDependencies": {
54
55
  "@noble/ciphers": "^2.1.1",
55
56
  "@noble/curves": "^2.0.1",
56
57
  "@noble/hashes": "^2.0.1",
57
- "@noble/post-quantum": "^0.5.3",
58
- "@types/node": "^24.10.4",
59
- "@types/web": "^0.0.297",
60
- "amaro": "^1.1.5",
61
- "playwright": "^1.57.0",
62
- "prettier": "^3.7.4",
58
+ "@noble/post-quantum": "^0.5.4",
59
+ "@types/node": "^24.10.11",
60
+ "@types/web": "^0.0.327",
61
+ "amaro": "^1.1.7",
62
+ "esbuild": "^0.27.0",
63
+ "playwright": "^1.58.2",
64
+ "prettier": "^3.8.1",
63
65
  "prettier-plugin-jsdoc": "^1.8.0",
64
66
  "remark-behead": "^3.1.0",
65
67
  "remark-insert-headings": "^0.0.0",
66
68
  "remark-toc": "^9.0.0",
67
69
  "serve": "^14.2.5",
68
- "typedoc": "^0.28.15",
69
- "typedoc-plugin-markdown": "^4.9.0",
70
+ "typedoc": "^0.28.16",
71
+ "typedoc-plugin-markdown": "^4.10.0",
70
72
  "typedoc-plugin-remark": "^2.0.1",
71
73
  "typescript": "^5.9.3"
72
74
  },