-
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.
Merge pull request #223 from dajiaji/bump-to-1_0_0
Bump version up to 1.0.0.
- Loading branch information
Showing
17 changed files
with
574 additions
and
845 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,231 @@ | ||
| <h1 align="center">@hpke/core</h1> | ||
|
|
||
| <div align="center"> | ||
| A TypeScript <a href="https://datatracker.ietf.org/doc/html/rfc9180">Hybrid Public Key Encryption (HPKE)</a> core module implemented using only <a href="https://www.w3.org/TR/WebCryptoAPI/">Web Cryptography API</a>. It does not support the X25519/X448-based KEMs and the ChaCha20Poly1305 AEAD, but it has no external module dependencies and is small in size.</div> | ||
| <p></p> | ||
|
|
||
| <div align="center"> | ||
|
|
||
| [Documentation](https://doc.deno.land/https://deno.land/x/hpke/core/mod.ts) | ||
|
|
||
| </div> | ||
|
|
||
| ## Index | ||
|
|
||
| - [Installation](#installation) | ||
| - [Web Browser](#web-browser) | ||
| - [Node.js](#nodejs) | ||
| - [Deno](#deno) | ||
| - [Cloudflare Workers](#cloudflare-workers) | ||
| - [Usage](#usage) | ||
| - [Contributing](#contributing) | ||
|
|
||
| ## 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/@hpke/core@1.0.0"; | ||
| // import { KemId, KdfId, AeadId, CipherSuite } from "https://esm.sh/@hpke/core@1.0.0"; | ||
| </script> | ||
|
|
||
| <!-- use the latest stable version --> | ||
| <script type="module"> | ||
| import * as hpke from "https://esm.sh/@hpke/core"; | ||
| // ... | ||
| </script> | ||
| ``` | ||
|
|
||
| Using unpkg: | ||
|
|
||
| ```html | ||
| <!-- use a specific version --> | ||
| <script type="module"> | ||
| import * as hpke from "https://unpkg.com/@hpke/core@1.0.0/esm/mod.js"; | ||
| import { KemId, KdfId, AeadId, CipherSuite} from "https://unpkg.com/@hpke/core@1.0.0/esm/mod.js"; | ||
| // ... | ||
| </script> | ||
| ``` | ||
|
|
||
| ### Node.js | ||
|
|
||
| Using npm: | ||
|
|
||
| ```sh | ||
| npm install @hpke/core | ||
| ``` | ||
|
|
||
| Using yarn: | ||
|
|
||
| ```sh | ||
| yarn add @hpke/core | ||
| ``` | ||
|
|
||
| ### Deno | ||
|
|
||
| Using deno.land: | ||
|
|
||
| ```js | ||
| // use a specific version | ||
| import * as hpke from "https://deno.land/x/hpke@1.0.0/core/mod.ts"; | ||
|
|
||
| // use the latest stable version | ||
| import * as hpke from "https://deno.land/x/hpke/core/mod.ts"; | ||
| ``` | ||
|
|
||
| ### Cloudflare Workers | ||
|
|
||
| ```sh | ||
| git clone git@github.com:dajiaji/hpke-js.git | ||
| cd hpke-js/core | ||
| npm install -g esbuild | ||
| deno task dnt | ||
| deno task minify > $YOUR_SRC_PATH/hpke-core.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/hpke-js@1.0.0"; | ||
| import { KemId, KdfId, AeadId, CipherSuite } from "https://esm.sh/@hpke/core@1.0.0"; | ||
| globalThis.doHpke = async () => { | ||
| const suite = new CipherSuite({ | ||
| kem: KemId.DhkemP256HkdfSha256, | ||
| kdf: KdfId.HkdfSha256, | ||
| aead: AeadId.Aes128Gcm | ||
| }); | ||
| 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 | ||
| import { AeadId, CipherSuite, KdfId, KemId } from "@hpke/core"; | ||
| // const { KemId, KdfId, AeadId, CipherSuite } = require("@hpke/core"); | ||
|
|
||
| async function doHpke() { | ||
| // setup | ||
| const suite = new CipherSuite({ | ||
| kem: KemId.DhkemP256HkdfSha256, | ||
| kdf: KdfId.HkdfSha256, | ||
| aead: AeadId.Aes128Gcm, | ||
| }); | ||
|
|
||
| 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 { KdfId, AeadId, CipherSuite } from "https://deno.land/x/hpke@1.0.0/core/mod.ts"; | ||
|
|
||
| async function doHpke() { | ||
| // setup | ||
| const suite = new CipherSuite({ | ||
| kem: KemId.DhkemP256HkdfSha256, | ||
| kdf: KdfId.HkdfSha256, | ||
| aead: AeadId.Aes128Gcm, | ||
| }); | ||
|
|
||
| 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. |
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
Oops, something went wrong.