hpke 1.1.4 → 1.1.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
@@ -3463,18 +3463,20 @@ export const KEM_DHKEM_X448_HKDF_SHA512: KEMFactory<CryptoKey> = function (): DH
3463
3463
  }
3464
3464
 
3465
3465
  // ============================================================================
3466
- // KEM (Key Encapsulation Mechanism) - ML-KEM Types and Implementation
3466
+ // KEM (Key Encapsulation Mechanism) - Direct KEM Types and Implementation
3467
3467
  // ============================================================================
3468
3468
 
3469
- interface MLKEM extends KEM<CryptoKey> {
3469
+ type KEMParams = Pick<KEM, 'id' | 'name' | 'Nsecret' | 'Nenc' | 'Npk' | 'Nsk'>
3470
+
3471
+ interface DirectKEM extends KEM<CryptoKey> {
3470
3472
  readonly suite_id: Uint8Array
3471
3473
  readonly algorithm: Readonly<KeyAlgorithm>
3472
3474
  readonly kdf: KDF
3473
3475
  }
3474
3476
 
3475
- function MLKEM_SHARED(): KEM_BASE<CryptoKey> {
3477
+ function DIRECT_KEM_SHARED(): KEM_BASE<CryptoKey> {
3476
3478
  return {
3477
- async DeriveKeyPair(this: MLKEM, ikm, extractable) {
3479
+ async DeriveKeyPair(this: DirectKEM, ikm, extractable) {
3478
3480
  const dk = await LabeledDerive(
3479
3481
  this.kdf,
3480
3482
  this.suite_id,
@@ -3491,7 +3493,7 @@ function MLKEM_SHARED(): KEM_BASE<CryptoKey> {
3491
3493
 
3492
3494
  return { privateKey, publicKey }
3493
3495
  },
3494
- async GenerateKeyPair(this: MLKEM, extractable) {
3496
+ async GenerateKeyPair(this: DirectKEM, extractable) {
3495
3497
  // @ts-expect-error
3496
3498
  const usages: KeyUsage[] = ['encapsulateBits', 'decapsulateBits']
3497
3499
  return (await subtle(
@@ -3499,14 +3501,14 @@ function MLKEM_SHARED(): KEM_BASE<CryptoKey> {
3499
3501
  this.name,
3500
3502
  )) as CryptoKeyPair
3501
3503
  },
3502
- async SerializePublicKey(this: MLKEM, key) {
3504
+ async SerializePublicKey(this: DirectKEM, key) {
3503
3505
  assertKeyAlgorithm(key, this.algorithm)
3504
3506
  assertCryptoKey(key)
3505
3507
  // @ts-expect-error
3506
3508
  const format: Exclude<KeyFormat, 'jwk'> = 'raw-public'
3507
3509
  return new Uint8Array(await subtle((c) => c.exportKey(format, key), this.name))
3508
3510
  },
3509
- async DeserializePublicKey(this: MLKEM, key) {
3511
+ async DeserializePublicKey(this: DirectKEM, key) {
3510
3512
  // @ts-expect-error
3511
3513
  const format: Exclude<KeyFormat, 'jwk'> = 'raw-public'
3512
3514
  // @ts-expect-error
@@ -3516,14 +3518,14 @@ function MLKEM_SHARED(): KEM_BASE<CryptoKey> {
3516
3518
  this.name,
3517
3519
  )
3518
3520
  },
3519
- async SerializePrivateKey(this: MLKEM, key) {
3521
+ async SerializePrivateKey(this: DirectKEM, key) {
3520
3522
  assertKeyAlgorithm(key, this.algorithm)
3521
3523
  assertCryptoKey(key)
3522
3524
  // @ts-expect-error
3523
3525
  const format: Exclude<KeyFormat, 'jwk'> = 'raw-seed'
3524
3526
  return new Uint8Array(await subtle((c) => c.exportKey(format, key), this.name))
3525
3527
  },
3526
- async DeserializePrivateKey(this: MLKEM, key, extractable) {
3528
+ async DeserializePrivateKey(this: DirectKEM, key, extractable) {
3527
3529
  // @ts-expect-error
3528
3530
  const format: Exclude<KeyFormat, 'jwk'> = 'raw-seed'
3529
3531
  // @ts-expect-error
@@ -3533,7 +3535,7 @@ function MLKEM_SHARED(): KEM_BASE<CryptoKey> {
3533
3535
  this.name,
3534
3536
  )
3535
3537
  },
3536
- async Encap(this: MLKEM, pkR) {
3538
+ async Encap(this: DirectKEM, pkR) {
3537
3539
  assertKeyAlgorithm(pkR, this.algorithm)
3538
3540
 
3539
3541
  const { sharedKey, ciphertext } = (await subtle(
@@ -3544,7 +3546,7 @@ function MLKEM_SHARED(): KEM_BASE<CryptoKey> {
3544
3546
 
3545
3547
  return { shared_secret: new Uint8Array(sharedKey), enc: new Uint8Array(ciphertext) }
3546
3548
  },
3547
- async Decap(this: MLKEM, enc, skR, _pkR) {
3549
+ async Decap(this: DirectKEM, enc, skR, _pkR) {
3548
3550
  assertKeyAlgorithm(skR, this.algorithm)
3549
3551
  return new Uint8Array(
3550
3552
  await subtle(
@@ -3557,6 +3559,25 @@ function MLKEM_SHARED(): KEM_BASE<CryptoKey> {
3557
3559
  }
3558
3560
  }
3559
3561
 
3562
+ function createDirectKEM({ id, name, Nsecret, Nenc, Npk, Nsk }: KEMParams): DirectKEM {
3563
+ const kdf = KDF_SHAKE256()
3564
+ // @ts-expect-error: so that NotSupportedError messages from kdf's subtle() are accurate
3565
+ kdf.name = name
3566
+ return {
3567
+ id,
3568
+ suite_id: concat(L_KEM, I2OSP(id, 2)),
3569
+ type: 'KEM',
3570
+ name,
3571
+ Nsecret,
3572
+ Nenc,
3573
+ Npk,
3574
+ Nsk,
3575
+ algorithm: { name },
3576
+ kdf,
3577
+ ...DIRECT_KEM_SHARED(),
3578
+ }
3579
+ }
3580
+
3560
3581
  // ============================================================================
3561
3582
  // KEM (Key Encapsulation Mechanism) - ML-KEM Suite Exports
3562
3583
  // ============================================================================
@@ -3584,25 +3605,14 @@ function MLKEM_SHARED(): KEM_BASE<CryptoKey> {
3584
3605
  * @group KEM Algorithms
3585
3606
  * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-3)
3586
3607
  */
3587
- export const KEM_ML_KEM_512: KEMFactory<CryptoKey> = function (): MLKEM {
3608
+ export const KEM_ML_KEM_512: KEMFactory<CryptoKey> = function (): DirectKEM {
3588
3609
  const id = 0x0040
3589
3610
  const name = 'ML-KEM-512'
3590
- const kdf = KDF_SHAKE256()
3591
- // @ts-expect-error: so that NotSupportedError messages from kdf's subtle() are accurate
3592
- kdf.name = name
3593
- return {
3594
- id,
3595
- suite_id: concat(L_KEM, I2OSP(id, 2)),
3596
- type: 'KEM',
3597
- name,
3598
- Nsecret: 32,
3599
- Nenc: 768,
3600
- Npk: 800,
3601
- Nsk: 64,
3602
- algorithm: { name: 'ML-KEM-512' },
3603
- kdf,
3604
- ...MLKEM_SHARED(),
3605
- }
3611
+ const Nsecret = 32
3612
+ const Nenc = 768
3613
+ const Npk = 800
3614
+ const Nsk = 64
3615
+ return createDirectKEM({ id, name, Nsecret, Nenc, Npk, Nsk })
3606
3616
  }
3607
3617
 
3608
3618
  /**
@@ -3624,25 +3634,14 @@ export const KEM_ML_KEM_512: KEMFactory<CryptoKey> = function (): MLKEM {
3624
3634
  * @group KEM Algorithms
3625
3635
  * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-3)
3626
3636
  */
3627
- export const KEM_ML_KEM_768: KEMFactory<CryptoKey> = function (): MLKEM {
3637
+ export const KEM_ML_KEM_768: KEMFactory<CryptoKey> = function (): DirectKEM {
3628
3638
  const id = 0x0041
3629
3639
  const name = 'ML-KEM-768'
3630
- const kdf = KDF_SHAKE256()
3631
- // @ts-expect-error: so that NotSupportedError messages from kdf's subtle() are accurate
3632
- kdf.name = name
3633
- return {
3634
- id,
3635
- suite_id: concat(L_KEM, I2OSP(id, 2)),
3636
- type: 'KEM',
3637
- name,
3638
- Nsecret: 32,
3639
- Nenc: 1088,
3640
- Npk: 1184,
3641
- Nsk: 64,
3642
- algorithm: { name: 'ML-KEM-768' },
3643
- kdf,
3644
- ...MLKEM_SHARED(),
3645
- }
3640
+ const Nsecret = 32
3641
+ const Nenc = 1088
3642
+ const Npk = 1184
3643
+ const Nsk = 64
3644
+ return createDirectKEM({ id, name, Nsecret, Nenc, Npk, Nsk })
3646
3645
  }
3647
3646
 
3648
3647
  /**
@@ -3664,25 +3663,14 @@ export const KEM_ML_KEM_768: KEMFactory<CryptoKey> = function (): MLKEM {
3664
3663
  * @group KEM Algorithms
3665
3664
  * @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-3)
3666
3665
  */
3667
- export const KEM_ML_KEM_1024: KEMFactory<CryptoKey> = function (): MLKEM {
3666
+ export const KEM_ML_KEM_1024: KEMFactory<CryptoKey> = function (): DirectKEM {
3668
3667
  const id = 0x0042
3669
3668
  const name = 'ML-KEM-1024'
3670
- const kdf = KDF_SHAKE256()
3671
- // @ts-expect-error: so that NotSupportedError messages from kdf's subtle() are accurate
3672
- kdf.name = name
3673
- return {
3674
- id,
3675
- suite_id: concat(L_KEM, I2OSP(id, 2)),
3676
- type: 'KEM',
3677
- name,
3678
- Nsecret: 32,
3679
- Nenc: 1568,
3680
- Npk: 1568,
3681
- Nsk: 64,
3682
- algorithm: { name: 'ML-KEM-1024' },
3683
- kdf,
3684
- ...MLKEM_SHARED(),
3685
- }
3669
+ const Nsecret = 32
3670
+ const Nenc = 1568
3671
+ const Npk = 1568
3672
+ const Nsk = 64
3673
+ return createDirectKEM({ id, name, Nsecret, Nenc, Npk, Nsk })
3686
3674
  }
3687
3675
 
3688
3676
  interface WebCryptoAEAD extends AEAD {
@@ -3856,7 +3844,7 @@ export const AEAD_ChaCha20Poly1305: AEADFactory = function AEAD_ChaCha20Poly1305
3856
3844
  }
3857
3845
 
3858
3846
  // ============================================================================
3859
- // KEM (Key Encapsulation Mechanism) - Hybrid KEM Types and Implementation
3847
+ // KEM (Key Encapsulation Mechanism) - Composite Hybrid KEM Types and Implementation
3860
3848
  // ============================================================================
3861
3849
 
3862
3850
  /* c8 ignore next 5 */
@@ -3956,7 +3944,7 @@ function split(N1: number, N2: number, x: Uint8Array): [Uint8Array, Uint8Array]
3956
3944
  return [x1, x2]
3957
3945
  }
3958
3946
 
3959
- function RandomScalarNist(t: HybridKEM['t'], seed: Uint8Array): Uint8Array {
3947
+ function RandomScalarNist(t: CompositeHybridKEM['t'], seed: Uint8Array): Uint8Array {
3960
3948
  let sk_bigint = 0n
3961
3949
  let start = 0
3962
3950
  let end = t.Nscalar!
@@ -3974,69 +3962,69 @@ function RandomScalarNist(t: HybridKEM['t'], seed: Uint8Array): Uint8Array {
3974
3962
  }
3975
3963
 
3976
3964
  /** @see [expandDecapsKeyG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.1) */
3977
- async function expandDecapsKeyG(PQTKEM: HybridKEM, seed: Uint8Array) {
3978
- const Nout = PQTKEM.pq.Nseed + PQTKEM.t.Nseed
3965
+ async function expandDecapsKeyG(kem: CompositeHybridKEM, seed: Uint8Array) {
3966
+ const Nout = kem.pq.Nseed + kem.t.Nseed
3979
3967
  const bits = Nout << 3
3980
3968
  // @ts-expect-error
3981
3969
  const algorithm: CShakeParams = { name: 'cSHAKE256', length: bits, outputLength: bits }
3982
- const seed_full = await subtle((c) => c.digest(algorithm, seed as BufferSource), PQTKEM.name)
3970
+ const seed_full = await subtle((c) => c.digest(algorithm, seed as BufferSource), kem.name)
3983
3971
 
3984
- const [seed_PQ, seed_T] = split(PQTKEM.pq.Nseed, PQTKEM.t.Nseed, new Uint8Array(seed_full))
3972
+ const [seed_PQ, seed_T] = split(kem.pq.Nseed, kem.t.Nseed, new Uint8Array(seed_full))
3985
3973
 
3986
3974
  // @ts-expect-error
3987
3975
  const format: Exclude<KeyFormat, 'jwk'> = 'raw-seed'
3988
3976
  // @ts-expect-error
3989
3977
  const usages: [KeyUsage, KeyUsage] = ['decapsulateBits', 'encapsulateBits']
3990
3978
  const dk_PQ = await subtle(
3991
- (c) => c.importKey(format, seed_PQ as BufferSource, PQTKEM.pq.algorithm, true, [usages[0]]),
3992
- PQTKEM.name,
3979
+ (c) => c.importKey(format, seed_PQ as BufferSource, kem.pq.algorithm, true, [usages[0]]),
3980
+ kem.name,
3993
3981
  )
3994
- const ek_PQ = await getPublicKey(PQTKEM.name, dk_PQ, [usages[1]])
3982
+ const ek_PQ = await getPublicKey(kem.name, dk_PQ, [usages[1]])
3995
3983
 
3996
- const sk = PQTKEM.t.RandomScalar?.(seed_T) ?? seed_T
3997
- const { privateKey: dk_T, publicKey: ek_T } = await PQTKEM.t.GetKeyPair(sk)
3984
+ const sk = kem.t.RandomScalar?.(seed_T) ?? seed_T
3985
+ const { privateKey: dk_T, publicKey: ek_T } = await kem.t.GetKeyPair(sk)
3998
3986
 
3999
3987
  return { ek_PQ, ek_T, dk_PQ, dk_T }
4000
3988
  }
4001
3989
 
4002
3990
  /** @see [C2PRICombiner](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.3) */
4003
3991
  async function C2PRICombiner(
4004
- PQTKEM: HybridKEM,
3992
+ kem: CompositeHybridKEM,
4005
3993
  ss_PQ: Uint8Array,
4006
3994
  ss_T: Uint8Array,
4007
3995
  ct_T: Uint8Array,
4008
3996
  _ek_T: CryptoKey,
4009
3997
  label: Uint8Array,
4010
3998
  ): Promise<Uint8Array> {
4011
- const ek_T = new Uint8Array(await subtle((c) => c.exportKey('raw', _ek_T), PQTKEM.name))
3999
+ const ek_T = new Uint8Array(await subtle((c) => c.exportKey('raw', _ek_T), kem.name))
4012
4000
  const data = concat(ss_PQ, ss_T, ct_T, ek_T, label) as BufferSource
4013
- return new Uint8Array(await subtle((c) => c.digest('SHA3-256', data), PQTKEM.name))
4001
+ return new Uint8Array(await subtle((c) => c.digest('SHA3-256', data), kem.name))
4014
4002
  }
4015
4003
 
4016
4004
  /** @see [prepareEncapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.1) */
4017
4005
  async function prepareEncapsG(
4018
- PQTKEM: HybridKEM,
4006
+ kem: CompositeHybridKEM,
4019
4007
  ek_PQ: CryptoKey,
4020
4008
  ek_T: CryptoKey,
4021
4009
  ): Promise<[Uint8Array, Uint8Array, Uint8Array, Uint8Array]> {
4022
4010
  const res = (await subtle(
4023
4011
  // @ts-expect-error
4024
- (c) => c.encapsulateBits(PQTKEM.pq.algorithm, ek_PQ),
4025
- PQTKEM.name,
4012
+ (c) => c.encapsulateBits(kem.pq.algorithm, ek_PQ),
4013
+ kem.name,
4026
4014
  )) as { sharedKey: ArrayBuffer; ciphertext: ArrayBuffer }
4027
4015
  const ss_PQ = new Uint8Array(res.sharedKey)
4028
4016
  const ct_PQ = new Uint8Array(res.ciphertext)
4029
4017
 
4030
4018
  const { privateKey: sk_E, publicKey } = (await subtle(
4031
- (c) => c.generateKey(PQTKEM.t.algorithm, false, ['deriveBits']),
4032
- PQTKEM.name,
4019
+ (c) => c.generateKey(kem.t.algorithm, true, ['deriveBits']),
4020
+ kem.name,
4033
4021
  )) as CryptoKeyPair
4034
- const ct_T = new Uint8Array(await subtle((c) => c.exportKey('raw', publicKey), PQTKEM.name))
4022
+ const ct_T = new Uint8Array(await subtle((c) => c.exportKey('raw', publicKey), kem.name))
4035
4023
 
4036
4024
  const ss_T = new Uint8Array(
4037
4025
  await subtle(
4038
- (c) => c.deriveBits({ name: PQTKEM.t.algorithm.name, public: ek_T }, sk_E, PQTKEM.t.Nss << 3),
4039
- PQTKEM.name,
4026
+ (c) => c.deriveBits({ name: kem.t.algorithm.name, public: ek_T }, sk_E, kem.t.Nss << 3),
4027
+ kem.name,
4040
4028
  ),
4041
4029
  )
4042
4030
  checkNotAllZeros(ss_T)
@@ -4046,7 +4034,7 @@ async function prepareEncapsG(
4046
4034
 
4047
4035
  /** @see [prepareDecapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.1) */
4048
4036
  async function prepareDecapsG(
4049
- PQTKEM: HybridKEM,
4037
+ kem: CompositeHybridKEM,
4050
4038
  dk_PQ: CryptoKey,
4051
4039
  dk_T: CryptoKey,
4052
4040
  ct_PQ: Uint8Array,
@@ -4055,20 +4043,20 @@ async function prepareDecapsG(
4055
4043
  const ss_PQ = new Uint8Array(
4056
4044
  await subtle(
4057
4045
  // @ts-expect-error
4058
- (c) => c.decapsulateBits(PQTKEM.pq.algorithm, dk_PQ, ct_PQ),
4059
- PQTKEM.name,
4046
+ (c) => c.decapsulateBits(kem.pq.algorithm, dk_PQ, ct_PQ),
4047
+ kem.name,
4060
4048
  ),
4061
4049
  )
4062
4050
 
4063
4051
  const pub = await subtle(
4064
- (c) => c.importKey('raw', ct_T as BufferSource, PQTKEM.t.algorithm, true, []),
4065
- PQTKEM.name,
4052
+ (c) => c.importKey('raw', ct_T as BufferSource, kem.t.algorithm, true, []),
4053
+ kem.name,
4066
4054
  )
4067
4055
 
4068
4056
  const ss_T = new Uint8Array(
4069
4057
  await subtle(
4070
- (c) => c.deriveBits({ name: PQTKEM.t.algorithm.name, public: pub }, dk_T, PQTKEM.t.Nss << 3),
4071
- PQTKEM.name,
4058
+ (c) => c.deriveBits({ name: kem.t.algorithm.name, public: pub }, dk_T, kem.t.Nss << 3),
4059
+ kem.name,
4072
4060
  ),
4073
4061
  )
4074
4062
  checkNotAllZeros(ss_T)
@@ -4076,7 +4064,7 @@ async function prepareDecapsG(
4076
4064
  return [ss_PQ, ss_T]
4077
4065
  }
4078
4066
 
4079
- interface HybridKEM extends KEM<HybridKey> {
4067
+ interface CompositeHybridKEM extends KEM<HybridKey> {
4080
4068
  readonly suite_id: Uint8Array
4081
4069
  readonly kdf: KDF
4082
4070
  readonly algorithm: KeyAlgorithm
@@ -4096,18 +4084,20 @@ interface HybridKEM extends KEM<HybridKey> {
4096
4084
  readonly Nsk: number
4097
4085
  readonly Nscalar?: number
4098
4086
  readonly GetKeyPair: (
4099
- this: HybridKEM['t'],
4087
+ this: CompositeHybridKEM['t'],
4100
4088
  sk: Uint8Array,
4101
4089
  ) => Promise<{ privateKey: CryptoKey; publicKey: CryptoKey }>
4102
4090
  readonly order?: bigint
4103
- readonly RandomScalar?: (this: HybridKEM['t'], seed: Uint8Array) => Uint8Array
4091
+ readonly RandomScalar?: (this: CompositeHybridKEM['t'], seed: Uint8Array) => Uint8Array
4104
4092
  }
4105
4093
  }
4106
4094
 
4107
- function PQTKEM_SHARED(): KEM_BASE<HybridKey> {
4095
+ type CompositeHybridKEMParams = KEMParams & Pick<CompositeHybridKEM, 'pq' | 't' | 'label'>
4096
+
4097
+ function COMPOSITE_HYBRID_KEM_SHARED(): KEM_BASE<HybridKey> {
4108
4098
  Object.freeze(HybridKey.prototype)
4109
4099
  return {
4110
- async DeriveKeyPair(this: HybridKEM, ikm: Uint8Array, extractable) {
4100
+ async DeriveKeyPair(this: CompositeHybridKEM, ikm: Uint8Array, extractable) {
4111
4101
  const seed = await LabeledDerive(
4112
4102
  this.kdf,
4113
4103
  this.suite_id,
@@ -4133,10 +4123,10 @@ function PQTKEM_SHARED(): KEM_BASE<HybridKey> {
4133
4123
 
4134
4124
  return { privateKey, publicKey }
4135
4125
  },
4136
- async GenerateKeyPair(this: HybridKEM, extractable) {
4126
+ async GenerateKeyPair(this: CompositeHybridKEM, extractable) {
4137
4127
  return await this.DeriveKeyPair(crypto.getRandomValues(new Uint8Array(32)), extractable)
4138
4128
  },
4139
- async SerializePublicKey(this: HybridKEM, key) {
4129
+ async SerializePublicKey(this: CompositeHybridKEM, key) {
4140
4130
  assertKeyAlgorithm(key, this.algorithm)
4141
4131
  HybridKey.validate(key, true)
4142
4132
  // @ts-expect-error
@@ -4150,7 +4140,7 @@ function PQTKEM_SHARED(): KEM_BASE<HybridKey> {
4150
4140
 
4151
4141
  return concat(ek_PQ, ek_T)
4152
4142
  },
4153
- async DeserializePublicKey(this: HybridKEM, key) {
4143
+ async DeserializePublicKey(this: CompositeHybridKEM, key) {
4154
4144
  // @ts-expect-error
4155
4145
  const format: Exclude<KeyFormat, 'jwk'> = 'raw-public'
4156
4146
  // @ts-expect-error
@@ -4164,13 +4154,13 @@ function PQTKEM_SHARED(): KEM_BASE<HybridKey> {
4164
4154
 
4165
4155
  return new HybridKey(priv, this.algorithm, 'public', true, ek_PQ, ek_T)
4166
4156
  },
4167
- async SerializePrivateKey(this: HybridKEM, key) {
4157
+ async SerializePrivateKey(this: CompositeHybridKEM, key) {
4168
4158
  assertKeyAlgorithm(key, this.algorithm)
4169
4159
  HybridKey.validate(key, true)
4170
4160
 
4171
4161
  return key.getSeed(priv)
4172
4162
  },
4173
- async DeserializePrivateKey(this: HybridKEM, key, extractable) {
4163
+ async DeserializePrivateKey(this: CompositeHybridKEM, key, extractable) {
4174
4164
  const { ek_PQ, ek_T, dk_PQ, dk_T } = await expandDecapsKeyG(this, key)
4175
4165
  const publicKey = new HybridKey(priv, this.algorithm, 'public', true, ek_PQ, ek_T)
4176
4166
  const privateKey = new HybridKey(
@@ -4186,7 +4176,7 @@ function PQTKEM_SHARED(): KEM_BASE<HybridKey> {
4186
4176
 
4187
4177
  return privateKey
4188
4178
  },
4189
- async Encap(this: HybridKEM, pkR) {
4179
+ async Encap(this: CompositeHybridKEM, pkR) {
4190
4180
  assertKeyAlgorithm(pkR, this.algorithm)
4191
4181
  HybridKey.validate(pkR)
4192
4182
 
@@ -4198,7 +4188,7 @@ function PQTKEM_SHARED(): KEM_BASE<HybridKey> {
4198
4188
 
4199
4189
  return { shared_secret: ss_H, enc: ct_H }
4200
4190
  },
4201
- async Decap(this: HybridKEM, enc, skR, pkR) {
4191
+ async Decap(this: CompositeHybridKEM, enc, skR, pkR) {
4202
4192
  assertKeyAlgorithm(skR, this.algorithm)
4203
4193
  HybridKey.validate(skR)
4204
4194
 
@@ -4220,6 +4210,20 @@ function PQTKEM_SHARED(): KEM_BASE<HybridKey> {
4220
4210
  }
4221
4211
  }
4222
4212
 
4213
+ function createCompositeHybridKEM(parameters: CompositeHybridKEMParams): CompositeHybridKEM {
4214
+ const kdf = KDF_SHAKE256()
4215
+ // @ts-expect-error: so that NotSupportedError messages from kdf's subtle() are accurate
4216
+ kdf.name = parameters.name
4217
+ return {
4218
+ ...parameters,
4219
+ suite_id: concat(L_KEM, I2OSP(parameters.id, 2)),
4220
+ type: 'KEM',
4221
+ algorithm: { name: parameters.name },
4222
+ kdf,
4223
+ ...COMPOSITE_HYBRID_KEM_SHARED(),
4224
+ }
4225
+ }
4226
+
4223
4227
  // ============================================================================
4224
4228
  // KEM (Key Encapsulation Mechanism) - Hybrid KEM Suite Exports
4225
4229
  // ============================================================================
@@ -4227,7 +4231,12 @@ function PQTKEM_SHARED(): KEM_BASE<HybridKey> {
4227
4231
  /**
4228
4232
  * Hybrid KEM combining ML-KEM-768 with X25519 (MLKEM768-X25519).
4229
4233
  *
4230
- * Depends on the following Web Cryptography algorithms being supported in the runtime:
4234
+ * Depends on one of the following Web Cryptography algorithm sets being supported in the runtime:
4235
+ *
4236
+ * - MLKEM768-X25519 key encapsulation
4237
+ * - SHAKE256 (cSHAKE256 without any parameters) digest on the recipient for key derivation
4238
+ *
4239
+ * Or:
4231
4240
  *
4232
4241
  * - ML-KEM-768 key encapsulation
4233
4242
  * - X25519 key agreement
@@ -4243,24 +4252,22 @@ function PQTKEM_SHARED(): KEM_BASE<HybridKey> {
4243
4252
  * @group KEM Algorithms
4244
4253
  * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-4)
4245
4254
  */
4246
- export const KEM_MLKEM768_X25519: KEMFactory = function (): HybridKEM {
4255
+ export const KEM_MLKEM768_X25519: KEMFactory = function (): CompositeHybridKEM | DirectKEM {
4247
4256
  const id = 0x647a
4248
4257
  const name = 'MLKEM768-X25519'
4249
- const kdf = KDF_SHAKE256()
4258
+ const Nsecret = 32
4259
+ const Nenc = 1120
4260
+ const Npk = 1216
4261
+ const Nsk = 32
4262
+ const kem = { id, name, Nsecret, Nenc, Npk, Nsk }
4263
+ // @ts-expect-error
4264
+ if (SubtleCrypto.supports?.('generateKey', name) ?? false) {
4265
+ return createDirectKEM(kem)
4266
+ }
4267
+
4250
4268
  const pkcs8 = Uint8Array.of(0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x6e, 0x04, 0x22, 0x04, 0x20) // prettier-ignore
4251
- // @ts-expect-error: so that NotSupportedError messages from kdf's subtle() are accurate
4252
- kdf.name = name
4253
- return {
4254
- id,
4255
- kdf,
4256
- suite_id: concat(L_KEM, I2OSP(id, 2)),
4257
- type: 'KEM',
4258
- name,
4259
- Nsecret: 32,
4260
- Nenc: 1120,
4261
- Npk: 1216,
4262
- Nsk: 32,
4263
- algorithm: { name: 'MLKEM768-X25519' },
4269
+ return createCompositeHybridKEM({
4270
+ ...kem,
4264
4271
  pq: { algorithm: { name: 'ML-KEM-768' }, Nseed: 64, Npk: 1184, Nct: 1088 },
4265
4272
  t: {
4266
4273
  algorithm: { name: 'X25519' },
@@ -4277,14 +4284,18 @@ export const KEM_MLKEM768_X25519: KEMFactory = function (): HybridKEM {
4277
4284
  },
4278
4285
  },
4279
4286
  label: Uint8Array.of(0x5c, 0x2e, 0x2f, 0x2f, 0x5e, 0x5c), // prettier-ignore
4280
- ...PQTKEM_SHARED(),
4281
- }
4287
+ })
4282
4288
  }
4283
4289
 
4284
4290
  /**
4285
4291
  * Hybrid KEM combining ML-KEM-768 with P-256 (MLKEM768-P256).
4286
4292
  *
4287
- * Depends on the following Web Cryptography algorithms being supported in the runtime:
4293
+ * Depends on one of the following Web Cryptography algorithm sets being supported in the runtime:
4294
+ *
4295
+ * - MLKEM768-P256 key encapsulation
4296
+ * - SHAKE256 (cSHAKE256 without any parameters) digest on the recipient for key derivation
4297
+ *
4298
+ * Or:
4288
4299
  *
4289
4300
  * - ML-KEM-768 key encapsulation
4290
4301
  * - ECDH with P-256 curve
@@ -4300,23 +4311,21 @@ export const KEM_MLKEM768_X25519: KEMFactory = function (): HybridKEM {
4300
4311
  * @group KEM Algorithms
4301
4312
  * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-4)
4302
4313
  */
4303
- export const KEM_MLKEM768_P256: KEMFactory = function (): HybridKEM {
4314
+ export const KEM_MLKEM768_P256: KEMFactory = function (): CompositeHybridKEM | DirectKEM {
4304
4315
  const id = 0x0050
4305
4316
  const name = 'MLKEM768-P256'
4306
- const kdf = KDF_SHAKE256()
4307
- // @ts-expect-error: so that NotSupportedError messages from kdf's subtle() are accurate
4308
- kdf.name = name
4309
- return {
4310
- id,
4311
- kdf,
4312
- suite_id: concat(L_KEM, I2OSP(id, 2)),
4313
- type: 'KEM',
4314
- name,
4315
- Nsecret: 32,
4316
- Nenc: 1153,
4317
- Npk: 1249,
4318
- Nsk: 32,
4319
- algorithm: { name: 'MLKEM768-P256' },
4317
+ const Nsecret = 32
4318
+ const Nenc = 1153
4319
+ const Npk = 1249
4320
+ const Nsk = 32
4321
+ const kem = { id, name, Nsecret, Nenc, Npk, Nsk }
4322
+ // @ts-expect-error
4323
+ if (SubtleCrypto.supports?.('generateKey', name) ?? false) {
4324
+ return createDirectKEM(kem)
4325
+ }
4326
+
4327
+ return createCompositeHybridKEM({
4328
+ ...kem,
4320
4329
  pq: { algorithm: { name: 'ML-KEM-768' }, Nseed: 64, Npk: 1184, Nct: 1088 },
4321
4330
  t: {
4322
4331
  ...P256,
@@ -4333,14 +4342,18 @@ export const KEM_MLKEM768_P256: KEMFactory = function (): HybridKEM {
4333
4342
  },
4334
4343
  },
4335
4344
  label: Uint8Array.of(0x4d, 0x4c, 0x4b, 0x45, 0x4d, 0x37, 0x36, 0x38, 0x2d, 0x50, 0x32, 0x35, 0x36), // prettier-ignore
4336
- ...PQTKEM_SHARED(),
4337
- }
4345
+ })
4338
4346
  }
4339
4347
 
4340
4348
  /**
4341
4349
  * Hybrid KEM combining ML-KEM-1024 with P-384 (MLKEM1024-P384).
4342
4350
  *
4343
- * Depends on the following Web Cryptography algorithms being supported in the runtime:
4351
+ * Depends on one of the following Web Cryptography algorithm sets being supported in the runtime:
4352
+ *
4353
+ * - MLKEM1024-P384 key encapsulation
4354
+ * - SHAKE256 (cSHAKE256 without any parameters) digest on the recipient for key derivation
4355
+ *
4356
+ * Or:
4344
4357
  *
4345
4358
  * - ML-KEM-1024 key encapsulation
4346
4359
  * - ECDH with P-384 curve
@@ -4356,23 +4369,21 @@ export const KEM_MLKEM768_P256: KEMFactory = function (): HybridKEM {
4356
4369
  * @group KEM Algorithms
4357
4370
  * @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-4)
4358
4371
  */
4359
- export const KEM_MLKEM1024_P384: KEMFactory = function (): HybridKEM {
4372
+ export const KEM_MLKEM1024_P384: KEMFactory = function (): CompositeHybridKEM | DirectKEM {
4360
4373
  const id = 0x0051
4361
4374
  const name = 'MLKEM1024-P384'
4362
- const kdf = KDF_SHAKE256()
4363
- // @ts-expect-error: so that NotSupportedError messages from kdf's subtle() are accurate
4364
- kdf.name = name
4365
- return {
4366
- id,
4367
- kdf,
4368
- suite_id: concat(L_KEM, I2OSP(id, 2)),
4369
- type: 'KEM',
4370
- name,
4371
- Nsecret: 32,
4372
- Nenc: 1665,
4373
- Npk: 1665,
4374
- Nsk: 32,
4375
- algorithm: { name: 'MLKEM1024-P384' },
4375
+ const Nsecret = 32
4376
+ const Nenc = 1665
4377
+ const Npk = 1665
4378
+ const Nsk = 32
4379
+ const kem = { id, name, Nsecret, Nenc, Npk, Nsk }
4380
+ // @ts-expect-error
4381
+ if (SubtleCrypto.supports?.('generateKey', name) ?? false) {
4382
+ return createDirectKEM(kem)
4383
+ }
4384
+
4385
+ return createCompositeHybridKEM({
4386
+ ...kem,
4376
4387
  pq: { algorithm: { name: 'ML-KEM-1024' }, Nseed: 64, Npk: 1568, Nct: 1568 },
4377
4388
  t: {
4378
4389
  ...P384,
@@ -4390,6 +4401,5 @@ export const KEM_MLKEM1024_P384: KEMFactory = function (): HybridKEM {
4390
4401
  },
4391
4402
  },
4392
4403
  label: Uint8Array.of(0x4d, 0x4c, 0x4b, 0x45, 0x4d, 0x31, 0x30, 0x32, 0x34, 0x2d, 0x50, 0x33, 0x38, 0x34), // prettier-ignore
4393
- ...PQTKEM_SHARED(),
4394
- }
4404
+ })
4395
4405
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hpke",
3
- "version": "1.1.4",
3
+ "version": "1.1.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",
@@ -45,12 +45,13 @@
45
45
  "check:packaging": "publint run . --strict && node tools/attw-check.js . && publint run examples/noble-suite --strict && node tools/attw-check.js examples/noble-suite",
46
46
  "docs": "npx typedoc",
47
47
  "format": "prettier --log-level silent --cache --write '**/*.{ts,js,mjs,cjs,json,yml}' '**/README.md'",
48
- "test": "node --test --no-warnings test/*.ts",
48
+ "test": "node --test --no-warnings test/*.ts test/noble-version.js",
49
49
  "test:browsers": "node test/browser.mjs",
50
50
  "test:bun": "bun test ./test/*.ts",
51
51
  "test:deno": "deno test --no-check --allow-read test/*.ts",
52
52
  "test:dist": "node tools/test-dist.js",
53
53
  "test:docs": "./check-examples.sh",
54
+ "test:llrt": "./test/.llrt.sh",
54
55
  "test:workerd": "./test/.workerd.sh",
55
56
  "typecheck:types": "tsc -p test-d && tsc -p test-d/tsconfig.node.json && tsc -p test-d/tsconfig.fallback.json"
56
57
  },
@@ -59,10 +60,11 @@
59
60
  "@noble/ciphers": "^2.3.0",
60
61
  "@noble/curves": "^2.3.0",
61
62
  "@noble/hashes": "^2.3.0",
62
- "@noble/post-quantum": "^0.7.0",
63
+ "@noble/post-quantum": "^0.7.1",
63
64
  "@types/node": "^24.13.3",
64
65
  "amaro": "^1.1.11",
65
- "esbuild": "^0.28.1",
66
+ "esbuild": "^0.28.2",
67
+ "fast-check": "4.9.0",
66
68
  "playwright": "^1.62.1",
67
69
  "prettier": "^3.9.6",
68
70
  "prettier-plugin-jsdoc": "^1.8.1",