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