libsodium 0.7.16 → 0.8.0
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/README.md +54 -27
- package/dist/modules/libsodium.js +10 -7
- package/dist/modules-esm/libsodium.mjs +14 -21
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -8,7 +8,7 @@ compiled to WebAssembly and pure JavaScript using
|
|
|
8
8
|
automatically generated wrappers to make it easy to use in web
|
|
9
9
|
applications.
|
|
10
10
|
|
|
11
|
-
The complete library weighs
|
|
11
|
+
The complete library weighs about 310 KB (minified, gzipped, includes pure JS +
|
|
12
12
|
WebAssembly versions) and can run in a web browser as well as server-side.
|
|
13
13
|
|
|
14
14
|
### Compatibility
|
|
@@ -60,37 +60,56 @@ The modules are also available on npm:
|
|
|
60
60
|
### Usage (as a module)
|
|
61
61
|
|
|
62
62
|
Load the `libsodium-wrappers` module. The returned object contains a `.ready`
|
|
63
|
-
property: a promise that must be
|
|
63
|
+
property: a promise that must be resolved before the sodium functions
|
|
64
64
|
can be used.
|
|
65
65
|
|
|
66
66
|
Example:
|
|
67
67
|
|
|
68
68
|
```js
|
|
69
|
-
import
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
69
|
+
import sodium from 'libsodium-wrappers';
|
|
70
|
+
|
|
71
|
+
await sodium.ready;
|
|
72
|
+
|
|
73
|
+
let key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
|
|
74
|
+
|
|
75
|
+
let res = sodium.crypto_secretstream_xchacha20poly1305_init_push(key);
|
|
76
|
+
let [state_out, header] = [res.state, res.header];
|
|
77
|
+
let c1 = sodium.crypto_secretstream_xchacha20poly1305_push(state_out,
|
|
78
|
+
sodium.from_string('message 1'), null,
|
|
79
|
+
sodium.crypto_secretstream_xchacha20poly1305_TAG_MESSAGE);
|
|
80
|
+
let c2 = sodium.crypto_secretstream_xchacha20poly1305_push(state_out,
|
|
81
|
+
sodium.from_string('message 2'), null,
|
|
82
|
+
sodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL);
|
|
83
|
+
|
|
84
|
+
let state_in = sodium.crypto_secretstream_xchacha20poly1305_init_pull(header, key);
|
|
85
|
+
let r1 = sodium.crypto_secretstream_xchacha20poly1305_pull(state_in, c1);
|
|
86
|
+
let [m1, tag1] = [sodium.to_string(r1.message), r1.tag];
|
|
87
|
+
let r2 = sodium.crypto_secretstream_xchacha20poly1305_pull(state_in, c2);
|
|
88
|
+
let [m2, tag2] = [sodium.to_string(r2.message), r2.tag];
|
|
89
|
+
|
|
90
|
+
console.log(m1);
|
|
91
|
+
console.log(m2);
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
**Named exports:** The ESM modules also provide named exports for helper functions:
|
|
95
|
+
|
|
96
|
+
```js
|
|
97
|
+
import { ready, from_hex, to_hex, from_string, to_string } from 'libsodium-wrappers';
|
|
98
|
+
|
|
99
|
+
await ready;
|
|
100
|
+
const bytes = from_hex('deadbeef');
|
|
101
|
+
console.log(to_hex(bytes));
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
**Note:** Cryptographic functions (like `crypto_secretbox_easy`) and constants (like `crypto_secretbox_KEYBYTES`) are dynamically added to the module at runtime after `ready` resolves. They cannot be imported as named exports and must be accessed via the default export:
|
|
105
|
+
|
|
106
|
+
```js
|
|
107
|
+
import sodium from 'libsodium-wrappers';
|
|
108
|
+
|
|
109
|
+
await sodium.ready;
|
|
110
|
+
// Now crypto functions and constants are available on the sodium object
|
|
111
|
+
const key = sodium.crypto_secretbox_keygen();
|
|
112
|
+
const nonce = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);
|
|
94
113
|
```
|
|
95
114
|
|
|
96
115
|
### Usage (in a web browser, via a callback)
|
|
@@ -118,6 +137,14 @@ Example:
|
|
|
118
137
|
<script src="sodium.js" async></script>
|
|
119
138
|
```
|
|
120
139
|
|
|
140
|
+
**Important:** If you inline the library directly into your HTML (rather than loading it from a separate file), make sure your page declares UTF-8 encoding:
|
|
141
|
+
|
|
142
|
+
```html
|
|
143
|
+
<meta charset="utf-8">
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Without this, browsers may corrupt the embedded WebAssembly binary data during HTML parsing, leading to errors like "failed to match magic number" or "HEAPU8 is undefined". Also ensure your server sends the `charset=utf-8` header.
|
|
147
|
+
|
|
121
148
|
## Additional helpers
|
|
122
149
|
|
|
123
150
|
* `from_base64()`, `to_base64()` with an optional second parameter
|