0
# libsodium-wrappers
1
2
libsodium-wrappers is a comprehensive JavaScript cryptographic library that provides wrappers for the Sodium cryptographic library. It offers a complete cryptographic toolkit compiled to WebAssembly and pure JavaScript, enabling secure cryptographic operations in web browsers and Node.js environments with automatic fallback support.
3
4
## Package Information
5
6
- **Package Name**: libsodium-wrappers
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install libsodium-wrappers`
10
11
## Core Imports
12
13
```javascript
14
// Wait for the library to be ready before use
15
const sodium = require('libsodium-wrappers');
16
await sodium.ready;
17
```
18
19
For ES modules:
20
21
```javascript
22
import sodium from 'libsodium-wrappers';
23
await sodium.ready;
24
```
25
26
## Basic Usage
27
28
```javascript
29
const sodium = require('libsodium-wrappers');
30
await sodium.ready;
31
32
// Generate a key for secret-key encryption
33
const key = sodium.crypto_secretbox_keygen();
34
const nonce = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);
35
36
// Encrypt a message
37
const message = sodium.from_string('Hello, World!');
38
const ciphertext = sodium.crypto_secretbox_easy(message, nonce, key);
39
40
// Decrypt the message
41
const decrypted = sodium.crypto_secretbox_open_easy(ciphertext, nonce, key);
42
const plaintextString = sodium.to_string(decrypted);
43
console.log(plaintextString); // "Hello, World!"
44
```
45
46
## Architecture
47
48
libsodium-wrappers is built around several key components:
49
50
- **WebAssembly Core**: Primary implementation using WebAssembly for performance
51
- **JavaScript Fallback**: Pure JavaScript implementation for compatibility
52
- **Automatic Format Conversion**: Built-in utilities for string/binary/hex/base64 conversion
53
- **Memory Management**: Automatic WebAssembly heap management
54
- **Type Safety**: Consistent Uint8Array interface for all binary data
55
- **Cross-Platform**: Full compatibility across browsers and Node.js environments
56
57
## Capabilities
58
59
### Authenticated Encryption (AEAD)
60
61
Modern authenticated encryption providing both confidentiality and authenticity. Supports multiple cipher suites including ChaCha20-Poly1305 and XChaCha20-Poly1305.
62
63
```javascript { .api }
64
// ChaCha20-Poly1305 IETF (recommended)
65
function crypto_aead_chacha20poly1305_ietf_encrypt(message, additional_data, secret_nonce, public_nonce, key);
66
function crypto_aead_chacha20poly1305_ietf_decrypt(secret_nonce, ciphertext, additional_data, public_nonce, key);
67
function crypto_aead_chacha20poly1305_ietf_keygen();
68
```
69
70
[Authenticated Encryption](./aead.md)
71
72
### Public-Key Encryption
73
74
Elliptic curve-based public-key encryption for secure communication between parties. Uses Curve25519 for key exchange and ChaCha20-Poly1305 for encryption.
75
76
```javascript { .api }
77
function crypto_box_keypair();
78
function crypto_box_easy(message, nonce, publicKey, privateKey);
79
function crypto_box_open_easy(ciphertext, nonce, publicKey, privateKey);
80
function crypto_box_seal(message, publicKey);
81
function crypto_box_seal_open(ciphertext, publicKey, secretKey);
82
```
83
84
[Public-Key Encryption](./public-key-encryption.md)
85
86
### Digital Signatures
87
88
Ed25519-based digital signatures for message authentication and non-repudiation.
89
90
```javascript { .api }
91
function crypto_sign_keypair();
92
function crypto_sign(message, privateKey);
93
function crypto_sign_open(signedMessage, publicKey);
94
function crypto_sign_detached(message, privateKey);
95
function crypto_sign_verify_detached(signature, message, publicKey);
96
```
97
98
[Digital Signatures](./digital-signatures.md)
99
100
### Secret-Key Encryption
101
102
Fast symmetric encryption for encrypting data with a shared secret key. Uses XSalsa20 stream cipher with Poly1305 authentication.
103
104
```javascript { .api }
105
function crypto_secretbox_keygen();
106
function crypto_secretbox_easy(message, nonce, key);
107
function crypto_secretbox_open_easy(ciphertext, nonce, key);
108
```
109
110
[Secret-Key Encryption](./secret-key-encryption.md)
111
112
### Hashing and Key Derivation
113
114
Cryptographic hash functions and key derivation functions for data integrity and key management.
115
116
```javascript { .api }
117
// Generic hash (BLAKE2b)
118
function crypto_generichash(hash_length, message, key);
119
120
// Key derivation
121
function crypto_kdf_derive_from_key(subkey_len, subkey_id, ctx, key);
122
function crypto_kdf_keygen();
123
124
// Standard hashes
125
function crypto_hash(message); // SHA-512
126
function crypto_hash_sha256(message);
127
```
128
129
[Hashing and Key Derivation](./hashing.md)
130
131
### Message Authentication
132
133
MAC (Message Authentication Code) functions for verifying message integrity and authenticity.
134
135
```javascript { .api }
136
function crypto_auth(message, key);
137
function crypto_auth_verify(tag, message, key);
138
function crypto_auth_keygen();
139
```
140
141
[Message Authentication](./authentication.md)
142
143
### Password Hashing
144
145
Secure password hashing using Argon2 and Scrypt algorithms, designed to be resistant to brute-force attacks.
146
147
```javascript { .api }
148
function crypto_pwhash_str(password, opsLimit, memLimit);
149
function crypto_pwhash_str_verify(hashed_password, password);
150
function crypto_pwhash_str_needs_rehash(hashed_password, opsLimit, memLimit);
151
```
152
153
[Password Hashing](./password-hashing.md)
154
155
### Key Exchange
156
157
Secure key exchange protocols for establishing shared secrets between parties.
158
159
```javascript { .api }
160
function crypto_kx_keypair();
161
function crypto_kx_client_session_keys(clientPublicKey, clientSecretKey, serverPublicKey);
162
function crypto_kx_server_session_keys(serverPublicKey, serverSecretKey, clientPublicKey);
163
```
164
165
[Key Exchange](./key-exchange.md)
166
167
### Random Number Generation
168
169
Cryptographically secure random number generation for keys, nonces, and other security-critical values.
170
171
```javascript { .api }
172
function randombytes_buf(length);
173
function randombytes_uniform(upper_bound);
174
function randombytes_random();
175
```
176
177
[Random Number Generation](./random.md)
178
179
### Stream Ciphers
180
181
Fast encryption without authentication for performance-critical applications and custom protocol implementations.
182
183
```javascript { .api }
184
function crypto_stream_chacha20_keygen();
185
function crypto_stream_chacha20_xor(input_message, nonce, key);
186
function crypto_stream_xchacha20_keygen();
187
function crypto_stream_xchacha20_xor(input_message, nonce, key);
188
```
189
190
[Stream Ciphers](./stream-ciphers.md)
191
192
### Advanced Cryptographic Operations
193
194
Low-level elliptic curve operations and core primitives for advanced cryptographic protocols and zero-knowledge proofs.
195
196
```javascript { .api }
197
function crypto_core_ed25519_add(p, q);
198
function crypto_core_ed25519_scalar_random();
199
function crypto_core_ristretto255_add(p, q);
200
function crypto_core_hchacha20(input, key, constant);
201
```
202
203
[Advanced Cryptographic Operations](./advanced-cryptography.md)
204
205
### Data Utilities
206
207
Helper functions for data format conversion, binary operations, and memory management.
208
209
```javascript { .api }
210
// Format conversion
211
function from_string(str);
212
function to_string(bytes);
213
function from_hex(hexString);
214
function to_hex(bytes);
215
function from_base64(base64String, variant);
216
function to_base64(bytes, variant);
217
218
// Binary operations
219
function compare(a, b);
220
function memcmp(a, b);
221
function increment(bytes);
222
function add(a, b);
223
```
224
225
[Data Utilities](./utilities.md)
226
227
## Global Constants
228
229
The library exposes numerous constants for buffer sizes, algorithm parameters, and configuration values. All constants follow the pattern `crypto_[algorithm]_[PARAMETER]`.
230
231
```javascript { .api }
232
// Example constants
233
const crypto_secretbox_KEYBYTES; // 32
234
const crypto_secretbox_NONCEBYTES; // 24
235
const crypto_box_PUBLICKEYBYTES; // 32
236
const crypto_sign_BYTES; // 64
237
const crypto_generichash_BYTES; // 32
238
```
239
240
## Initialization
241
242
The library must be initialized before use:
243
244
```javascript
245
const sodium = require('libsodium-wrappers');
246
247
// Wait for WebAssembly module to load
248
await sodium.ready;
249
250
// Now you can use all cryptographic functions
251
const key = sodium.crypto_secretbox_keygen();
252
```
253
254
## Error Handling
255
256
Functions throw JavaScript Error objects for invalid inputs, cryptographic failures, or initialization problems:
257
258
```javascript
259
try {
260
const result = sodium.crypto_secretbox_open_easy(ciphertext, nonce, wrongkey);
261
} catch (error) {
262
console.error('Decryption failed:', error.message);
263
// Handle decryption failure
264
}
265
```