-
Notifications
You must be signed in to change notification settings - Fork 9
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
25 changed files
with
976 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,247 @@ | ||
| <h1 align="center">@hpke/chacha20poly1305</h1> | ||
|
|
||
| <div align="center"> | ||
| A TypeScript <a href="https://datatracker.ietf.org/doc/html/rfc9180">Hybrid Public Key Encryption (HPKE)</a> module extension for AEAD with ChaCha20-Poly1305, which is implemented by using <a href="https://github.com/paulmillr/noble-ciphers">@noble/ciphers</a></div> | ||
| <p></p> | ||
|
|
||
| <div align="center"> | ||
|
|
||
| [Documentation](https://doc.deno.land/https://deno.land/x/hpke/x/chacha20poly1305/mod.ts) | ||
|
|
||
| </div> | ||
|
|
||
| ## Index | ||
|
|
||
| - [Supported Environments](#supported-environments) | ||
| - [Installation](#installation) | ||
| - [Web Browser](#web-browser) | ||
| - [Node.js](#nodejs) | ||
| - [Deno](#deno) | ||
| - [Cloudflare Workers](#cloudflare-workers) | ||
| - [Usage](#usage) | ||
| - [Contributing](#contributing) | ||
|
|
||
| ## Supported Environments | ||
|
|
||
| - **Web Browser**: [Web Cryptography API](https://www.w3.org/TR/WebCryptoAPI/) | ||
| supported browsers | ||
| - Confirmed: Chrome, Firefox, Edge, Safari, Opera, Vivaldi, Brave | ||
| - **Node.js**: 16.x, 17.x, 18.x, 19.x, 20.x | ||
| - **Deno**: 1.x (1.15-) | ||
| - **Cloudflare Workers** | ||
| - **bun**: 0.x (0.3.0-) | ||
|
|
||
| ## Installation | ||
|
|
||
| ### Web Browser | ||
|
|
||
| Followings are how to use with typical CDNs. Other CDNs can be used as well. | ||
|
|
||
| Using esm.sh: | ||
|
|
||
| ```html | ||
| <!-- use a specific version --> | ||
| <script type="module"> | ||
| import * as hpke from "https://esm.sh/[email protected]"; | ||
| import * as chacha20 from "https://esm.sh/@hpke/[email protected]"; | ||
| // ... | ||
| </script> | ||
|
|
||
| <!-- use the latest stable version --> | ||
| <script type="module"> | ||
| import * as hpke from "https://esm.sh/hpke-js"; | ||
| import * as chacha20 from "https://esm.sh/@hpke/chacha20poly1305"; | ||
| // ... | ||
| </script> | ||
| ``` | ||
|
|
||
| Using unpkg: | ||
|
|
||
| ```html | ||
| <!-- use a specific version --> | ||
| <script type="module"> | ||
| import * as hpke from "https://unpkg.com/[email protected]/esm/mod.js"; | ||
| import * as chacha20 from "https://unpkg.com/@hpke/[email protected]/esm/mod.js"; | ||
| // ... | ||
| </script> | ||
| ``` | ||
|
|
||
| ### Node.js | ||
|
|
||
| Using npm: | ||
|
|
||
| ```sh | ||
| npm install @hpke/chacha20poly1305 | ||
| ``` | ||
|
|
||
| Using yarn: | ||
|
|
||
| ```sh | ||
| yarn add @hpke/chacha20poly1305 | ||
| ``` | ||
|
|
||
| ### Deno | ||
|
|
||
| Using deno.land: | ||
|
|
||
| ```js | ||
| // use a specific version | ||
| import * as hpke from "https://deno.land/x/[email protected]/mod.ts"; | ||
| import * as chacha20 from "https://deno.land/x/[email protected]/x/chacha20poly1305/mod.ts"; | ||
|
|
||
| // use the latest stable version | ||
| import * as hpke from "https://deno.land/x/hpke/mod.ts"; | ||
| import * as chacha20 from "https://deno.land/x/hpke/x/chacha20poly1305/mod.ts"; | ||
| ``` | ||
|
|
||
| ### Cloudflare Workers | ||
|
|
||
| Downloads a single js file from esm.sh: | ||
|
|
||
| ```sh | ||
| curl -sS -o $YOUR_SRC_PATH/hpke.min.js https://esm.sh/v86/[email protected]/es2022/hpke.min.js | ||
| curl -sS -o $YOUR_SRC_PATH/hpke-chacha20poly1305.min.js https://esm.sh/v86/@hpke/[email protected]/es2022/hpke-chacha20poly1305.min.js | ||
| ``` | ||
|
|
||
| ## Usage | ||
|
|
||
| This section shows some typical usage examples. | ||
|
|
||
| ### Browsers | ||
|
|
||
| ```html | ||
| <html> | ||
| <head></head> | ||
| <body> | ||
| <script type="module"> | ||
| // import * as hpke from "https://esm.sh/[email protected]"; | ||
| import { KemId, KdfId, CipherSuite } from "https://esm.sh/[email protected]"; | ||
| import { Chacha20Poly1305 } from "https://esm.sh/@hpke/[email protected]"; | ||
| globalThis.doHpke = async () => { | ||
| const suite = new CipherSuite({ | ||
| kem: KemId.DhkemP256HkdfSha256, | ||
| kdf: KdfId.HkdfSha256, | ||
| aead: new Chacha20Poly1305() | ||
| }); | ||
| const rkp = await suite.generateKeyPair(); | ||
| const sender = await suite.createSenderContext({ | ||
| recipientPublicKey: rkp.publicKey | ||
| }); | ||
| const recipient = await suite.createRecipientContext({ | ||
| recipientKey: rkp.privateKey, // rkp (CryptoKeyPair) is also acceptable. | ||
| enc: sender.enc, | ||
| }); | ||
| // encrypt | ||
| const ct = await sender.seal(new TextEncoder().encode("hello world!")); | ||
| // decrypt | ||
| try { | ||
| const pt = await recipient.open(ct); | ||
| // hello world! | ||
| alert(new TextDecoder().decode(pt)); | ||
| } catch (err) { | ||
| alert("failed to decrypt."); | ||
| } | ||
| } | ||
| </script> | ||
| <button type="button" onclick="doHpke()">do HPKE</button> | ||
| </body> | ||
| </html> | ||
| ``` | ||
|
|
||
| ### Node.js | ||
|
|
||
| ```js | ||
| const { KemId, KdfId, CipherSuite } = require("hpke-js"); | ||
| const { Chacha20Poly1305 } = require("@hpke/chacha20poly1305"); | ||
|
|
||
| async function doHpke() { | ||
| // setup | ||
| const suite = new CipherSuite({ | ||
| kem: KemId.DhkemP256HkdfSha256, | ||
| kdf: KdfId.HkdfSha256, | ||
| aead: new Chacha20Poly1305(), | ||
| }); | ||
|
|
||
| const rkp = await suite.generateKeyPair(); | ||
|
|
||
| const sender = await suite.createSenderContext({ | ||
| recipientPublicKey: rkp.publicKey, | ||
| }); | ||
|
|
||
| const recipient = await suite.createRecipientContext({ | ||
| recipientKey: rkp.privateKey, | ||
| enc: sender.enc, | ||
| }); | ||
|
|
||
| // encrypt | ||
| const ct = await sender.seal(new TextEncoder().encode("my-secret-message")); | ||
|
|
||
| // decrypt | ||
| try { | ||
| const pt = await recipient.open(ct); | ||
|
|
||
| console.log("decrypted: ", new TextDecoder().decode(pt)); | ||
| // decrypted: my-secret-message | ||
| } catch (err) { | ||
| console.log("failed to decrypt."); | ||
| } | ||
| } | ||
|
|
||
| doHpke(); | ||
| ``` | ||
|
|
||
| ### Deno | ||
|
|
||
| ```js | ||
| import { KemId, KdfId, CipherSuite } from "https://deno.land/x/[email protected]/mod.ts"; | ||
| import { Chacha20Poly1305 } from "https://deno.land/x/[email protected]/x/chacha20poly1305/mod.ts"; | ||
|
|
||
| async function doHpke() { | ||
| // setup | ||
| const suite = new CipherSuite({ | ||
| kem: KemId.DhkemP256HkdfSha256, | ||
| kdf: KdfId.HkdfSha256, | ||
| aead: new Chacha20Poly1305(), | ||
| }); | ||
|
|
||
| const rkp = await suite.generateKeyPair(); | ||
|
|
||
| const sender = await suite.createSenderContext({ | ||
| recipientPublicKey: rkp.publicKey, | ||
| }); | ||
|
|
||
| const recipient = await suite.createRecipientContext({ | ||
| recipientKey: rkp.privateKey, | ||
| enc: sender.enc, | ||
| }); | ||
|
|
||
| // encrypt | ||
| const ct = await sender.seal(new TextEncoder().encode("my-secret-message")); | ||
|
|
||
| try { | ||
| // decrypt | ||
| const pt = await recipient.open(ct); | ||
|
|
||
| console.log("decrypted: ", new TextDecoder().decode(pt)); | ||
| // decrypted: my-secret-message | ||
| } catch (_err: unknown) { | ||
| console.log("failed to decrypt."); | ||
| } | ||
| } | ||
|
|
||
| doHpke(); | ||
| ``` | ||
|
|
||
| ## Contributing | ||
|
|
||
| We welcome all kind of contributions, filing issues, suggesting new features or | ||
| sending PRs. |
Oops, something went wrong.