hpke 0.5.0 โ†’ 1.0.1

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/LICENSE.md ADDED
@@ -0,0 +1,21 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2025 Filip Skokan
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,83 +1,148 @@
1
- # Hybrid public key encryption with algorithms dispatched at runtime
1
+ # hpke
2
2
 
3
- This crate provides a generic-free interface to the [`hpke`][hpke]
4
- crate, a rust implementation of the draft RFC9180 [hybrid public key
5
- encryption](https://www.rfc-editor.org/rfc/rfc9180.html)
6
- scheme. If you know the specific (aead, kdf, kem) triple at compile
7
- time, you should use the [`hpke`][hpke] crate directly.
3
+ `hpke` is a JavaScript module for Hybrid Public Key Encryption (HPKE). This module is designed to
4
+ work across various Web-interoperable runtimes including Node.js, browsers, Cloudflare Workers,
5
+ Deno, Bun, and others.
8
6
 
9
- Currently, this crate only exposes interfaces for the Base mode (0)
10
- described in the hpke draft, and within base mode, only stateless
11
- single-shot message encryption/decryption, as defined in [RFC9180ยง6][section-6]
7
+ ## [๐Ÿ’— Help the project](https://github.com/sponsors/panva)
12
8
 
13
- [hpke]: https://github.com/rozbb/rust-hpke
14
- [section-6]: https://www.rfc-editor.org/rfc/rfc9180.html#section-6
9
+ Support from the community to continue maintaining and improving this module is welcome. If you find
10
+ this module useful, please consider supporting this project by
11
+ [becoming a sponsor](https://github.com/sponsors/panva).
15
12
 
16
- ## WebAssembly ready
13
+ ## Dependencies: 0
17
14
 
18
- This crate is also published to npm as [`hpke`][npm] as a
19
- typescript/javascript package, and can also be custom built for
20
- specific wasm use cases (omitting unused algorithms) with
21
- [`wasm-pack`][wasm-pack]. For an example of using the library from
22
- node, see [examples/example.ts][example-ts]
15
+ `hpke` has no dependencies and it exports tree-shakeable ESM.
23
16
 
24
- [npm]: https://www.npmjs.com/package/hpke
25
- [wasm-pack]: https://github.com/rustwasm/wasm-pack
26
- [example-ts]: https://github.com/jbr/hpke-dispatch/blob/main/examples/example.ts
17
+ ## [API Reference](docs/README.md)
27
18
 
28
- ## Nightly-only feature to work around a wasm-bindgen bug: `cfg_eval`
19
+ `hpke` is distributed via [npmjs.com](https://www.npmjs.com/package/hpke),
20
+ [jsdelivr.com](https://www.jsdelivr.com/package/npm/hpke), and
21
+ [github.com](https://github.com/panva/hpke).
29
22
 
30
- In order to opt out of `algo-all` for a wasm build, you must use
31
- nightly and enable the `cfg_eval` cargo feature. This is due to
32
- [wasm-bindgen#2058][wasm-bindgen-2058]. This is not necessary for use
33
- from rust, even when opting out of `algo-all`.
23
+ ## Quick Start
34
24
 
35
- [hpke]: https://docs.rs/hpke/latest/hpke/
36
- [wasm-bindgen-2058]: https://github.com/rustwasm/wasm-bindgen/issues/2058
25
+ ```ts
26
+ import * as HPKE from 'hpke'
37
27
 
38
- ## Available cargo features:
28
+ // 1. Choose a cipher suite
29
+ const suite = new HPKE.CipherSuite(
30
+ HPKE.KEM_DHKEM_P256_HKDF_SHA256,
31
+ HPKE.KDF_HKDF_SHA256,
32
+ HPKE.AEAD_AES_128_GCM,
33
+ )
39
34
 
40
- * *`cfg_eval`*: allows this crate to be built on nightly rust for wasm
41
- without `algo-all`. Note that `algo-all` (all
42
- algorithms) will build for wasm on any channel without this feature.
43
- disabled by default. Attempting to build for wasm with a subset.
35
+ // 2. Generate recipient key pair
36
+ const recipient = await suite.GenerateKeyPair()
44
37
 
45
- * *base-mode-open*: Enables hpke base-mode one-shot open behavior
46
- (receiver functionality). Enabled by default.
38
+ // 3. Encrypt a message
39
+ const plaintext = new TextEncoder().encode('Hello, World!')
40
+ const { encapsulatedSecret, ciphertext } = await suite.Seal(recipient.publicKey, plaintext)
47
41
 
48
- * *base-mode-seal*: Enables hpke base-mode one-shot seal behavior
49
- (sender functionality). Enabled by default.
42
+ // 4. Decrypt the message
43
+ const decrypted = await suite.Open(recipient.privateKey, encapsulatedSecret, ciphertext)
44
+ console.log(new TextDecoder().decode(decrypted)) // "Hello, World!"
45
+ ```
50
46
 
51
- * *algo-all*: enables all aead, kdf, and kem algorithms. enabled by
52
- default.
47
+ ## [Examples](examples/README.md)
53
48
 
54
- * *aead-all*: Enables `aead-aes-gcm-128`, `aead-aes-gcm-256`, and
55
- `aead-chacha-20-poly-1305` algorithm features. Enabled by default.
49
+ For more advanced examples, including how to integrate external cryptographic libraries, see the
50
+ [examples directory](examples/README.md).
56
51
 
57
- * *kdf-all*: Enables `kdf-sha256`, `kdf-sha384`, `kdf-sha512`
58
- algorithm features. Enabled by default.
52
+ ## Supported Runtimes
59
53
 
60
- * *kem-all*: Enables both `kem-dh-p256-hkdf-sha256` and
61
- `kem-x25519-hkdf-sha256` algorithm features. Enabled by default.
54
+ This module is compatible with JavaScript runtimes that support the utilized Web API globals and
55
+ standard built-in objects or are Node.js.
62
56
 
63
- * *serde*: enables derived serde serialization and deserialization for
64
- all public structs and enums. Disabled by default.
57
+ The following runtimes are supported _(this is not an exhaustive list)_:
65
58
 
66
- ## Example feature usage:
59
+ - Bun
60
+ - Browsers
61
+ - Cloudflare Workers
62
+ - Deno
63
+ - Electron
64
+ - Node.js
67
65
 
68
- To depend on this crate from rust with all algorithms,
69
- `base-mode-open`, and `base-mode-seal`, use default features.
66
+ Please note that some suites may not be available depending on the runtime used.
70
67
 
71
- To depend on this crate from rust with all algorithms and serde
72
- enabled, but without `base-mode-seal`: `default-features = false,
73
- features = ["algo-all", "base-mode-open", "serde"]`
68
+ ## Supported Algorithms
74
69
 
75
- To build for wasm without `kem-x25519-hkdf-sha256` or
76
- `base-mode-open`: `wasm-pack build --no-default-features --features
77
- aead-all,kdf-all,kem-dh-p256-hkdf-sha256,base-mode-seal,cfg_eval`
70
+ Algorithm implementations exposed by this module are built on top of [Web Cryptography][] (and its
71
+ extensions, e.g. [Secure Curves][], [Modern Algorithms][]). Runtimes implementing Web Cryptography
72
+ are not required to support all of its algorithms and so not all algorithms are available in all
73
+ runtimes.
78
74
 
79
- To build for wasm with all algorithms but without base-mode-open:
80
- `wasm-pack build --no-default-features --features
81
- algo-all,base-mode-seal`
75
+ This module is designed to be extensible, you can bring outside-built implementations of any KEM,
76
+ KDF, or AEAD algorithm into any JavaScript runtime by conforming to the respective interfaces
77
+ ([KEM](https://github.com/panva/hpke/blob/main/docs/interfaces/KEM.md),
78
+ [KDF](https://github.com/panva/hpke/blob/main/docs/interfaces/KDF.md), or
79
+ [AEAD](https://github.com/panva/hpke/blob/main/docs/interfaces/AEAD.md)). This allows you to use
80
+ alternative cryptographic libraries, native bindings, or specialized hardware implementations
81
+ alongside the built-in Web Cryptography-based algorithms.
82
82
 
83
+ For extended algorithm support across all runtimes, see [`@panva/hpke-noble`][extensibility], which
84
+ provides these KEM, KDF, and AEAD implementations using Paul Miller's
85
+ [@noble](https://paulmillr.com/noble/) cryptographic libraries. These implementations can be freely
86
+ mixed and matched with the built-in algorithms.
83
87
 
88
+ Below are the algorithms built in (based on Web Cryptography) and their runtime support matrix.
89
+
90
+ ### Key Encapsulation Mechanisms (KEM)
91
+
92
+ | Name | Node.js | Deno | Bun | CF Workers | [Browsers][] | [Extensibility][] |
93
+ | :--------------------------------------------- | :------: | :--: | :-: | :--------: | :----------: | :---------------: |
94
+ | DHKEM(P-256, HKDF-SHA256) <sub>`0x0010`</sub> | โœ“ | โœ“ | โœ“ | โœ“ | โœ“ | โœ“ |
95
+ | DHKEM(P-384, HKDF-SHA384) <sub>`0x0011`</sub> | โœ“ | โœ“ | โœ“ | โœ“ | โœ“ | โœ“ |
96
+ | DHKEM(P-521, HKDF-SHA512) <sub>`0x0012`</sub> | โœ“ | | โœ“ | โœ“ | โœ“ | โœ“ |
97
+ | DHKEM(X25519, HKDF-SHA256) <sub>`0x0020`</sub> | โœ“ | โœ“ | | โœ“ | โœ“ | โœ“ |
98
+ | DHKEM(X448, HKDF-SHA512) <sub>`0x0021`</sub> | โœ“ | | | | | โœ“ |
99
+ | ML-KEM-512 <sub>`0x0040`</sub> | โœ“[^24.7] | | | | | โœ“ |
100
+ | ML-KEM-768 <sub>`0x0041`</sub> | โœ“[^24.7] | | | | | โœ“ |
101
+ | ML-KEM-1024 <sub>`0x0042`</sub> | โœ“[^24.7] | | | | | โœ“ |
102
+ | MLKEM768-P256 <sub>`0x0050`</sub> | โœ“[^24.7] | | | | | โœ“ |
103
+ | MLKEM768-X25519 <sub>`0x647a`</sub> | โœ“[^24.7] | | | | | โœ“ |
104
+ | MLKEM1024-P384 <sub>`0x0051`</sub> | โœ“[^24.7] | | | | | โœ“ |
105
+
106
+ ### Key Derivation Functions (KDF)
107
+
108
+ | Name | Node.js | Deno | Bun | CF Workers | [Browsers][] | [Extensibility][] |
109
+ | :-------------------------------- | :------: | :--: | :-: | :--------: | :----------: | :---------------: |
110
+ | HKDF-SHA256 <sub>`0x0001`</sub> | โœ“ | โœ“ | โœ“ | โœ“ | โœ“ | โœ“ |
111
+ | HKDF-SHA384 <sub>`0x0002`</sub> | โœ“ | โœ“ | โœ“ | โœ“ | โœ“ | โœ“ |
112
+ | HKDF-SHA512 <sub>`0x0003`</sub> | โœ“ | โœ“ | โœ“ | โœ“ | โœ“ | โœ“ |
113
+ | SHAKE128 <sub>`0x0010`</sub> | โœ“[^24.7] | | | | | โœ“ |
114
+ | SHAKE256 <sub>`0x0011`</sub> | โœ“[^24.7] | | | | | โœ“ |
115
+ | TurboSHAKE128 <sub>`0x0012`</sub> | | | | | | โœ“ |
116
+ | TurboSHAKE256 <sub>`0x0013`</sub> | | | | | | โœ“ |
117
+
118
+ ### Authenticated Encryption (AEAD)
119
+
120
+ | Name | Node.js | Deno | Bun | CF Workers | [Browsers][] | [Extensibility][] |
121
+ | :----------------------------------- | :------: | :--: | :-: | :--------: | :----------: | :---------------: |
122
+ | AES-128-GCM <sub>`0x0001`</sub> | โœ“ | โœ“ | โœ“ | โœ“ | โœ“ | โœ“ |
123
+ | AES-256-GCM <sub>`0x0002`</sub> | โœ“ | โœ“ | โœ“ | โœ“ | โœ“ | โœ“ |
124
+ | ChaCha20Poly1305 <sub>`0x0003`</sub> | โœ“[^24.7] | | | | | โœ“ |
125
+ | Export-only <sub>`0xffff`</sub> | โœ“ | โœ“ | โœ“ | โœ“ | โœ“ | |
126
+
127
+ ## Specifications
128
+
129
+ - [Hybrid Public Key Encryption](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-02)
130
+ - [Post-Quantum and Post-Quantum/Traditional Hybrid Algorithms for HPKE](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-03)
131
+
132
+ The algorithm implementations are being tested using test vectors from their respective
133
+ specifications.
134
+
135
+ ## Supported Versions
136
+
137
+ | Version | Security Fixes ๐Ÿ”‘ | Other Bug Fixes ๐Ÿž | New Features โญ |
138
+ | ----------------------------------------------- | ----------------- | ------------------ | --------------- |
139
+ | [v1.x](https://github.com/panva/hpke/tree/v1.x) | [Security Policy] | โœ“ | โœ“ |
140
+
141
+ [Web Cryptography]: https://www.w3.org/TR/webcrypto-2/
142
+ [Security Policy]: https://github.com/panva/hpke/security/policy
143
+ [Secure Curves]: https://wicg.github.io/webcrypto-secure-curves/
144
+ [Modern Algorithms]: https://wicg.github.io/webcrypto-modern-algos/
145
+ [extensibility]: https://github.com/panva/hpke/tree/main/examples/noble-suite#readme
146
+ [browsers]: https://panva.github.io/hpke/
147
+
148
+ [^24.7]: Available in Node.js versions >= 24.7.0