hpke 1.1.3 → 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/README.md +5 -5
- package/index.d.ts +157 -102
- package/index.d.ts.map +1 -1
- package/index.js +231 -175
- package/index.ts +338 -282
- package/package.json +20 -13
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-
|
|
8
|
+
* [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04).
|
|
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-
|
|
45
|
+
/** @see [ComputeNonce](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#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-
|
|
66
|
+
/** @see [Context.IncrementSeq](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#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,7 @@ 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-
|
|
74
|
+
/** @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.3) */
|
|
75
75
|
async function ContextExport(
|
|
76
76
|
suite: Triple,
|
|
77
77
|
exporterSecret: Uint8Array,
|
|
@@ -129,14 +129,14 @@ class SenderContext {
|
|
|
129
129
|
#key: Uint8Array
|
|
130
130
|
#base_nonce: Uint8Array
|
|
131
131
|
#exporter_secret: Uint8Array
|
|
132
|
-
#mode:
|
|
132
|
+
#mode: Mode
|
|
133
133
|
#seq: number = 0
|
|
134
134
|
#max_seq: number
|
|
135
135
|
#mutex?: Mutex
|
|
136
136
|
|
|
137
137
|
constructor(
|
|
138
138
|
suite: Triple,
|
|
139
|
-
mode:
|
|
139
|
+
mode: Mode,
|
|
140
140
|
key: Uint8Array,
|
|
141
141
|
base_nonce: Uint8Array,
|
|
142
142
|
exporter_secret: Uint8Array,
|
|
@@ -154,7 +154,7 @@ class SenderContext {
|
|
|
154
154
|
* @see {@link MODE_BASE}
|
|
155
155
|
* @see {@link MODE_PSK}
|
|
156
156
|
*/
|
|
157
|
-
get mode():
|
|
157
|
+
get mode(): Mode {
|
|
158
158
|
return this.#mode
|
|
159
159
|
}
|
|
160
160
|
|
|
@@ -192,7 +192,7 @@ class SenderContext {
|
|
|
192
192
|
*
|
|
193
193
|
* @returns A Promise that resolves to the ciphertext. The ciphertext is {@link Nt} bytes longer
|
|
194
194
|
* than the plaintext.
|
|
195
|
-
* @see [Context.Seal](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
195
|
+
* @see [Context.Seal](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.2)
|
|
196
196
|
*/
|
|
197
197
|
async Seal(plaintext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array> {
|
|
198
198
|
checkUint8Array(plaintext, 'plaintext')
|
|
@@ -240,7 +240,7 @@ class SenderContext {
|
|
|
240
240
|
* @param length - Desired length of exported secret in bytes
|
|
241
241
|
*
|
|
242
242
|
* @returns A Promise that resolves to the exported secret.
|
|
243
|
-
* @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
243
|
+
* @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.3)
|
|
244
244
|
*/
|
|
245
245
|
async Export(exporterContext: Uint8Array, length: number): Promise<Uint8Array> {
|
|
246
246
|
return await ContextExport(this.#suite, this.#exporter_secret, exporterContext, length)
|
|
@@ -280,14 +280,14 @@ class RecipientContext {
|
|
|
280
280
|
#key: Uint8Array
|
|
281
281
|
#base_nonce: Uint8Array
|
|
282
282
|
#exporter_secret: Uint8Array
|
|
283
|
-
#mode:
|
|
283
|
+
#mode: Mode
|
|
284
284
|
#seq: number = 0
|
|
285
285
|
#max_seq: number
|
|
286
286
|
#mutex?: Mutex
|
|
287
287
|
|
|
288
288
|
constructor(
|
|
289
289
|
suite: Triple,
|
|
290
|
-
mode:
|
|
290
|
+
mode: Mode,
|
|
291
291
|
key: Uint8Array,
|
|
292
292
|
base_nonce: Uint8Array,
|
|
293
293
|
exporter_secret: Uint8Array,
|
|
@@ -305,7 +305,7 @@ class RecipientContext {
|
|
|
305
305
|
* @see {@link MODE_BASE}
|
|
306
306
|
* @see {@link MODE_PSK}
|
|
307
307
|
*/
|
|
308
|
-
get mode():
|
|
308
|
+
get mode(): Mode {
|
|
309
309
|
return this.#mode
|
|
310
310
|
}
|
|
311
311
|
|
|
@@ -344,7 +344,7 @@ class RecipientContext {
|
|
|
344
344
|
* @param aad - Additional authenticated data
|
|
345
345
|
*
|
|
346
346
|
* @returns A Promise that resolves to the decrypted plaintext.
|
|
347
|
-
* @see [Context.Open](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
347
|
+
* @see [Context.Open](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.2)
|
|
348
348
|
*/
|
|
349
349
|
async Open(ciphertext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array> {
|
|
350
350
|
checkUint8Array(ciphertext, 'ciphertext')
|
|
@@ -401,7 +401,7 @@ class RecipientContext {
|
|
|
401
401
|
* @param length - Desired length of exported secret in bytes
|
|
402
402
|
*
|
|
403
403
|
* @returns A Promise that resolves to the exported secret.
|
|
404
|
-
* @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
404
|
+
* @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.3)
|
|
405
405
|
*/
|
|
406
406
|
async Export(exporterContext: Uint8Array, length: number): Promise<Uint8Array> {
|
|
407
407
|
return await ContextExport(this.#suite, this.#exporter_secret, exporterContext, length)
|
|
@@ -432,7 +432,7 @@ const validate = <T extends { type: string }>(factory: () => T, type: string): T
|
|
|
432
432
|
* asymmetric key exchange with a symmetric cipher. This was originally defined in an Informational
|
|
433
433
|
* document on the IRTF stream as [RFC 9180](https://www.rfc-editor.org/rfc/rfc9180.html) and is now
|
|
434
434
|
* being republished as a Standards Track document of the IETF as
|
|
435
|
-
* [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
435
|
+
* [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04).
|
|
436
436
|
*
|
|
437
437
|
* HPKE provides a variant of public key encryption for arbitrary-sized plaintexts using a recipient
|
|
438
438
|
* public key. It supports two modes:
|
|
@@ -446,10 +446,11 @@ const validate = <T extends { type: string }>(factory: () => T, type: string): T
|
|
|
446
446
|
* - KDF: Key Derivation Function for deriving symmetric keys
|
|
447
447
|
* - AEAD: Authenticated Encryption with Additional Data for encryption
|
|
448
448
|
*
|
|
449
|
+
* @typeParam K - Key representation produced and consumed by the suite's KEM
|
|
449
450
|
* @group Core
|
|
450
451
|
*/
|
|
451
|
-
export class CipherSuite {
|
|
452
|
-
#suite: Triple
|
|
452
|
+
export class CipherSuite<K extends Key = Key> {
|
|
453
|
+
#suite: Triple<K>
|
|
453
454
|
|
|
454
455
|
/**
|
|
455
456
|
* Creates a new HPKE cipher suite by combining a Key Encapsulation Mechanism (KEM), Key
|
|
@@ -512,7 +513,7 @@ export class CipherSuite {
|
|
|
512
513
|
* @see {@link KDFFactory Available KDFs}
|
|
513
514
|
* @see {@link AEADFactory Available AEADs}
|
|
514
515
|
*/
|
|
515
|
-
constructor(KEM: KEMFactory
|
|
516
|
+
constructor(KEM: KEMFactory<K>, KDF: KDFFactory, AEAD: AEADFactory) {
|
|
516
517
|
const kem = validate(KEM, 'KEM')
|
|
517
518
|
const kdf = validate(KDF, 'KDF')
|
|
518
519
|
const aead = validate(AEAD, 'AEAD')
|
|
@@ -532,17 +533,17 @@ export class CipherSuite {
|
|
|
532
533
|
*/
|
|
533
534
|
get KEM(): {
|
|
534
535
|
/** The identifier of this suite's KEM */
|
|
535
|
-
id: number
|
|
536
|
+
readonly id: number
|
|
536
537
|
/** The name of this suite's KEM */
|
|
537
|
-
name: string
|
|
538
|
+
readonly name: string
|
|
538
539
|
/** The length in bytes of this suite's KEM produced shared secret */
|
|
539
|
-
Nsecret: number
|
|
540
|
+
readonly Nsecret: number
|
|
540
541
|
/** The length in bytes of this suite's KEM produced encapsulated secret */
|
|
541
|
-
Nenc: number
|
|
542
|
+
readonly Nenc: number
|
|
542
543
|
/** The length in bytes of this suite's KEM public key */
|
|
543
|
-
Npk: number
|
|
544
|
+
readonly Npk: number
|
|
544
545
|
/** The length in bytes of this suite's KEM private key */
|
|
545
|
-
Nsk: number
|
|
546
|
+
readonly Nsk: number
|
|
546
547
|
} {
|
|
547
548
|
return {
|
|
548
549
|
id: this.#suite.KEM.id,
|
|
@@ -561,21 +562,21 @@ export class CipherSuite {
|
|
|
561
562
|
*/
|
|
562
563
|
get KDF(): {
|
|
563
564
|
/** The identifier of this suite's KDF */
|
|
564
|
-
id: number
|
|
565
|
+
readonly id: number
|
|
565
566
|
/** The name of this suite's KDF */
|
|
566
|
-
name: string
|
|
567
|
+
readonly name: string
|
|
567
568
|
/**
|
|
568
569
|
* When 1, this suite's KDF is a one-stage (Derive) KDF.
|
|
569
570
|
*
|
|
570
571
|
* When 2, this suite's KDF is a two-stage (Extract and Expand) KDF.
|
|
571
572
|
*/
|
|
572
|
-
stages: 1 | 2
|
|
573
|
+
readonly stages: 1 | 2
|
|
573
574
|
/**
|
|
574
575
|
* For one-stage KDF: The security strength of this suite's KDF, in bytes.
|
|
575
576
|
*
|
|
576
577
|
* For two-stage KDF: The output size of this suite's KDF Extract() function in bytes.
|
|
577
578
|
*/
|
|
578
|
-
Nh: number
|
|
579
|
+
readonly Nh: number
|
|
579
580
|
} {
|
|
580
581
|
return {
|
|
581
582
|
id: this.#suite.KDF.id,
|
|
@@ -593,15 +594,15 @@ export class CipherSuite {
|
|
|
593
594
|
*/
|
|
594
595
|
get AEAD(): {
|
|
595
596
|
/** The identifier of this suite's AEAD */
|
|
596
|
-
id: number
|
|
597
|
+
readonly id: number
|
|
597
598
|
/** The name of this suite's AEAD */
|
|
598
|
-
name: string
|
|
599
|
+
readonly name: string
|
|
599
600
|
/** The length in bytes of a key for this suite's AEAD */
|
|
600
|
-
Nk: number
|
|
601
|
+
readonly Nk: number
|
|
601
602
|
/** The length in bytes of a nonce for this suite's AEAD */
|
|
602
|
-
Nn: number
|
|
603
|
+
readonly Nn: number
|
|
603
604
|
/** The length in bytes of an authentication tag for this suite's AEAD */
|
|
604
|
-
Nt: number
|
|
605
|
+
readonly Nt: number
|
|
605
606
|
} {
|
|
606
607
|
return {
|
|
607
608
|
id: this.#suite.AEAD.id,
|
|
@@ -629,7 +630,7 @@ export class CipherSuite {
|
|
|
629
630
|
*
|
|
630
631
|
* @returns A Promise that resolves to a generated key pair.
|
|
631
632
|
*/
|
|
632
|
-
async GenerateKeyPair(extractable?: boolean): Promise<KeyPair
|
|
633
|
+
async GenerateKeyPair(extractable?: boolean): Promise<KeyPair<K>> {
|
|
633
634
|
extractable ??= false
|
|
634
635
|
checkExtractable(extractable)
|
|
635
636
|
return await this.#suite.KEM.GenerateKeyPair(extractable)
|
|
@@ -662,7 +663,7 @@ export class CipherSuite {
|
|
|
662
663
|
*
|
|
663
664
|
* @returns A Promise that resolves to the derived key pair.
|
|
664
665
|
*/
|
|
665
|
-
async DeriveKeyPair(ikm: Uint8Array, extractable?: boolean): Promise<KeyPair
|
|
666
|
+
async DeriveKeyPair(ikm: Uint8Array, extractable?: boolean): Promise<KeyPair<K>> {
|
|
666
667
|
extractable ??= false
|
|
667
668
|
checkExtractable(extractable)
|
|
668
669
|
checkUint8Array(ikm, 'ikm')
|
|
@@ -695,7 +696,7 @@ export class CipherSuite {
|
|
|
695
696
|
*
|
|
696
697
|
* @returns A Promise that resolves to the serialized private key.
|
|
697
698
|
*/
|
|
698
|
-
async SerializePrivateKey(privateKey:
|
|
699
|
+
async SerializePrivateKey(privateKey: K): Promise<Uint8Array> {
|
|
699
700
|
isKey(privateKey, 'private', true)
|
|
700
701
|
|
|
701
702
|
return await this.#suite.KEM.SerializePrivateKey(privateKey)
|
|
@@ -717,7 +718,7 @@ export class CipherSuite {
|
|
|
717
718
|
*
|
|
718
719
|
* @returns A Promise that resolves to the serialized public key.
|
|
719
720
|
*/
|
|
720
|
-
async SerializePublicKey(publicKey:
|
|
721
|
+
async SerializePublicKey(publicKey: K): Promise<Uint8Array> {
|
|
721
722
|
isKey(publicKey, 'public', true)
|
|
722
723
|
|
|
723
724
|
return await this.#suite.KEM.SerializePublicKey(publicKey)
|
|
@@ -742,7 +743,7 @@ export class CipherSuite {
|
|
|
742
743
|
*
|
|
743
744
|
* @returns A Promise that resolves to the deserialized private key.
|
|
744
745
|
*/
|
|
745
|
-
async DeserializePrivateKey(privateKey: Uint8Array, extractable?: boolean): Promise<
|
|
746
|
+
async DeserializePrivateKey(privateKey: Uint8Array, extractable?: boolean): Promise<K> {
|
|
746
747
|
extractable ??= false
|
|
747
748
|
checkExtractable(extractable)
|
|
748
749
|
checkUint8Array(privateKey, 'privateKey')
|
|
@@ -777,7 +778,7 @@ export class CipherSuite {
|
|
|
777
778
|
*
|
|
778
779
|
* @returns A Promise that resolves to the deserialized public key.
|
|
779
780
|
*/
|
|
780
|
-
async DeserializePublicKey(publicKey: Uint8Array): Promise<
|
|
781
|
+
async DeserializePublicKey(publicKey: Uint8Array): Promise<K> {
|
|
781
782
|
checkUint8Array(publicKey, 'publicKey')
|
|
782
783
|
|
|
783
784
|
try {
|
|
@@ -825,10 +826,10 @@ export class CipherSuite {
|
|
|
825
826
|
* @returns A Promise that resolves to an object containing the encapsulated secret and
|
|
826
827
|
* ciphertext. The ciphertext is {@link CipherSuite.AEAD Nt} bytes longer than the plaintext. The
|
|
827
828
|
* encapsulated secret is {@link CipherSuite.KEM Nenc} bytes.
|
|
828
|
-
* @see [Single-Shot Encryption](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
829
|
+
* @see [Single-Shot Encryption](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-6.1)
|
|
829
830
|
*/
|
|
830
831
|
async Seal(
|
|
831
|
-
publicKey:
|
|
832
|
+
publicKey: K,
|
|
832
833
|
plaintext: Uint8Array,
|
|
833
834
|
options?: { aad?: Uint8Array; info?: Uint8Array; psk?: Uint8Array; pskId?: Uint8Array },
|
|
834
835
|
): Promise<{ encapsulatedSecret: Uint8Array; ciphertext: Uint8Array }> {
|
|
@@ -874,10 +875,10 @@ export class CipherSuite {
|
|
|
874
875
|
* @param options.pskId - Pre-shared key identifier (for PSK mode)
|
|
875
876
|
*
|
|
876
877
|
* @returns A Promise that resolves to the decrypted plaintext.
|
|
877
|
-
* @see [Single-Shot Decryption](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
878
|
+
* @see [Single-Shot Decryption](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-6.1)
|
|
878
879
|
*/
|
|
879
880
|
async Open(
|
|
880
|
-
privateKey:
|
|
881
|
+
privateKey: K | KeyPair<K>,
|
|
881
882
|
encapsulatedSecret: Uint8Array,
|
|
882
883
|
ciphertext: Uint8Array,
|
|
883
884
|
options?: { aad?: Uint8Array; info?: Uint8Array; psk?: Uint8Array; pskId?: Uint8Array },
|
|
@@ -922,10 +923,10 @@ export class CipherSuite {
|
|
|
922
923
|
*
|
|
923
924
|
* @returns A Promise that resolves to an object containing the encapsulated secret and the
|
|
924
925
|
* exported secret.
|
|
925
|
-
* @see [Single-Shot Secret Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
926
|
+
* @see [Single-Shot Secret Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-6.2)
|
|
926
927
|
*/
|
|
927
928
|
async SendExport(
|
|
928
|
-
publicKey:
|
|
929
|
+
publicKey: K,
|
|
929
930
|
exporterContext: Uint8Array,
|
|
930
931
|
length: number,
|
|
931
932
|
options?: { info?: Uint8Array; psk?: Uint8Array; pskId?: Uint8Array },
|
|
@@ -970,10 +971,10 @@ export class CipherSuite {
|
|
|
970
971
|
* @param options.pskId - Pre-shared key identifier (for PSK mode)
|
|
971
972
|
*
|
|
972
973
|
* @returns A Promise that resolves to the exported secret.
|
|
973
|
-
* @see [Single-Shot Secret Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
974
|
+
* @see [Single-Shot Secret Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-6.2)
|
|
974
975
|
*/
|
|
975
976
|
async ReceiveExport(
|
|
976
|
-
privateKey:
|
|
977
|
+
privateKey: K | KeyPair<K>,
|
|
977
978
|
encapsulatedSecret: Uint8Array,
|
|
978
979
|
exporterContext: Uint8Array,
|
|
979
980
|
length: number,
|
|
@@ -1024,10 +1025,10 @@ export class CipherSuite {
|
|
|
1024
1025
|
*
|
|
1025
1026
|
* @returns A Promise that resolves to an object containing the encapsulated secret and the sender
|
|
1026
1027
|
* context (`ctx`). The encapsulated secret is {@link CipherSuite.KEM Nenc} bytes.
|
|
1027
|
-
* @see [SetupBaseS / SetupPSKS](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
1028
|
+
* @see [SetupBaseS / SetupPSKS](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.1.1)
|
|
1028
1029
|
*/
|
|
1029
1030
|
async SetupSender(
|
|
1030
|
-
publicKey:
|
|
1031
|
+
publicKey: K,
|
|
1031
1032
|
options?: { info?: Uint8Array; psk?: Uint8Array; pskId?: Uint8Array },
|
|
1032
1033
|
): Promise<{ encapsulatedSecret: Uint8Array; ctx: SenderContext }> {
|
|
1033
1034
|
isKey(publicKey, 'public')
|
|
@@ -1105,10 +1106,10 @@ export class CipherSuite {
|
|
|
1105
1106
|
* @param options.pskId - Pre-shared key identifier (for PSK mode)
|
|
1106
1107
|
*
|
|
1107
1108
|
* @returns A Promise that resolves to the recipient context.
|
|
1108
|
-
* @see [SetupBaseR / SetupPSKR](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
1109
|
+
* @see [SetupBaseR / SetupPSKR](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.1.1)
|
|
1109
1110
|
*/
|
|
1110
1111
|
async SetupRecipient(
|
|
1111
|
-
privateKey:
|
|
1112
|
+
privateKey: K | KeyPair<K>,
|
|
1112
1113
|
encapsulatedSecret: Uint8Array,
|
|
1113
1114
|
options?: { info?: Uint8Array; psk?: Uint8Array; pskId?: Uint8Array },
|
|
1114
1115
|
): Promise<RecipientContext> {
|
|
@@ -1141,7 +1142,7 @@ export class CipherSuite {
|
|
|
1141
1142
|
return new RecipientContext(this.#suite, mode, key, base_nonce, exporter_secret)
|
|
1142
1143
|
}
|
|
1143
1144
|
|
|
1144
|
-
#extractRecipientKeys(skR:
|
|
1145
|
+
#extractRecipientKeys(skR: K | KeyPair<K>): { skR: K; pkR: K | undefined } {
|
|
1145
1146
|
if (isKeyPair(skR)) {
|
|
1146
1147
|
return { skR: skR.privateKey, pkR: skR.publicKey }
|
|
1147
1148
|
}
|
|
@@ -1279,9 +1280,9 @@ export class NotSupportedError extends Error {
|
|
|
1279
1280
|
// Type Definitions and Interfaces
|
|
1280
1281
|
// ============================================================================
|
|
1281
1282
|
|
|
1282
|
-
interface Triple {
|
|
1283
|
+
interface Triple<K extends Key = Key> {
|
|
1283
1284
|
readonly id: Uint8Array
|
|
1284
|
-
readonly KEM: Readonly<KEM
|
|
1285
|
+
readonly KEM: Readonly<KEM<K>>
|
|
1285
1286
|
readonly KDF: Readonly<KDF>
|
|
1286
1287
|
readonly AEAD: Readonly<AEAD>
|
|
1287
1288
|
}
|
|
@@ -1292,7 +1293,7 @@ interface Triple {
|
|
|
1292
1293
|
* Base mode provides encryption to a public key without sender authentication. The recipient cannot
|
|
1293
1294
|
* verify who encrypted the message, only that someone with access to their public key did.
|
|
1294
1295
|
*
|
|
1295
|
-
* @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
1296
|
+
* @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5)
|
|
1296
1297
|
*/
|
|
1297
1298
|
export const MODE_BASE = 0x00
|
|
1298
1299
|
|
|
@@ -1303,10 +1304,13 @@ export const MODE_BASE = 0x00
|
|
|
1303
1304
|
* sender and recipient must possess the same PSK and PSK ID. This provides implicit sender
|
|
1304
1305
|
* authentication.
|
|
1305
1306
|
*
|
|
1306
|
-
* @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
1307
|
+
* @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5)
|
|
1307
1308
|
*/
|
|
1308
1309
|
export const MODE_PSK = 0x01
|
|
1309
1310
|
|
|
1311
|
+
/** Mode supported by this implementation. */
|
|
1312
|
+
export type Mode = typeof MODE_BASE | typeof MODE_PSK
|
|
1313
|
+
|
|
1310
1314
|
/**
|
|
1311
1315
|
* Factory function that returns a KEM implementation.
|
|
1312
1316
|
*
|
|
@@ -1338,8 +1342,10 @@ export const MODE_PSK = 0x01
|
|
|
1338
1342
|
* > returning an object conforming to the {@link KEM} interface can be used. Such implementations not
|
|
1339
1343
|
* > reliant on Web Cryptography are exported by
|
|
1340
1344
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
1345
|
+
*
|
|
1346
|
+
* @typeParam K - Key representation produced and consumed by the KEM
|
|
1341
1347
|
*/
|
|
1342
|
-
export type KEMFactory = () => Readonly<KEM
|
|
1348
|
+
export type KEMFactory<K extends Key = Key> = () => Readonly<KEM<K>>
|
|
1343
1349
|
|
|
1344
1350
|
/**
|
|
1345
1351
|
* Factory function that returns a KDF implementation.
|
|
@@ -1396,12 +1402,14 @@ export type AEADFactory = () => Readonly<AEAD>
|
|
|
1396
1402
|
* - Private Key: Used by recipients for decryption operations (passed to
|
|
1397
1403
|
* {@link CipherSuite.SetupRecipient} or {@link CipherSuite.Open}). These are not distributed and
|
|
1398
1404
|
* kept private.
|
|
1405
|
+
*
|
|
1406
|
+
* @typeParam K - Key representation contained in the pair
|
|
1399
1407
|
*/
|
|
1400
|
-
export interface KeyPair {
|
|
1408
|
+
export interface KeyPair<K extends Key = Key> {
|
|
1401
1409
|
/** The public key, used for encryption operations. */
|
|
1402
|
-
readonly publicKey: Readonly<
|
|
1410
|
+
readonly publicKey: Readonly<K>
|
|
1403
1411
|
/** The private key, used for decryption operations. */
|
|
1404
|
-
readonly privateKey: Readonly<
|
|
1412
|
+
readonly privateKey: Readonly<K>
|
|
1405
1413
|
}
|
|
1406
1414
|
|
|
1407
1415
|
/**
|
|
@@ -1428,6 +1436,34 @@ export interface Key {
|
|
|
1428
1436
|
readonly type: 'private' | 'public' | (string & {})
|
|
1429
1437
|
}
|
|
1430
1438
|
|
|
1439
|
+
/**
|
|
1440
|
+
* A Web Cryptography key as declared by the host runtime.
|
|
1441
|
+
*
|
|
1442
|
+
* This aliases the key type returned by the host's `SubtleCrypto.generateKey()` API when it is
|
|
1443
|
+
* exposed on `globalThis`. A structural fallback is used otherwise, keeping the package portable to
|
|
1444
|
+
* runtimes and TypeScript projects that do not include DOM or Node.js ambient types.
|
|
1445
|
+
*/
|
|
1446
|
+
export type CryptoKey = typeof globalThis extends {
|
|
1447
|
+
crypto: { subtle: { generateKey(...args: any[]): Promise<infer R> } }
|
|
1448
|
+
}
|
|
1449
|
+
? Extract<R, { type: string }>
|
|
1450
|
+
: CryptoKeyStructuralFallback
|
|
1451
|
+
|
|
1452
|
+
/**
|
|
1453
|
+
* Used as {@link CryptoKey} when the host runtime's `crypto` global is not exposed on `typeof
|
|
1454
|
+
* globalThis`, including when it is absent from ambient types or declared with `const` or `let`. It
|
|
1455
|
+
* remains structurally compatible with host {@link !CryptoKey} declarations so values flow freely to
|
|
1456
|
+
* and from {@link !SubtleCrypto} APIs.
|
|
1457
|
+
*
|
|
1458
|
+
* @internal
|
|
1459
|
+
*/
|
|
1460
|
+
interface CryptoKeyStructuralFallback {
|
|
1461
|
+
readonly algorithm: { name: string }
|
|
1462
|
+
readonly extractable: boolean
|
|
1463
|
+
readonly type: string
|
|
1464
|
+
readonly usages: string[]
|
|
1465
|
+
}
|
|
1466
|
+
|
|
1431
1467
|
// ============================================================================
|
|
1432
1468
|
// Utility Functions
|
|
1433
1469
|
// ============================================================================
|
|
@@ -1525,7 +1561,7 @@ function lengthPrefixed(x: Uint8Array): Uint8Array {
|
|
|
1525
1561
|
* ensures domain separation between different uses of the KDF in HPKE.
|
|
1526
1562
|
*
|
|
1527
1563
|
* @group Utilities
|
|
1528
|
-
* @see [LabeledDerive](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
1564
|
+
* @see [LabeledDerive](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
|
|
1529
1565
|
*/
|
|
1530
1566
|
export async function LabeledDerive(
|
|
1531
1567
|
KDF: Pick<KDF, 'Derive'>,
|
|
@@ -1539,7 +1575,7 @@ export async function LabeledDerive(
|
|
|
1539
1575
|
return await KDF.Derive(labeled_ikm, L)
|
|
1540
1576
|
}
|
|
1541
1577
|
|
|
1542
|
-
/** @see [Export_OneStage](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
1578
|
+
/** @see [Export_OneStage](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5) */
|
|
1543
1579
|
async function Export_OneStage(
|
|
1544
1580
|
KDF: KDF,
|
|
1545
1581
|
suite_id: Uint8Array,
|
|
@@ -1551,7 +1587,7 @@ async function Export_OneStage(
|
|
|
1551
1587
|
return await LabeledDerive(KDF, suite_id, exporter_secret, L_sec, exporter_context, L)
|
|
1552
1588
|
}
|
|
1553
1589
|
|
|
1554
|
-
/** @see [CombineSecrets_OneStage](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
1590
|
+
/** @see [CombineSecrets_OneStage](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5) */
|
|
1555
1591
|
async function CombineSecrets_OneStage(
|
|
1556
1592
|
suite: Triple,
|
|
1557
1593
|
mode: number,
|
|
@@ -1608,7 +1644,7 @@ function checkExtractable(extractable: unknown): asserts extractable is boolean
|
|
|
1608
1644
|
}
|
|
1609
1645
|
}
|
|
1610
1646
|
|
|
1611
|
-
/** @see [KeySchedule (CombineSecrets)](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
1647
|
+
/** @see [KeySchedule (CombineSecrets)](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.1) */
|
|
1612
1648
|
async function CombineSecrets_TwoStage(
|
|
1613
1649
|
suite: Triple,
|
|
1614
1650
|
mode: number,
|
|
@@ -1651,7 +1687,7 @@ async function CombineSecrets_TwoStage(
|
|
|
1651
1687
|
return { key, base_nonce, exporter_secret }
|
|
1652
1688
|
}
|
|
1653
1689
|
|
|
1654
|
-
/** @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
1690
|
+
/** @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.3) */
|
|
1655
1691
|
async function Export_TwoStage(
|
|
1656
1692
|
KDF: KDF,
|
|
1657
1693
|
suite_id: Uint8Array,
|
|
@@ -1728,7 +1764,7 @@ async function Export_TwoStage(
|
|
|
1728
1764
|
* )
|
|
1729
1765
|
* ```
|
|
1730
1766
|
*
|
|
1731
|
-
* @see [HPKE Key Derivation Functions](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
1767
|
+
* @see [HPKE Key Derivation Functions](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.2)
|
|
1732
1768
|
*/
|
|
1733
1769
|
export interface KDF {
|
|
1734
1770
|
/** KDF algorithm identifier */
|
|
@@ -1801,7 +1837,7 @@ export interface KDF {
|
|
|
1801
1837
|
* pseudorandom key. This ensures domain separation between different uses of the KDF in HPKE.
|
|
1802
1838
|
*
|
|
1803
1839
|
* @group Utilities
|
|
1804
|
-
* @see [LabeledExtract](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
1840
|
+
* @see [LabeledExtract](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.4)
|
|
1805
1841
|
*/
|
|
1806
1842
|
export async function LabeledExtract(
|
|
1807
1843
|
KDF: Pick<KDF, 'Extract'>,
|
|
@@ -1831,7 +1867,7 @@ export async function LabeledExtract(
|
|
|
1831
1867
|
* of the KDF in HPKE.
|
|
1832
1868
|
*
|
|
1833
1869
|
* @group Utilities
|
|
1834
|
-
* @see [LabeledExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
1870
|
+
* @see [LabeledExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.4)
|
|
1835
1871
|
*/
|
|
1836
1872
|
export async function LabeledExpand(
|
|
1837
1873
|
KDF: Pick<KDF, 'Expand'>,
|
|
@@ -1940,9 +1976,10 @@ export async function LabeledExpand(
|
|
|
1940
1976
|
* )
|
|
1941
1977
|
* ```
|
|
1942
1978
|
*
|
|
1943
|
-
* @
|
|
1979
|
+
* @typeParam K - Key representation produced and consumed by the KEM
|
|
1980
|
+
* @see [HPKE Key Encapsulation Mechanisms](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.1)
|
|
1944
1981
|
*/
|
|
1945
|
-
export interface KEM {
|
|
1982
|
+
export interface KEM<K extends Key = Key> {
|
|
1946
1983
|
/** KEM algorithm identifier */
|
|
1947
1984
|
readonly id: number
|
|
1948
1985
|
|
|
@@ -1972,7 +2009,7 @@ export interface KEM {
|
|
|
1972
2009
|
*
|
|
1973
2010
|
* @returns A promise resolving to a {@link KeyPair}
|
|
1974
2011
|
*/
|
|
1975
|
-
DeriveKeyPair(ikm: Uint8Array, extractable: boolean): Promise<KeyPair
|
|
2012
|
+
DeriveKeyPair(ikm: Uint8Array, extractable: boolean): Promise<KeyPair<K>>
|
|
1976
2013
|
|
|
1977
2014
|
/**
|
|
1978
2015
|
* Generates a random key pair.
|
|
@@ -1981,7 +2018,7 @@ export interface KEM {
|
|
|
1981
2018
|
*
|
|
1982
2019
|
* @returns A promise resolving to a {@link KeyPair}
|
|
1983
2020
|
*/
|
|
1984
|
-
GenerateKeyPair(extractable: boolean): Promise<KeyPair
|
|
2021
|
+
GenerateKeyPair(extractable: boolean): Promise<KeyPair<K>>
|
|
1985
2022
|
|
|
1986
2023
|
/**
|
|
1987
2024
|
* Serializes a public key to bytes.
|
|
@@ -1990,7 +2027,7 @@ export interface KEM {
|
|
|
1990
2027
|
*
|
|
1991
2028
|
* @returns A promise resolving to the serialized public key
|
|
1992
2029
|
*/
|
|
1993
|
-
SerializePublicKey(key:
|
|
2030
|
+
SerializePublicKey(key: K): Promise<Uint8Array>
|
|
1994
2031
|
|
|
1995
2032
|
/**
|
|
1996
2033
|
* Deserializes a public key from bytes.
|
|
@@ -1999,7 +2036,7 @@ export interface KEM {
|
|
|
1999
2036
|
*
|
|
2000
2037
|
* @returns A promise resolving to a {@link !Key} or a Key interface-conforming object
|
|
2001
2038
|
*/
|
|
2002
|
-
DeserializePublicKey(key: Uint8Array): Promise<
|
|
2039
|
+
DeserializePublicKey(key: Uint8Array): Promise<K>
|
|
2003
2040
|
|
|
2004
2041
|
/**
|
|
2005
2042
|
* Serializes a private key to bytes.
|
|
@@ -2008,7 +2045,7 @@ export interface KEM {
|
|
|
2008
2045
|
*
|
|
2009
2046
|
* @returns A promise resolving to the serialized private key
|
|
2010
2047
|
*/
|
|
2011
|
-
SerializePrivateKey(key:
|
|
2048
|
+
SerializePrivateKey(key: K): Promise<Uint8Array>
|
|
2012
2049
|
|
|
2013
2050
|
/**
|
|
2014
2051
|
* Deserializes a private key from bytes.
|
|
@@ -2018,7 +2055,7 @@ export interface KEM {
|
|
|
2018
2055
|
*
|
|
2019
2056
|
* @returns A promise resolving to a {@link !Key} or a Key interface-conforming object
|
|
2020
2057
|
*/
|
|
2021
|
-
DeserializePrivateKey(key: Uint8Array, extractable: boolean): Promise<
|
|
2058
|
+
DeserializePrivateKey(key: Uint8Array, extractable: boolean): Promise<K>
|
|
2022
2059
|
|
|
2023
2060
|
/**
|
|
2024
2061
|
* Encapsulates a shared secret to a recipient's public key.
|
|
@@ -2031,7 +2068,7 @@ export interface KEM {
|
|
|
2031
2068
|
*
|
|
2032
2069
|
* @returns A promise resolving to an object containing the shared secret and encapsulated secret
|
|
2033
2070
|
*/
|
|
2034
|
-
Encap(pkR:
|
|
2071
|
+
Encap(pkR: K): Promise<{ shared_secret: Uint8Array; enc: Uint8Array }>
|
|
2035
2072
|
|
|
2036
2073
|
/**
|
|
2037
2074
|
* Decapsulates a shared secret using a recipient's private key.
|
|
@@ -2046,10 +2083,10 @@ export interface KEM {
|
|
|
2046
2083
|
*
|
|
2047
2084
|
* @returns A promise resolving to the shared secret
|
|
2048
2085
|
*/
|
|
2049
|
-
Decap(enc: Uint8Array, skR:
|
|
2086
|
+
Decap(enc: Uint8Array, skR: K, pkR: K | undefined): Promise<Uint8Array>
|
|
2050
2087
|
}
|
|
2051
2088
|
|
|
2052
|
-
function isKeyPair(skR:
|
|
2089
|
+
function isKeyPair<K extends Key>(skR: K | KeyPair<K>): skR is KeyPair<K> {
|
|
2053
2090
|
if (!skR || typeof skR !== 'object') return false
|
|
2054
2091
|
if ('publicKey' in skR && 'privateKey' in skR) {
|
|
2055
2092
|
const pkR = skR.publicKey
|
|
@@ -2142,7 +2179,7 @@ function isKey(key: unknown, type: string, extractable?: boolean): asserts key i
|
|
|
2142
2179
|
* )
|
|
2143
2180
|
* ```
|
|
2144
2181
|
*
|
|
2145
|
-
* @see [HPKE AEAD Encryption Algorithm](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
2182
|
+
* @see [HPKE AEAD Encryption Algorithm](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.3)
|
|
2146
2183
|
*/
|
|
2147
2184
|
export interface AEAD {
|
|
2148
2185
|
/** AEAD algorithm identifier */
|
|
@@ -2177,7 +2214,7 @@ export interface AEAD {
|
|
|
2177
2214
|
* @param pt - Plaintext to encrypt
|
|
2178
2215
|
*
|
|
2179
2216
|
* @returns A promise resolving to the ciphertext with authentication tag appended
|
|
2180
|
-
* @see [Context.Seal P_MAX handling](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
2217
|
+
* @see [Context.Seal P_MAX handling](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.2)
|
|
2181
2218
|
*/
|
|
2182
2219
|
Seal(key: Uint8Array, nonce: Uint8Array, aad: Uint8Array, pt: Uint8Array): Promise<Uint8Array>
|
|
2183
2220
|
|
|
@@ -2238,7 +2275,7 @@ function KDFStages(KDF: KDF): 1 | 2 {
|
|
|
2238
2275
|
throw new Error('unreachable')
|
|
2239
2276
|
}
|
|
2240
2277
|
|
|
2241
|
-
/** @see [KeySchedule](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
2278
|
+
/** @see [KeySchedule](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.1) */
|
|
2242
2279
|
async function KeySchedule(
|
|
2243
2280
|
suite: Triple,
|
|
2244
2281
|
mode: number,
|
|
@@ -2261,7 +2298,7 @@ async function KeySchedule(
|
|
|
2261
2298
|
return await CombineSecrets(suite, mode, shared_secret, info, psk, pskId)
|
|
2262
2299
|
}
|
|
2263
2300
|
|
|
2264
|
-
/** @see [VerifyPSKInputs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
2301
|
+
/** @see [VerifyPSKInputs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.1) */
|
|
2265
2302
|
function VerifyPSKInputs(psk: Uint8Array, psk_id: Uint8Array) {
|
|
2266
2303
|
if (psk.byteLength && psk_id.byteLength) {
|
|
2267
2304
|
if (psk.byteLength < 32) {
|
|
@@ -2293,7 +2330,7 @@ const CHACHA20_POLY1305_P_MAX = 2 ** 38 - 64
|
|
|
2293
2330
|
* This is a factory function that must be passed to the {@link CipherSuite} constructor.
|
|
2294
2331
|
*
|
|
2295
2332
|
* @group AEAD Algorithms
|
|
2296
|
-
* @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
2333
|
+
* @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.3)
|
|
2297
2334
|
*/
|
|
2298
2335
|
export const AEAD_EXPORT_ONLY: AEADFactory = function (): AEAD {
|
|
2299
2336
|
return {
|
|
@@ -2419,7 +2456,7 @@ function HKDF_SHARED(): KDF_BASE {
|
|
|
2419
2456
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
2420
2457
|
*
|
|
2421
2458
|
* @group KDF Algorithms
|
|
2422
|
-
* @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
2459
|
+
* @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.2)
|
|
2423
2460
|
*/
|
|
2424
2461
|
export const KDF_HKDF_SHA256: KDFFactory = function (): HKDF {
|
|
2425
2462
|
return { id: 0x0001, type: 'KDF', name: 'HKDF-SHA256', Nh: 32, hash: 'SHA-256', ...HKDF_SHARED() }
|
|
@@ -2442,7 +2479,7 @@ export const KDF_HKDF_SHA256: KDFFactory = function (): HKDF {
|
|
|
2442
2479
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
2443
2480
|
*
|
|
2444
2481
|
* @group KDF Algorithms
|
|
2445
|
-
* @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
2482
|
+
* @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.2)
|
|
2446
2483
|
*/
|
|
2447
2484
|
export const KDF_HKDF_SHA384: KDFFactory = function (): HKDF {
|
|
2448
2485
|
return { id: 0x0002, type: 'KDF', name: 'HKDF-SHA384', Nh: 48, hash: 'SHA-384', ...HKDF_SHARED() }
|
|
@@ -2465,7 +2502,7 @@ export const KDF_HKDF_SHA384: KDFFactory = function (): HKDF {
|
|
|
2465
2502
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
2466
2503
|
*
|
|
2467
2504
|
* @group KDF Algorithms
|
|
2468
|
-
* @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
2505
|
+
* @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.2)
|
|
2469
2506
|
*/
|
|
2470
2507
|
export const KDF_HKDF_SHA512: KDFFactory = function (): HKDF {
|
|
2471
2508
|
return { id: 0x0003, type: 'KDF', name: 'HKDF-SHA512', Nh: 64, hash: 'SHA-512', ...HKDF_SHARED() }
|
|
@@ -2513,7 +2550,7 @@ function SHAKE_SHARED(): KDF_BASE {
|
|
|
2513
2550
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
2514
2551
|
*
|
|
2515
2552
|
* @group KDF Algorithms
|
|
2516
|
-
* @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
2553
|
+
* @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
|
|
2517
2554
|
*/
|
|
2518
2555
|
export const KDF_SHAKE128: KDFFactory = function (): SHAKE {
|
|
2519
2556
|
return {
|
|
@@ -2543,7 +2580,7 @@ export const KDF_SHAKE128: KDFFactory = function (): SHAKE {
|
|
|
2543
2580
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
2544
2581
|
*
|
|
2545
2582
|
* @group KDF Algorithms
|
|
2546
|
-
* @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
2583
|
+
* @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
|
|
2547
2584
|
*/
|
|
2548
2585
|
export const KDF_SHAKE256: KDFFactory = function (): SHAKE {
|
|
2549
2586
|
return {
|
|
@@ -2573,7 +2610,7 @@ export const KDF_SHAKE256: KDFFactory = function (): SHAKE {
|
|
|
2573
2610
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
2574
2611
|
*
|
|
2575
2612
|
* @group KDF Algorithms
|
|
2576
|
-
* @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
2613
|
+
* @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
|
|
2577
2614
|
*/
|
|
2578
2615
|
export const KDF_TurboSHAKE128: KDFFactory = function (): SHAKE {
|
|
2579
2616
|
return {
|
|
@@ -2603,7 +2640,7 @@ export const KDF_TurboSHAKE128: KDFFactory = function (): SHAKE {
|
|
|
2603
2640
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
2604
2641
|
*
|
|
2605
2642
|
* @group KDF Algorithms
|
|
2606
|
-
* @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
2643
|
+
* @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
|
|
2607
2644
|
*/
|
|
2608
2645
|
export const KDF_TurboSHAKE256: KDFFactory = function (): SHAKE {
|
|
2609
2646
|
return {
|
|
@@ -2658,8 +2695,8 @@ function checkNotAllZeros(buffer: Uint8Array): void {
|
|
|
2658
2695
|
}
|
|
2659
2696
|
}
|
|
2660
2697
|
|
|
2661
|
-
type KEM_BASE = Pick<
|
|
2662
|
-
KEM
|
|
2698
|
+
type KEM_BASE<K extends Key = Key> = Pick<
|
|
2699
|
+
KEM<K>,
|
|
2663
2700
|
| 'GenerateKeyPair'
|
|
2664
2701
|
| 'DeriveKeyPair'
|
|
2665
2702
|
| 'SerializePublicKey'
|
|
@@ -2670,7 +2707,7 @@ type KEM_BASE = Pick<
|
|
|
2670
2707
|
| 'Decap'
|
|
2671
2708
|
>
|
|
2672
2709
|
|
|
2673
|
-
interface DHKEM extends KEM {
|
|
2710
|
+
interface DHKEM extends KEM<CryptoKey> {
|
|
2674
2711
|
readonly suite_id: Uint8Array
|
|
2675
2712
|
readonly Ndh: number
|
|
2676
2713
|
readonly kdf: KDF
|
|
@@ -2709,7 +2746,7 @@ function b64u(input: string): Uint8Array {
|
|
|
2709
2746
|
// KEM (Key Encapsulation Mechanism) - DHKEM Helper Functions
|
|
2710
2747
|
// ============================================================================
|
|
2711
2748
|
|
|
2712
|
-
/** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
2749
|
+
/** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1.3) */
|
|
2713
2750
|
async function DeriveKeyPairBytes(
|
|
2714
2751
|
DHKEM: DHKEM,
|
|
2715
2752
|
ikm: Uint8Array,
|
|
@@ -2766,7 +2803,7 @@ function assertCryptoKey(key: Key): asserts key is CryptoKey {
|
|
|
2766
2803
|
}
|
|
2767
2804
|
}
|
|
2768
2805
|
|
|
2769
|
-
/** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
2806
|
+
/** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.5) */
|
|
2770
2807
|
async function ExtractAndExpand_OneStage(
|
|
2771
2808
|
DHKEM: DHKEM,
|
|
2772
2809
|
dh: Uint8Array,
|
|
@@ -2782,7 +2819,7 @@ async function ExtractAndExpand_OneStage(
|
|
|
2782
2819
|
)
|
|
2783
2820
|
}
|
|
2784
2821
|
|
|
2785
|
-
/** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
2822
|
+
/** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.5) */
|
|
2786
2823
|
async function ExtractAndExpand_TwoStage(
|
|
2787
2824
|
DHKEM: DHKEM,
|
|
2788
2825
|
dh: Uint8Array,
|
|
@@ -2799,7 +2836,7 @@ async function ExtractAndExpand_TwoStage(
|
|
|
2799
2836
|
)
|
|
2800
2837
|
}
|
|
2801
2838
|
|
|
2802
|
-
/** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
2839
|
+
/** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.5) */
|
|
2803
2840
|
async function ExtractAndExpand(
|
|
2804
2841
|
DHKEM: DHKEM,
|
|
2805
2842
|
dh: Uint8Array,
|
|
@@ -2813,7 +2850,9 @@ async function ExtractAndExpand(
|
|
|
2813
2850
|
// KEM (Key Encapsulation Mechanism) - DHKEM Shared Implementation
|
|
2814
2851
|
// ============================================================================
|
|
2815
2852
|
|
|
2816
|
-
function DHKEM_SHARED(): Required<
|
|
2853
|
+
function DHKEM_SHARED(): Required<
|
|
2854
|
+
Omit<KEM_BASE<CryptoKey>, 'DeriveKeyPair' | 'DeserializePrivateKey'>
|
|
2855
|
+
> {
|
|
2817
2856
|
return {
|
|
2818
2857
|
async GenerateKeyPair(this: DHKEM, extractable) {
|
|
2819
2858
|
return (await subtle(
|
|
@@ -3097,7 +3136,7 @@ async function DeserializePrivateKeyNist(
|
|
|
3097
3136
|
return privateKey
|
|
3098
3137
|
}
|
|
3099
3138
|
|
|
3100
|
-
/** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
3139
|
+
/** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1.3) */
|
|
3101
3140
|
async function DeriveKeyPairNist(
|
|
3102
3141
|
this: DHKEM & NistCurveConfig,
|
|
3103
3142
|
ikm: Uint8Array,
|
|
@@ -3145,7 +3184,7 @@ async function GetKeyPairNist(
|
|
|
3145
3184
|
// KEM (Key Encapsulation Mechanism) - DHKEM X Curve Implementations
|
|
3146
3185
|
// ============================================================================
|
|
3147
3186
|
|
|
3148
|
-
/** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
3187
|
+
/** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1.3) */
|
|
3149
3188
|
async function DeriveKeyPairX(this: DHKEM, ikm: Uint8Array, extractable: boolean) {
|
|
3150
3189
|
const sk = await DeriveKeyPairBytes(this, ikm, L_sk, new Uint8Array())
|
|
3151
3190
|
return await createKeyPairFromPrivateKey(this, sk, extractable)
|
|
@@ -3184,9 +3223,10 @@ const P256: NistCurveConfig = {
|
|
|
3184
3223
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
3185
3224
|
*
|
|
3186
3225
|
* @group KEM Algorithms
|
|
3187
|
-
* @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
3226
|
+
* @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
|
|
3188
3227
|
*/
|
|
3189
|
-
export const KEM_DHKEM_P256_HKDF_SHA256: KEMFactory = function (): DHKEM &
|
|
3228
|
+
export const KEM_DHKEM_P256_HKDF_SHA256: KEMFactory<CryptoKey> = function (): DHKEM &
|
|
3229
|
+
NistCurveConfig {
|
|
3190
3230
|
const id = 0x0010
|
|
3191
3231
|
const name = 'DHKEM(P-256, HKDF-SHA256)'
|
|
3192
3232
|
const kdf = KDF_HKDF_SHA256()
|
|
@@ -3239,9 +3279,10 @@ const P384: NistCurveConfig = {
|
|
|
3239
3279
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
3240
3280
|
*
|
|
3241
3281
|
* @group KEM Algorithms
|
|
3242
|
-
* @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
3282
|
+
* @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
|
|
3243
3283
|
*/
|
|
3244
|
-
export const KEM_DHKEM_P384_HKDF_SHA384: KEMFactory = function (): DHKEM &
|
|
3284
|
+
export const KEM_DHKEM_P384_HKDF_SHA384: KEMFactory<CryptoKey> = function (): DHKEM &
|
|
3285
|
+
NistCurveConfig {
|
|
3245
3286
|
const id = 0x0011
|
|
3246
3287
|
const name = 'DHKEM(P-384, HKDF-SHA384)'
|
|
3247
3288
|
const kdf = KDF_HKDF_SHA384()
|
|
@@ -3294,9 +3335,10 @@ const P521: NistCurveConfig = {
|
|
|
3294
3335
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
3295
3336
|
*
|
|
3296
3337
|
* @group KEM Algorithms
|
|
3297
|
-
* @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
3338
|
+
* @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
|
|
3298
3339
|
*/
|
|
3299
|
-
export const KEM_DHKEM_P521_HKDF_SHA512: KEMFactory = function (): DHKEM &
|
|
3340
|
+
export const KEM_DHKEM_P521_HKDF_SHA512: KEMFactory<CryptoKey> = function (): DHKEM &
|
|
3341
|
+
NistCurveConfig {
|
|
3300
3342
|
const id = 0x0012
|
|
3301
3343
|
const name = 'DHKEM(P-521, HKDF-SHA512)'
|
|
3302
3344
|
const kdf = KDF_HKDF_SHA512()
|
|
@@ -3340,9 +3382,11 @@ export const KEM_DHKEM_P521_HKDF_SHA512: KEMFactory = function (): DHKEM & NistC
|
|
|
3340
3382
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
3341
3383
|
*
|
|
3342
3384
|
* @group KEM Algorithms
|
|
3343
|
-
* @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
3385
|
+
* @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
|
|
3344
3386
|
*/
|
|
3345
|
-
export const KEM_DHKEM_X25519_HKDF_SHA256: KEMFactory = function (): DHKEM & {
|
|
3387
|
+
export const KEM_DHKEM_X25519_HKDF_SHA256: KEMFactory<CryptoKey> = function (): DHKEM & {
|
|
3388
|
+
pkcs8: Uint8Array
|
|
3389
|
+
} {
|
|
3346
3390
|
const id = 0x0020
|
|
3347
3391
|
const name = 'DHKEM(X25519, HKDF-SHA256)'
|
|
3348
3392
|
const kdf = KDF_HKDF_SHA256()
|
|
@@ -3387,9 +3431,11 @@ export const KEM_DHKEM_X25519_HKDF_SHA256: KEMFactory = function (): DHKEM & { p
|
|
|
3387
3431
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
3388
3432
|
*
|
|
3389
3433
|
* @group KEM Algorithms
|
|
3390
|
-
* @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
3434
|
+
* @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
|
|
3391
3435
|
*/
|
|
3392
|
-
export const KEM_DHKEM_X448_HKDF_SHA512: KEMFactory = function (): DHKEM & {
|
|
3436
|
+
export const KEM_DHKEM_X448_HKDF_SHA512: KEMFactory<CryptoKey> = function (): DHKEM & {
|
|
3437
|
+
pkcs8: Uint8Array
|
|
3438
|
+
} {
|
|
3393
3439
|
const id = 0x0021
|
|
3394
3440
|
const name = 'DHKEM(X448, HKDF-SHA512)'
|
|
3395
3441
|
const kdf = KDF_HKDF_SHA512()
|
|
@@ -3417,18 +3463,20 @@ export const KEM_DHKEM_X448_HKDF_SHA512: KEMFactory = function (): DHKEM & { pkc
|
|
|
3417
3463
|
}
|
|
3418
3464
|
|
|
3419
3465
|
// ============================================================================
|
|
3420
|
-
// KEM (Key Encapsulation Mechanism) -
|
|
3466
|
+
// KEM (Key Encapsulation Mechanism) - Direct KEM Types and Implementation
|
|
3421
3467
|
// ============================================================================
|
|
3422
3468
|
|
|
3423
|
-
|
|
3469
|
+
type KEMParams = Pick<KEM, 'id' | 'name' | 'Nsecret' | 'Nenc' | 'Npk' | 'Nsk'>
|
|
3470
|
+
|
|
3471
|
+
interface DirectKEM extends KEM<CryptoKey> {
|
|
3424
3472
|
readonly suite_id: Uint8Array
|
|
3425
3473
|
readonly algorithm: Readonly<KeyAlgorithm>
|
|
3426
3474
|
readonly kdf: KDF
|
|
3427
3475
|
}
|
|
3428
3476
|
|
|
3429
|
-
function
|
|
3477
|
+
function DIRECT_KEM_SHARED(): KEM_BASE<CryptoKey> {
|
|
3430
3478
|
return {
|
|
3431
|
-
async DeriveKeyPair(this:
|
|
3479
|
+
async DeriveKeyPair(this: DirectKEM, ikm, extractable) {
|
|
3432
3480
|
const dk = await LabeledDerive(
|
|
3433
3481
|
this.kdf,
|
|
3434
3482
|
this.suite_id,
|
|
@@ -3445,7 +3493,7 @@ function MLKEM_SHARED(): KEM_BASE {
|
|
|
3445
3493
|
|
|
3446
3494
|
return { privateKey, publicKey }
|
|
3447
3495
|
},
|
|
3448
|
-
async GenerateKeyPair(this:
|
|
3496
|
+
async GenerateKeyPair(this: DirectKEM, extractable) {
|
|
3449
3497
|
// @ts-expect-error
|
|
3450
3498
|
const usages: KeyUsage[] = ['encapsulateBits', 'decapsulateBits']
|
|
3451
3499
|
return (await subtle(
|
|
@@ -3453,14 +3501,14 @@ function MLKEM_SHARED(): KEM_BASE {
|
|
|
3453
3501
|
this.name,
|
|
3454
3502
|
)) as CryptoKeyPair
|
|
3455
3503
|
},
|
|
3456
|
-
async SerializePublicKey(this:
|
|
3504
|
+
async SerializePublicKey(this: DirectKEM, key) {
|
|
3457
3505
|
assertKeyAlgorithm(key, this.algorithm)
|
|
3458
3506
|
assertCryptoKey(key)
|
|
3459
3507
|
// @ts-expect-error
|
|
3460
3508
|
const format: Exclude<KeyFormat, 'jwk'> = 'raw-public'
|
|
3461
3509
|
return new Uint8Array(await subtle((c) => c.exportKey(format, key), this.name))
|
|
3462
3510
|
},
|
|
3463
|
-
async DeserializePublicKey(this:
|
|
3511
|
+
async DeserializePublicKey(this: DirectKEM, key) {
|
|
3464
3512
|
// @ts-expect-error
|
|
3465
3513
|
const format: Exclude<KeyFormat, 'jwk'> = 'raw-public'
|
|
3466
3514
|
// @ts-expect-error
|
|
@@ -3470,14 +3518,14 @@ function MLKEM_SHARED(): KEM_BASE {
|
|
|
3470
3518
|
this.name,
|
|
3471
3519
|
)
|
|
3472
3520
|
},
|
|
3473
|
-
async SerializePrivateKey(this:
|
|
3521
|
+
async SerializePrivateKey(this: DirectKEM, key) {
|
|
3474
3522
|
assertKeyAlgorithm(key, this.algorithm)
|
|
3475
3523
|
assertCryptoKey(key)
|
|
3476
3524
|
// @ts-expect-error
|
|
3477
3525
|
const format: Exclude<KeyFormat, 'jwk'> = 'raw-seed'
|
|
3478
3526
|
return new Uint8Array(await subtle((c) => c.exportKey(format, key), this.name))
|
|
3479
3527
|
},
|
|
3480
|
-
async DeserializePrivateKey(this:
|
|
3528
|
+
async DeserializePrivateKey(this: DirectKEM, key, extractable) {
|
|
3481
3529
|
// @ts-expect-error
|
|
3482
3530
|
const format: Exclude<KeyFormat, 'jwk'> = 'raw-seed'
|
|
3483
3531
|
// @ts-expect-error
|
|
@@ -3487,7 +3535,7 @@ function MLKEM_SHARED(): KEM_BASE {
|
|
|
3487
3535
|
this.name,
|
|
3488
3536
|
)
|
|
3489
3537
|
},
|
|
3490
|
-
async Encap(this:
|
|
3538
|
+
async Encap(this: DirectKEM, pkR) {
|
|
3491
3539
|
assertKeyAlgorithm(pkR, this.algorithm)
|
|
3492
3540
|
|
|
3493
3541
|
const { sharedKey, ciphertext } = (await subtle(
|
|
@@ -3498,7 +3546,7 @@ function MLKEM_SHARED(): KEM_BASE {
|
|
|
3498
3546
|
|
|
3499
3547
|
return { shared_secret: new Uint8Array(sharedKey), enc: new Uint8Array(ciphertext) }
|
|
3500
3548
|
},
|
|
3501
|
-
async Decap(this:
|
|
3549
|
+
async Decap(this: DirectKEM, enc, skR, _pkR) {
|
|
3502
3550
|
assertKeyAlgorithm(skR, this.algorithm)
|
|
3503
3551
|
return new Uint8Array(
|
|
3504
3552
|
await subtle(
|
|
@@ -3511,6 +3559,25 @@ function MLKEM_SHARED(): KEM_BASE {
|
|
|
3511
3559
|
}
|
|
3512
3560
|
}
|
|
3513
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
|
+
|
|
3514
3581
|
// ============================================================================
|
|
3515
3582
|
// KEM (Key Encapsulation Mechanism) - ML-KEM Suite Exports
|
|
3516
3583
|
// ============================================================================
|
|
@@ -3536,27 +3603,16 @@ function MLKEM_SHARED(): KEM_BASE {
|
|
|
3536
3603
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
3537
3604
|
*
|
|
3538
3605
|
* @group KEM Algorithms
|
|
3539
|
-
* @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
3606
|
+
* @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-3)
|
|
3540
3607
|
*/
|
|
3541
|
-
export const KEM_ML_KEM_512: KEMFactory = function ():
|
|
3608
|
+
export const KEM_ML_KEM_512: KEMFactory<CryptoKey> = function (): DirectKEM {
|
|
3542
3609
|
const id = 0x0040
|
|
3543
3610
|
const name = 'ML-KEM-512'
|
|
3544
|
-
const
|
|
3545
|
-
|
|
3546
|
-
|
|
3547
|
-
|
|
3548
|
-
|
|
3549
|
-
suite_id: concat(L_KEM, I2OSP(id, 2)),
|
|
3550
|
-
type: 'KEM',
|
|
3551
|
-
name,
|
|
3552
|
-
Nsecret: 32,
|
|
3553
|
-
Nenc: 768,
|
|
3554
|
-
Npk: 800,
|
|
3555
|
-
Nsk: 64,
|
|
3556
|
-
algorithm: { name: 'ML-KEM-512' },
|
|
3557
|
-
kdf,
|
|
3558
|
-
...MLKEM_SHARED(),
|
|
3559
|
-
}
|
|
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 })
|
|
3560
3616
|
}
|
|
3561
3617
|
|
|
3562
3618
|
/**
|
|
@@ -3576,27 +3632,16 @@ export const KEM_ML_KEM_512: KEMFactory = function (): MLKEM {
|
|
|
3576
3632
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
3577
3633
|
*
|
|
3578
3634
|
* @group KEM Algorithms
|
|
3579
|
-
* @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
3635
|
+
* @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-3)
|
|
3580
3636
|
*/
|
|
3581
|
-
export const KEM_ML_KEM_768: KEMFactory = function ():
|
|
3637
|
+
export const KEM_ML_KEM_768: KEMFactory<CryptoKey> = function (): DirectKEM {
|
|
3582
3638
|
const id = 0x0041
|
|
3583
3639
|
const name = 'ML-KEM-768'
|
|
3584
|
-
const
|
|
3585
|
-
|
|
3586
|
-
|
|
3587
|
-
|
|
3588
|
-
|
|
3589
|
-
suite_id: concat(L_KEM, I2OSP(id, 2)),
|
|
3590
|
-
type: 'KEM',
|
|
3591
|
-
name,
|
|
3592
|
-
Nsecret: 32,
|
|
3593
|
-
Nenc: 1088,
|
|
3594
|
-
Npk: 1184,
|
|
3595
|
-
Nsk: 64,
|
|
3596
|
-
algorithm: { name: 'ML-KEM-768' },
|
|
3597
|
-
kdf,
|
|
3598
|
-
...MLKEM_SHARED(),
|
|
3599
|
-
}
|
|
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 })
|
|
3600
3645
|
}
|
|
3601
3646
|
|
|
3602
3647
|
/**
|
|
@@ -3616,27 +3661,16 @@ export const KEM_ML_KEM_768: KEMFactory = function (): MLKEM {
|
|
|
3616
3661
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
3617
3662
|
*
|
|
3618
3663
|
* @group KEM Algorithms
|
|
3619
|
-
* @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
3664
|
+
* @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-3)
|
|
3620
3665
|
*/
|
|
3621
|
-
export const KEM_ML_KEM_1024: KEMFactory = function ():
|
|
3666
|
+
export const KEM_ML_KEM_1024: KEMFactory<CryptoKey> = function (): DirectKEM {
|
|
3622
3667
|
const id = 0x0042
|
|
3623
3668
|
const name = 'ML-KEM-1024'
|
|
3624
|
-
const
|
|
3625
|
-
|
|
3626
|
-
|
|
3627
|
-
|
|
3628
|
-
|
|
3629
|
-
suite_id: concat(L_KEM, I2OSP(id, 2)),
|
|
3630
|
-
type: 'KEM',
|
|
3631
|
-
name,
|
|
3632
|
-
Nsecret: 32,
|
|
3633
|
-
Nenc: 1568,
|
|
3634
|
-
Npk: 1568,
|
|
3635
|
-
Nsk: 64,
|
|
3636
|
-
algorithm: { name: 'ML-KEM-1024' },
|
|
3637
|
-
kdf,
|
|
3638
|
-
...MLKEM_SHARED(),
|
|
3639
|
-
}
|
|
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 })
|
|
3640
3674
|
}
|
|
3641
3675
|
|
|
3642
3676
|
interface WebCryptoAEAD extends AEAD {
|
|
@@ -3728,7 +3762,7 @@ function AEAD_SHARED(P_MAX: number): AEAD_BASE {
|
|
|
3728
3762
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
3729
3763
|
*
|
|
3730
3764
|
* @group AEAD Algorithms
|
|
3731
|
-
* @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
3765
|
+
* @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.3)
|
|
3732
3766
|
*/
|
|
3733
3767
|
export const AEAD_AES_128_GCM: AEADFactory = function (): WebCryptoAEAD {
|
|
3734
3768
|
return {
|
|
@@ -3760,7 +3794,7 @@ export const AEAD_AES_128_GCM: AEADFactory = function (): WebCryptoAEAD {
|
|
|
3760
3794
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
3761
3795
|
*
|
|
3762
3796
|
* @group AEAD Algorithms
|
|
3763
|
-
* @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
3797
|
+
* @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.3)
|
|
3764
3798
|
*/
|
|
3765
3799
|
export const AEAD_AES_256_GCM: AEADFactory = function (): WebCryptoAEAD {
|
|
3766
3800
|
return {
|
|
@@ -3792,7 +3826,7 @@ export const AEAD_AES_256_GCM: AEADFactory = function (): WebCryptoAEAD {
|
|
|
3792
3826
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
3793
3827
|
*
|
|
3794
3828
|
* @group AEAD Algorithms
|
|
3795
|
-
* @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
3829
|
+
* @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.3)
|
|
3796
3830
|
*/
|
|
3797
3831
|
export const AEAD_ChaCha20Poly1305: AEADFactory = function AEAD_ChaCha20Poly1305(): WebCryptoAEAD {
|
|
3798
3832
|
return {
|
|
@@ -3810,7 +3844,7 @@ export const AEAD_ChaCha20Poly1305: AEADFactory = function AEAD_ChaCha20Poly1305
|
|
|
3810
3844
|
}
|
|
3811
3845
|
|
|
3812
3846
|
// ============================================================================
|
|
3813
|
-
// KEM (Key Encapsulation Mechanism) - Hybrid KEM Types and Implementation
|
|
3847
|
+
// KEM (Key Encapsulation Mechanism) - Composite Hybrid KEM Types and Implementation
|
|
3814
3848
|
// ============================================================================
|
|
3815
3849
|
|
|
3816
3850
|
/* c8 ignore next 5 */
|
|
@@ -3910,7 +3944,7 @@ function split(N1: number, N2: number, x: Uint8Array): [Uint8Array, Uint8Array]
|
|
|
3910
3944
|
return [x1, x2]
|
|
3911
3945
|
}
|
|
3912
3946
|
|
|
3913
|
-
function RandomScalarNist(t:
|
|
3947
|
+
function RandomScalarNist(t: CompositeHybridKEM['t'], seed: Uint8Array): Uint8Array {
|
|
3914
3948
|
let sk_bigint = 0n
|
|
3915
3949
|
let start = 0
|
|
3916
3950
|
let end = t.Nscalar!
|
|
@@ -3927,70 +3961,70 @@ function RandomScalarNist(t: HybridKEM['t'], seed: Uint8Array): Uint8Array {
|
|
|
3927
3961
|
return bigIntToUint8Array(sk_bigint, t.Nscalar!)
|
|
3928
3962
|
}
|
|
3929
3963
|
|
|
3930
|
-
/** @see [expandDecapsKeyG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-
|
|
3931
|
-
async function expandDecapsKeyG(
|
|
3932
|
-
const Nout =
|
|
3964
|
+
/** @see [expandDecapsKeyG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.1) */
|
|
3965
|
+
async function expandDecapsKeyG(kem: CompositeHybridKEM, seed: Uint8Array) {
|
|
3966
|
+
const Nout = kem.pq.Nseed + kem.t.Nseed
|
|
3933
3967
|
const bits = Nout << 3
|
|
3934
3968
|
// @ts-expect-error
|
|
3935
3969
|
const algorithm: CShakeParams = { name: 'cSHAKE256', length: bits, outputLength: bits }
|
|
3936
|
-
const seed_full = await subtle((c) => c.digest(algorithm, seed as BufferSource),
|
|
3970
|
+
const seed_full = await subtle((c) => c.digest(algorithm, seed as BufferSource), kem.name)
|
|
3937
3971
|
|
|
3938
|
-
const [seed_PQ, seed_T] = split(
|
|
3972
|
+
const [seed_PQ, seed_T] = split(kem.pq.Nseed, kem.t.Nseed, new Uint8Array(seed_full))
|
|
3939
3973
|
|
|
3940
3974
|
// @ts-expect-error
|
|
3941
3975
|
const format: Exclude<KeyFormat, 'jwk'> = 'raw-seed'
|
|
3942
3976
|
// @ts-expect-error
|
|
3943
3977
|
const usages: [KeyUsage, KeyUsage] = ['decapsulateBits', 'encapsulateBits']
|
|
3944
3978
|
const dk_PQ = await subtle(
|
|
3945
|
-
(c) => c.importKey(format, seed_PQ as BufferSource,
|
|
3946
|
-
|
|
3979
|
+
(c) => c.importKey(format, seed_PQ as BufferSource, kem.pq.algorithm, true, [usages[0]]),
|
|
3980
|
+
kem.name,
|
|
3947
3981
|
)
|
|
3948
|
-
const ek_PQ = await getPublicKey(
|
|
3982
|
+
const ek_PQ = await getPublicKey(kem.name, dk_PQ, [usages[1]])
|
|
3949
3983
|
|
|
3950
|
-
const sk =
|
|
3951
|
-
const { privateKey: dk_T, publicKey: ek_T } = await
|
|
3984
|
+
const sk = kem.t.RandomScalar?.(seed_T) ?? seed_T
|
|
3985
|
+
const { privateKey: dk_T, publicKey: ek_T } = await kem.t.GetKeyPair(sk)
|
|
3952
3986
|
|
|
3953
3987
|
return { ek_PQ, ek_T, dk_PQ, dk_T }
|
|
3954
3988
|
}
|
|
3955
3989
|
|
|
3956
|
-
/** @see [C2PRICombiner](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-
|
|
3990
|
+
/** @see [C2PRICombiner](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.3) */
|
|
3957
3991
|
async function C2PRICombiner(
|
|
3958
|
-
|
|
3992
|
+
kem: CompositeHybridKEM,
|
|
3959
3993
|
ss_PQ: Uint8Array,
|
|
3960
3994
|
ss_T: Uint8Array,
|
|
3961
3995
|
ct_T: Uint8Array,
|
|
3962
3996
|
_ek_T: CryptoKey,
|
|
3963
3997
|
label: Uint8Array,
|
|
3964
3998
|
): Promise<Uint8Array> {
|
|
3965
|
-
const ek_T = new Uint8Array(await subtle((c) => c.exportKey('raw', _ek_T),
|
|
3999
|
+
const ek_T = new Uint8Array(await subtle((c) => c.exportKey('raw', _ek_T), kem.name))
|
|
3966
4000
|
const data = concat(ss_PQ, ss_T, ct_T, ek_T, label) as BufferSource
|
|
3967
|
-
return new Uint8Array(await subtle((c) => c.digest('SHA3-256', data),
|
|
4001
|
+
return new Uint8Array(await subtle((c) => c.digest('SHA3-256', data), kem.name))
|
|
3968
4002
|
}
|
|
3969
4003
|
|
|
3970
|
-
/** @see [prepareEncapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-
|
|
4004
|
+
/** @see [prepareEncapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.1) */
|
|
3971
4005
|
async function prepareEncapsG(
|
|
3972
|
-
|
|
4006
|
+
kem: CompositeHybridKEM,
|
|
3973
4007
|
ek_PQ: CryptoKey,
|
|
3974
4008
|
ek_T: CryptoKey,
|
|
3975
4009
|
): Promise<[Uint8Array, Uint8Array, Uint8Array, Uint8Array]> {
|
|
3976
4010
|
const res = (await subtle(
|
|
3977
4011
|
// @ts-expect-error
|
|
3978
|
-
(c) => c.encapsulateBits(
|
|
3979
|
-
|
|
4012
|
+
(c) => c.encapsulateBits(kem.pq.algorithm, ek_PQ),
|
|
4013
|
+
kem.name,
|
|
3980
4014
|
)) as { sharedKey: ArrayBuffer; ciphertext: ArrayBuffer }
|
|
3981
4015
|
const ss_PQ = new Uint8Array(res.sharedKey)
|
|
3982
4016
|
const ct_PQ = new Uint8Array(res.ciphertext)
|
|
3983
4017
|
|
|
3984
4018
|
const { privateKey: sk_E, publicKey } = (await subtle(
|
|
3985
|
-
(c) => c.generateKey(
|
|
3986
|
-
|
|
4019
|
+
(c) => c.generateKey(kem.t.algorithm, true, ['deriveBits']),
|
|
4020
|
+
kem.name,
|
|
3987
4021
|
)) as CryptoKeyPair
|
|
3988
|
-
const ct_T = new Uint8Array(await subtle((c) => c.exportKey('raw', publicKey),
|
|
4022
|
+
const ct_T = new Uint8Array(await subtle((c) => c.exportKey('raw', publicKey), kem.name))
|
|
3989
4023
|
|
|
3990
4024
|
const ss_T = new Uint8Array(
|
|
3991
4025
|
await subtle(
|
|
3992
|
-
(c) => c.deriveBits({ name:
|
|
3993
|
-
|
|
4026
|
+
(c) => c.deriveBits({ name: kem.t.algorithm.name, public: ek_T }, sk_E, kem.t.Nss << 3),
|
|
4027
|
+
kem.name,
|
|
3994
4028
|
),
|
|
3995
4029
|
)
|
|
3996
4030
|
checkNotAllZeros(ss_T)
|
|
@@ -3998,9 +4032,9 @@ async function prepareEncapsG(
|
|
|
3998
4032
|
return [ss_PQ, ss_T, ct_PQ, ct_T]
|
|
3999
4033
|
}
|
|
4000
4034
|
|
|
4001
|
-
/** @see [prepareDecapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-
|
|
4035
|
+
/** @see [prepareDecapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.1) */
|
|
4002
4036
|
async function prepareDecapsG(
|
|
4003
|
-
|
|
4037
|
+
kem: CompositeHybridKEM,
|
|
4004
4038
|
dk_PQ: CryptoKey,
|
|
4005
4039
|
dk_T: CryptoKey,
|
|
4006
4040
|
ct_PQ: Uint8Array,
|
|
@@ -4009,20 +4043,20 @@ async function prepareDecapsG(
|
|
|
4009
4043
|
const ss_PQ = new Uint8Array(
|
|
4010
4044
|
await subtle(
|
|
4011
4045
|
// @ts-expect-error
|
|
4012
|
-
(c) => c.decapsulateBits(
|
|
4013
|
-
|
|
4046
|
+
(c) => c.decapsulateBits(kem.pq.algorithm, dk_PQ, ct_PQ),
|
|
4047
|
+
kem.name,
|
|
4014
4048
|
),
|
|
4015
4049
|
)
|
|
4016
4050
|
|
|
4017
4051
|
const pub = await subtle(
|
|
4018
|
-
(c) => c.importKey('raw', ct_T as BufferSource,
|
|
4019
|
-
|
|
4052
|
+
(c) => c.importKey('raw', ct_T as BufferSource, kem.t.algorithm, true, []),
|
|
4053
|
+
kem.name,
|
|
4020
4054
|
)
|
|
4021
4055
|
|
|
4022
4056
|
const ss_T = new Uint8Array(
|
|
4023
4057
|
await subtle(
|
|
4024
|
-
(c) => c.deriveBits({ name:
|
|
4025
|
-
|
|
4058
|
+
(c) => c.deriveBits({ name: kem.t.algorithm.name, public: pub }, dk_T, kem.t.Nss << 3),
|
|
4059
|
+
kem.name,
|
|
4026
4060
|
),
|
|
4027
4061
|
)
|
|
4028
4062
|
checkNotAllZeros(ss_T)
|
|
@@ -4030,7 +4064,7 @@ async function prepareDecapsG(
|
|
|
4030
4064
|
return [ss_PQ, ss_T]
|
|
4031
4065
|
}
|
|
4032
4066
|
|
|
4033
|
-
interface
|
|
4067
|
+
interface CompositeHybridKEM extends KEM<HybridKey> {
|
|
4034
4068
|
readonly suite_id: Uint8Array
|
|
4035
4069
|
readonly kdf: KDF
|
|
4036
4070
|
readonly algorithm: KeyAlgorithm
|
|
@@ -4050,18 +4084,20 @@ interface HybridKEM extends KEM {
|
|
|
4050
4084
|
readonly Nsk: number
|
|
4051
4085
|
readonly Nscalar?: number
|
|
4052
4086
|
readonly GetKeyPair: (
|
|
4053
|
-
this:
|
|
4087
|
+
this: CompositeHybridKEM['t'],
|
|
4054
4088
|
sk: Uint8Array,
|
|
4055
4089
|
) => Promise<{ privateKey: CryptoKey; publicKey: CryptoKey }>
|
|
4056
4090
|
readonly order?: bigint
|
|
4057
|
-
readonly RandomScalar?: (this:
|
|
4091
|
+
readonly RandomScalar?: (this: CompositeHybridKEM['t'], seed: Uint8Array) => Uint8Array
|
|
4058
4092
|
}
|
|
4059
4093
|
}
|
|
4060
4094
|
|
|
4061
|
-
|
|
4095
|
+
type CompositeHybridKEMParams = KEMParams & Pick<CompositeHybridKEM, 'pq' | 't' | 'label'>
|
|
4096
|
+
|
|
4097
|
+
function COMPOSITE_HYBRID_KEM_SHARED(): KEM_BASE<HybridKey> {
|
|
4062
4098
|
Object.freeze(HybridKey.prototype)
|
|
4063
4099
|
return {
|
|
4064
|
-
async DeriveKeyPair(this:
|
|
4100
|
+
async DeriveKeyPair(this: CompositeHybridKEM, ikm: Uint8Array, extractable) {
|
|
4065
4101
|
const seed = await LabeledDerive(
|
|
4066
4102
|
this.kdf,
|
|
4067
4103
|
this.suite_id,
|
|
@@ -4087,10 +4123,10 @@ function PQTKEM_SHARED(): KEM_BASE {
|
|
|
4087
4123
|
|
|
4088
4124
|
return { privateKey, publicKey }
|
|
4089
4125
|
},
|
|
4090
|
-
async GenerateKeyPair(this:
|
|
4126
|
+
async GenerateKeyPair(this: CompositeHybridKEM, extractable) {
|
|
4091
4127
|
return await this.DeriveKeyPair(crypto.getRandomValues(new Uint8Array(32)), extractable)
|
|
4092
4128
|
},
|
|
4093
|
-
async SerializePublicKey(this:
|
|
4129
|
+
async SerializePublicKey(this: CompositeHybridKEM, key) {
|
|
4094
4130
|
assertKeyAlgorithm(key, this.algorithm)
|
|
4095
4131
|
HybridKey.validate(key, true)
|
|
4096
4132
|
// @ts-expect-error
|
|
@@ -4104,7 +4140,7 @@ function PQTKEM_SHARED(): KEM_BASE {
|
|
|
4104
4140
|
|
|
4105
4141
|
return concat(ek_PQ, ek_T)
|
|
4106
4142
|
},
|
|
4107
|
-
async DeserializePublicKey(this:
|
|
4143
|
+
async DeserializePublicKey(this: CompositeHybridKEM, key) {
|
|
4108
4144
|
// @ts-expect-error
|
|
4109
4145
|
const format: Exclude<KeyFormat, 'jwk'> = 'raw-public'
|
|
4110
4146
|
// @ts-expect-error
|
|
@@ -4118,13 +4154,13 @@ function PQTKEM_SHARED(): KEM_BASE {
|
|
|
4118
4154
|
|
|
4119
4155
|
return new HybridKey(priv, this.algorithm, 'public', true, ek_PQ, ek_T)
|
|
4120
4156
|
},
|
|
4121
|
-
async SerializePrivateKey(this:
|
|
4157
|
+
async SerializePrivateKey(this: CompositeHybridKEM, key) {
|
|
4122
4158
|
assertKeyAlgorithm(key, this.algorithm)
|
|
4123
4159
|
HybridKey.validate(key, true)
|
|
4124
4160
|
|
|
4125
4161
|
return key.getSeed(priv)
|
|
4126
4162
|
},
|
|
4127
|
-
async DeserializePrivateKey(this:
|
|
4163
|
+
async DeserializePrivateKey(this: CompositeHybridKEM, key, extractable) {
|
|
4128
4164
|
const { ek_PQ, ek_T, dk_PQ, dk_T } = await expandDecapsKeyG(this, key)
|
|
4129
4165
|
const publicKey = new HybridKey(priv, this.algorithm, 'public', true, ek_PQ, ek_T)
|
|
4130
4166
|
const privateKey = new HybridKey(
|
|
@@ -4140,7 +4176,7 @@ function PQTKEM_SHARED(): KEM_BASE {
|
|
|
4140
4176
|
|
|
4141
4177
|
return privateKey
|
|
4142
4178
|
},
|
|
4143
|
-
async Encap(this:
|
|
4179
|
+
async Encap(this: CompositeHybridKEM, pkR) {
|
|
4144
4180
|
assertKeyAlgorithm(pkR, this.algorithm)
|
|
4145
4181
|
HybridKey.validate(pkR)
|
|
4146
4182
|
|
|
@@ -4152,7 +4188,7 @@ function PQTKEM_SHARED(): KEM_BASE {
|
|
|
4152
4188
|
|
|
4153
4189
|
return { shared_secret: ss_H, enc: ct_H }
|
|
4154
4190
|
},
|
|
4155
|
-
async Decap(this:
|
|
4191
|
+
async Decap(this: CompositeHybridKEM, enc, skR, pkR) {
|
|
4156
4192
|
assertKeyAlgorithm(skR, this.algorithm)
|
|
4157
4193
|
HybridKey.validate(skR)
|
|
4158
4194
|
|
|
@@ -4174,6 +4210,20 @@ function PQTKEM_SHARED(): KEM_BASE {
|
|
|
4174
4210
|
}
|
|
4175
4211
|
}
|
|
4176
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
|
+
|
|
4177
4227
|
// ============================================================================
|
|
4178
4228
|
// KEM (Key Encapsulation Mechanism) - Hybrid KEM Suite Exports
|
|
4179
4229
|
// ============================================================================
|
|
@@ -4181,7 +4231,12 @@ function PQTKEM_SHARED(): KEM_BASE {
|
|
|
4181
4231
|
/**
|
|
4182
4232
|
* Hybrid KEM combining ML-KEM-768 with X25519 (MLKEM768-X25519).
|
|
4183
4233
|
*
|
|
4184
|
-
* Depends on the following Web Cryptography
|
|
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:
|
|
4185
4240
|
*
|
|
4186
4241
|
* - ML-KEM-768 key encapsulation
|
|
4187
4242
|
* - X25519 key agreement
|
|
@@ -4195,26 +4250,24 @@ function PQTKEM_SHARED(): KEM_BASE {
|
|
|
4195
4250
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
4196
4251
|
*
|
|
4197
4252
|
* @group KEM Algorithms
|
|
4198
|
-
* @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
4253
|
+
* @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-4)
|
|
4199
4254
|
*/
|
|
4200
|
-
export const KEM_MLKEM768_X25519: KEMFactory = function ():
|
|
4255
|
+
export const KEM_MLKEM768_X25519: KEMFactory = function (): CompositeHybridKEM | DirectKEM {
|
|
4201
4256
|
const id = 0x647a
|
|
4202
4257
|
const name = 'MLKEM768-X25519'
|
|
4203
|
-
const
|
|
4204
|
-
const
|
|
4205
|
-
|
|
4206
|
-
|
|
4207
|
-
|
|
4208
|
-
|
|
4209
|
-
|
|
4210
|
-
|
|
4211
|
-
|
|
4212
|
-
|
|
4213
|
-
|
|
4214
|
-
|
|
4215
|
-
|
|
4216
|
-
Nsk: 32,
|
|
4217
|
-
algorithm: { name: 'MLKEM768-X25519' },
|
|
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
|
+
|
|
4268
|
+
const pkcs8 = Uint8Array.of(0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x6e, 0x04, 0x22, 0x04, 0x20) // prettier-ignore
|
|
4269
|
+
return createCompositeHybridKEM({
|
|
4270
|
+
...kem,
|
|
4218
4271
|
pq: { algorithm: { name: 'ML-KEM-768' }, Nseed: 64, Npk: 1184, Nct: 1088 },
|
|
4219
4272
|
t: {
|
|
4220
4273
|
algorithm: { name: 'X25519' },
|
|
@@ -4231,14 +4284,18 @@ export const KEM_MLKEM768_X25519: KEMFactory = function (): HybridKEM {
|
|
|
4231
4284
|
},
|
|
4232
4285
|
},
|
|
4233
4286
|
label: Uint8Array.of(0x5c, 0x2e, 0x2f, 0x2f, 0x5e, 0x5c), // prettier-ignore
|
|
4234
|
-
|
|
4235
|
-
}
|
|
4287
|
+
})
|
|
4236
4288
|
}
|
|
4237
4289
|
|
|
4238
4290
|
/**
|
|
4239
4291
|
* Hybrid KEM combining ML-KEM-768 with P-256 (MLKEM768-P256).
|
|
4240
4292
|
*
|
|
4241
|
-
* Depends on the following Web Cryptography
|
|
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:
|
|
4242
4299
|
*
|
|
4243
4300
|
* - ML-KEM-768 key encapsulation
|
|
4244
4301
|
* - ECDH with P-256 curve
|
|
@@ -4252,25 +4309,23 @@ export const KEM_MLKEM768_X25519: KEMFactory = function (): HybridKEM {
|
|
|
4252
4309
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
4253
4310
|
*
|
|
4254
4311
|
* @group KEM Algorithms
|
|
4255
|
-
* @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
4312
|
+
* @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-4)
|
|
4256
4313
|
*/
|
|
4257
|
-
export const KEM_MLKEM768_P256: KEMFactory = function ():
|
|
4314
|
+
export const KEM_MLKEM768_P256: KEMFactory = function (): CompositeHybridKEM | DirectKEM {
|
|
4258
4315
|
const id = 0x0050
|
|
4259
4316
|
const name = 'MLKEM768-P256'
|
|
4260
|
-
const
|
|
4261
|
-
|
|
4262
|
-
|
|
4263
|
-
|
|
4264
|
-
|
|
4265
|
-
|
|
4266
|
-
|
|
4267
|
-
|
|
4268
|
-
|
|
4269
|
-
|
|
4270
|
-
|
|
4271
|
-
|
|
4272
|
-
Nsk: 32,
|
|
4273
|
-
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,
|
|
4274
4329
|
pq: { algorithm: { name: 'ML-KEM-768' }, Nseed: 64, Npk: 1184, Nct: 1088 },
|
|
4275
4330
|
t: {
|
|
4276
4331
|
...P256,
|
|
@@ -4287,14 +4342,18 @@ export const KEM_MLKEM768_P256: KEMFactory = function (): HybridKEM {
|
|
|
4287
4342
|
},
|
|
4288
4343
|
},
|
|
4289
4344
|
label: Uint8Array.of(0x4d, 0x4c, 0x4b, 0x45, 0x4d, 0x37, 0x36, 0x38, 0x2d, 0x50, 0x32, 0x35, 0x36), // prettier-ignore
|
|
4290
|
-
|
|
4291
|
-
}
|
|
4345
|
+
})
|
|
4292
4346
|
}
|
|
4293
4347
|
|
|
4294
4348
|
/**
|
|
4295
4349
|
* Hybrid KEM combining ML-KEM-1024 with P-384 (MLKEM1024-P384).
|
|
4296
4350
|
*
|
|
4297
|
-
* Depends on the following Web Cryptography
|
|
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:
|
|
4298
4357
|
*
|
|
4299
4358
|
* - ML-KEM-1024 key encapsulation
|
|
4300
4359
|
* - ECDH with P-384 curve
|
|
@@ -4308,25 +4367,23 @@ export const KEM_MLKEM768_P256: KEMFactory = function (): HybridKEM {
|
|
|
4308
4367
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
4309
4368
|
*
|
|
4310
4369
|
* @group KEM Algorithms
|
|
4311
|
-
* @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
4370
|
+
* @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-4)
|
|
4312
4371
|
*/
|
|
4313
|
-
export const KEM_MLKEM1024_P384: KEMFactory = function ():
|
|
4372
|
+
export const KEM_MLKEM1024_P384: KEMFactory = function (): CompositeHybridKEM | DirectKEM {
|
|
4314
4373
|
const id = 0x0051
|
|
4315
4374
|
const name = 'MLKEM1024-P384'
|
|
4316
|
-
const
|
|
4317
|
-
|
|
4318
|
-
|
|
4319
|
-
|
|
4320
|
-
|
|
4321
|
-
|
|
4322
|
-
|
|
4323
|
-
|
|
4324
|
-
|
|
4325
|
-
|
|
4326
|
-
|
|
4327
|
-
|
|
4328
|
-
Nsk: 32,
|
|
4329
|
-
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,
|
|
4330
4387
|
pq: { algorithm: { name: 'ML-KEM-1024' }, Nseed: 64, Npk: 1568, Nct: 1568 },
|
|
4331
4388
|
t: {
|
|
4332
4389
|
...P384,
|
|
@@ -4344,6 +4401,5 @@ export const KEM_MLKEM1024_P384: KEMFactory = function (): HybridKEM {
|
|
|
4344
4401
|
},
|
|
4345
4402
|
},
|
|
4346
4403
|
label: Uint8Array.of(0x4d, 0x4c, 0x4b, 0x45, 0x4d, 0x31, 0x30, 0x32, 0x34, 0x2d, 0x50, 0x33, 0x38, 0x34), // prettier-ignore
|
|
4347
|
-
|
|
4348
|
-
}
|
|
4404
|
+
})
|
|
4349
4405
|
}
|