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 +21 -0
- package/README.md +123 -58
- package/index.d.ts +1824 -0
- package/index.d.ts.map +1 -0
- package/index.js +4170 -0
- package/index.ts +4170 -0
- package/package.json +68 -38
- package/LICENSE +0 -375
- package/pkg/node/.gitignore +0 -1
- package/pkg/node/LICENSE +0 -375
- package/pkg/node/README.md +0 -83
- package/pkg/node/hpke_dispatch.d.ts +0 -241
- package/pkg/node/hpke_dispatch.js +0 -812
- package/pkg/node/hpke_dispatch_bg.wasm +0 -0
- package/pkg/node/hpke_dispatch_bg.wasm.d.ts +0 -32
- package/pkg/node/index.spec.ts +0 -82
- package/pkg/node/package.json +0 -21
- package/pkg/web/.gitignore +0 -1
- package/pkg/web/LICENSE +0 -375
- package/pkg/web/README.md +0 -83
- package/pkg/web/hpke_dispatch.d.ts +0 -297
- package/pkg/web/hpke_dispatch.js +0 -852
- package/pkg/web/hpke_dispatch_bg.wasm +0 -0
- package/pkg/web/hpke_dispatch_bg.wasm.d.ts +0 -32
- package/pkg/web/index.mjs +0 -2
- package/pkg/web/index.mjs.map +0 -7
- package/pkg/web/index.ts +0 -5
- package/pkg/web/package.json +0 -22
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
|
-
#
|
|
1
|
+
# hpke
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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
|
-
|
|
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
|
-
|
|
14
|
-
|
|
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
|
-
##
|
|
13
|
+
## Dependencies: 0
|
|
17
14
|
|
|
18
|
-
|
|
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
|
-
[
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
36
|
-
|
|
25
|
+
```ts
|
|
26
|
+
import * as HPKE from 'hpke'
|
|
37
27
|
|
|
38
|
-
|
|
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
|
-
|
|
41
|
-
|
|
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
|
-
|
|
46
|
-
|
|
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
|
-
|
|
49
|
-
|
|
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
|
-
|
|
52
|
-
default.
|
|
47
|
+
## [Examples](examples/README.md)
|
|
53
48
|
|
|
54
|
-
|
|
55
|
-
|
|
49
|
+
For more advanced examples, including how to integrate external cryptographic libraries, see the
|
|
50
|
+
[examples directory](examples/README.md).
|
|
56
51
|
|
|
57
|
-
|
|
58
|
-
algorithm features. Enabled by default.
|
|
52
|
+
## Supported Runtimes
|
|
59
53
|
|
|
60
|
-
|
|
61
|
-
|
|
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
|
-
|
|
64
|
-
all public structs and enums. Disabled by default.
|
|
57
|
+
The following runtimes are supported _(this is not an exhaustive list)_:
|
|
65
58
|
|
|
66
|
-
|
|
59
|
+
- Bun
|
|
60
|
+
- Browsers
|
|
61
|
+
- Cloudflare Workers
|
|
62
|
+
- Deno
|
|
63
|
+
- Electron
|
|
64
|
+
- Node.js
|
|
67
65
|
|
|
68
|
-
|
|
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
|
-
|
|
72
|
-
enabled, but without `base-mode-seal`: `default-features = false,
|
|
73
|
-
features = ["algo-all", "base-mode-open", "serde"]`
|
|
68
|
+
## Supported Algorithms
|
|
74
69
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
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
|
-
|
|
80
|
-
|
|
81
|
-
|
|
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
|