From 107f59b0929abaeaa7c1cc27dc9f39863ef1e505 Mon Sep 17 00:00:00 2001 From: Ajitomi Daisuke Date: Mon, 4 Nov 2024 13:50:29 +0900 Subject: [PATCH 1/2] Add explanation for using as . --- packages/hybridkem-x-wing/README.md | 23 +++++++++++-------- .../hybridkem-x-wing/src/hybridkemXWing.ts | 16 +++++++++++++ 2 files changed, 30 insertions(+), 9 deletions(-) diff --git a/packages/hybridkem-x-wing/README.md b/packages/hybridkem-x-wing/README.md index fd3466535..6c50d0c88 100644 --- a/packages/hybridkem-x-wing/README.md +++ b/packages/hybridkem-x-wing/README.md @@ -130,20 +130,21 @@ async function doHpke() { const rkp = await suite.kem.generateKeyPair(); + // Note that the `ct` (ciphertext) resulting from X-Wing Encapsulate() is set to `sender.enc`. const sender = await suite.createSenderContext({ recipientPublicKey: rkp.publicKey, }); // encrypt - const ct = await sender.seal(new TextEncoder().encode("Hello world!")); + const encrypted = await sender.seal(new TextEncoder().encode("Hello world!")); const recipient = await suite.createRecipientContext({ recipientKey: rkp.privateKey, - enc: sender.enc, + enc: sender.enc, // == `ct` (ciphertext) for X-Wing }); // decrypt - const pt = await recipient.open(ct); + const pt = await recipient.open(encrypted); // Hello world! console.log(new TextDecoder().decode(pt)); @@ -172,20 +173,21 @@ async function doHpke() { const rkp = await suite.kem.generateKeyPair(); + // Note that the `ct` (ciphertext) resulting from X-Wing::Encapsulate() is set to `sender.enc`. const sender = await suite.createSenderContext({ recipientPublicKey: rkp.publicKey, }); // encrypt - const ct = await sender.seal(new TextEncoder().encode("Hello world!")); + const encrypted = await sender.seal(new TextEncoder().encode("Hello world!")); const recipient = await suite.createRecipientContext({ recipientKey: rkp.privateKey, - enc: sender.enc, + enc: sender.enc, // == `ct` (ciphertext) in the context of X-Wing }); // decrypt - const pt = await recipient.open(ct); + const pt = await recipient.open(encrypted); // Hello world! console.log(new TextDecoder().decode(pt)); @@ -222,19 +224,22 @@ try { const rkp = await suite.kem.generateKeyPair(); + // Note that the `ct` resulting from X-Wing::Encapsulate() is set to `sender.enc`. const sender = await suite.createSenderContext({ recipientPublicKey: rkp.publicKey, }); // encrypt - const ct = await sender.seal(new TextEncoder().encode("Hello world!")); + const encrypted = await sender.seal( + new TextEncoder().encode("Hello world!"), + ); const recipient = await suite.createRecipientContext({ recipientKey: rkp.privateKey, // rkp (CryptoKeyPair) is also acceptable. - enc: sender.enc, + enc: sender.enc, // == `ct` (ciphertext) for X-Wing }); // decrypt - const pt = await recipient.open(ct); + const pt = await recipient.open(encrypted); // Hello world! alert(new TextDecoder().decode(pt)); diff --git a/packages/hybridkem-x-wing/src/hybridkemXWing.ts b/packages/hybridkem-x-wing/src/hybridkemXWing.ts index 7e4314ed8..fb6340a3b 100644 --- a/packages/hybridkem-x-wing/src/hybridkemXWing.ts +++ b/packages/hybridkem-x-wing/src/hybridkemXWing.ts @@ -222,6 +222,13 @@ export class HybridkemXWing implements KemInterface { // return await this.deserializePrivateKey(key as ArrayBuffer); } + /** + * Encapsulates the shared secret and the `ct` (ciphertext) as `enc`. + * @param params The parameters for encapsulation. + * @returns {Promise<{ sharedSecret: ArrayBuffer; enc: ArrayBuffer }>} A promise that resolves with the `ss` (shared secret) as `sharedSecret` and the `ct` (ciphertext) as `enc`. + * @throws {InvalidParamError} Thrown if the length of the `ekm` is not 64 bytes. + * @throws {EncapError} Thrown if the shared secret cannot be encapsulated. + */ public async encap( params: SenderContextParams, ): Promise<{ sharedSecret: ArrayBuffer; enc: ArrayBuffer }> { @@ -268,6 +275,15 @@ export class HybridkemXWing implements KemInterface { } } + /** + * Decapsulates the `ss` (shared secret) from the `enc` and the recipient's private key. + * The `enc` is the same as the `ct` (ciphertext) resulting from `X-Wing::Encapsulate(), + * which is executed under the `encap()`. + * @param params The parameters for decapsulation. + * @returns {Promise} A promise that resolves with the shared secret. + * @throws {InvalidParamError} Thrown if the length of the `enc` is not 1120 bytes. + * @throws {DecapError} Thrown if the shared secret cannot be decapsulated. + */ public async decap(params: RecipientContextParams): Promise { const rSk = isCryptoKeyPair(params.recipientKey) ? params.recipientKey.privateKey From e1044955b18dfd478c3da7573ffbf61ad07c95a6 Mon Sep 17 00:00:00 2001 From: Ajitomi Daisuke Date: Mon, 4 Nov 2024 14:05:03 +0900 Subject: [PATCH 2/2] Use Aes256Gcm. --- packages/hybridkem-x-wing/README.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/packages/hybridkem-x-wing/README.md b/packages/hybridkem-x-wing/README.md index 6c50d0c88..60dd91dbf 100644 --- a/packages/hybridkem-x-wing/README.md +++ b/packages/hybridkem-x-wing/README.md @@ -27,7 +27,7 @@ Documentation: [jsr.io](https://jsr.io/@hpke/hybridkem-x-wing/doc) | ## Installation -`@hpke/hybridkem-x-wing` need to be used with +`@hpke/hybridkem-x-wing` needs to be used with [@hpke/core](https://github.com/dajiaji/hpke-js/blob/main/packages/core/README.md), which can be installed in the same manner as desribed below. @@ -52,7 +52,7 @@ such as Cloudflare Workers and Bun. Then, you can use the module from code like this: ```ts -import { Aes128Gcm, CipherSuite, HkdfSha256 } from "@hpke/core"; +import { Aes256Gcm, CipherSuite, HkdfSha256 } from "@hpke/core"; import { HybridkemXWing } from "@hpke/hybridkem-x-wing"; ``` @@ -75,7 +75,7 @@ Using esm.sh: