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
```