0
# libsodium-wrappers-sumo
1

2
The Sodium cryptographic library compiled to pure JavaScript with comprehensive WASM support. This is the "sumo" variant that includes the complete libsodium API with 188 functions across 18 categories, providing high-performance cryptographic operations for both browser and Node.js environments.
3

4
## Package Information
5

6
- **Package Name**: libsodium-wrappers-sumo
7
- **Package Type**: npm
8
- **Version**: 0.7.15
9
- **Language**: JavaScript (with TypeScript definitions)
10
- **Installation**: `npm install libsodium-wrappers-sumo`
11

12
## Core Imports
13

14
The library uses an asynchronous initialization pattern with a `.ready` promise:
15

16
```javascript { .api }
17
import _sodium from 'libsodium-wrappers-sumo';
18

19
// Wait for library initialization
20
await _sodium.ready;
21
const sodium = _sodium;
22

23
// Now all functions are available
24
const key = sodium.crypto_secretbox_keygen();
25
```
26

27
For CommonJS:
28

29
```javascript { .api }
30
const _sodium = require('libsodium-wrappers-sumo');
31

32
(async () => {
33
  await _sodium.ready;
34
  const sodium = _sodium;
35
  // Use sodium functions here
36
})();
37
```
38

39
## Basic Usage
40

41
```javascript
42
import _sodium from 'libsodium-wrappers-sumo';
43

44
await _sodium.ready;
45
const sodium = _sodium;
46

47
// Generate a random key
48
const key = sodium.crypto_secretbox_keygen();
49

50
// Encrypt a message
51
const message = sodium.from_string('Hello, World!');
52
const nonce = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);
53
const ciphertext = sodium.crypto_secretbox_easy(message, nonce, key);
54

55
// Decrypt the message
56
const decrypted = sodium.crypto_secretbox_open_easy(ciphertext, nonce, key);
57
console.log(sodium.to_string(decrypted)); // "Hello, World!"
58
```
59

60
## Architecture
61

62
libsodium-wrappers-sumo is built around several key components:
63

64
- **WebAssembly Core**: High-performance cryptographic operations compiled from C libsodium
65
- **JavaScript Wrappers**: Type-safe API wrappers with automatic memory management
66
- **Utility Functions**: Data conversion and manipulation helpers for seamless integration
67
- **Constant Definitions**: All cryptographic constants and parameters
68
- **Error Handling**: Comprehensive error checking and clear error messages
69

70
The library provides:
71
- **Memory Safety**: Automatic management of cryptographic memory
72
- **Type Consistency**: Standardized Uint8Array inputs/outputs
73
- **Cross-Platform**: Works in browsers, Node.js, and web workers
74
- **Performance**: WASM-based implementation with pure JS fallback
75

76
## Library Constants
77

78
The library provides access to version information and all cryptographic constants:
79

80
```javascript { .api }
81
// Version information
82
const SODIUM_LIBRARY_VERSION_MAJOR: number;
83
const SODIUM_LIBRARY_VERSION_MINOR: number; 
84
const SODIUM_VERSION_STRING: string;
85

86
// Example: crypto_secretbox constants
87
const crypto_secretbox_KEYBYTES: number;     // 32
88
const crypto_secretbox_NONCEBYTES: number;   // 24
89
const crypto_secretbox_MACBYTES: number;     // 16
90
```
91

92
## Capabilities
93

94
### Authenticated Encryption with Associated Data (AEAD)
95

96
High-performance authenticated encryption supporting multiple algorithms including ChaCha20-Poly1305, XChaCha20-Poly1305, AES-256-GCM, and AEGIS variants. Provides both confidentiality and authenticity in a single operation.
97

98
```javascript { .api }
99
// XChaCha20-Poly1305 (recommended for most use cases)
100
const key = sodium.crypto_aead_xchacha20poly1305_ietf_keygen();
101
const nonce = sodium.randombytes_buf(sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES);
102
const ciphertext = sodium.crypto_aead_xchacha20poly1305_ietf_encrypt(
103
  message, additionalData, null, nonce, key
104
);
105

106
// AEGIS-256 (high performance)
107
const key = sodium.crypto_aead_aegis256_keygen();
108
const ciphertext = sodium.crypto_aead_aegis256_encrypt(message, ad, null, nonce, key);
109
```
110

111
[AEAD Documentation](./aead.md)
112

113
### Message Authentication
114

115
HMAC-based message authentication with SHA-256, SHA-512, and SHA-512/256 variants. Provides cryptographic proof of message authenticity and integrity.
116

117
```javascript { .api }
118
// HMAC-SHA256 authentication
119
const key = sodium.crypto_auth_hmacsha256_keygen();
120
const tag = sodium.crypto_auth_hmacsha256(message, key);
121
const isValid = sodium.crypto_auth_hmacsha256_verify(tag, message, key);
122

123
// Generic auth (defaults to HMAC-SHA512/256)
124
const tag = sodium.crypto_auth(message, key);
125
```
126

127
[Message Authentication Documentation](./auth.md)
128

129
### Public-Key Encryption (Box)
130

131
Curve25519-based public-key encryption supporting multiple cipher variants. Enables secure communication between parties with public key infrastructure.
132

133
```javascript { .api }
134
// Generate keypair
135
const { publicKey, privateKey } = sodium.crypto_box_keypair();
136

137
// Encrypt (authenticated encryption)
138
const nonce = sodium.randombytes_buf(sodium.crypto_box_NONCEBYTES);
139
const ciphertext = sodium.crypto_box_easy(message, nonce, recipientPublicKey, senderPrivateKey);
140

141
// Sealed box (anonymous encryption)
142
const sealed = sodium.crypto_box_seal(message, recipientPublicKey);
143
```
144

145
[Public-Key Encryption Documentation](./box.md)
146

147
### Secret-Key Encryption (SecretBox)
148

149
Fast symmetric encryption with XSalsa20 and XChaCha20 stream ciphers combined with Poly1305 authentication. Ideal for encrypting data with shared secrets.
150

151
```javascript { .api }
152
// Generate key
153
const key = sodium.crypto_secretbox_keygen();
154

155
// Encrypt
156
const nonce = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);
157
const ciphertext = sodium.crypto_secretbox_easy(message, nonce, key);
158

159
// Decrypt
160
const plaintext = sodium.crypto_secretbox_open_easy(ciphertext, nonce, key);
161
```
162

163
[Secret-Key Encryption Documentation](./secretbox.md)
164

165
### Digital Signatures
166

167
Ed25519-based digital signatures providing message authentication, integrity, and non-repudiation. Supports both attached and detached signature modes.
168

169
```javascript { .api }
170
// Generate signing keypair
171
const { publicKey, privateKey } = sodium.crypto_sign_keypair();
172

173
// Create detached signature
174
const signature = sodium.crypto_sign_detached(message, privateKey);
175

176
// Verify signature
177
const isValid = sodium.crypto_sign_verify_detached(signature, message, publicKey);
178
```
179

180
[Digital Signatures Documentation](./sign.md)
181

182
### Hashing
183

184
Comprehensive hashing functions including BLAKE2b (generic hash), SHA-256, and SHA-512. Supports both one-shot and streaming operations.
185

186
```javascript { .api }
187
// BLAKE2b generic hash
188
const hash = sodium.crypto_generichash(32, message);
189
const hash_with_key = sodium.crypto_generichash(32, message, key);
190

191
// SHA-256 and SHA-512
192
const sha256 = sodium.crypto_hash_sha256(message);
193
const sha512 = sodium.crypto_hash_sha512(message);
194
```
195

196
[Hashing Documentation](./hash.md)
197

198
### Key Derivation and Exchange
199

200
Key derivation functions (KDF) and key exchange (KX) protocols for generating multiple keys from a master key and establishing shared secrets between parties.
201

202
```javascript { .api }
203
// Key derivation
204
const masterKey = sodium.crypto_kdf_keygen();
205
const subkey = sodium.crypto_kdf_derive_from_key(32, 1, 'context_', masterKey);
206

207
// Key exchange
208
const client = sodium.crypto_kx_keypair();
209
const server = sodium.crypto_kx_keypair();
210
const { sharedRx, sharedTx } = sodium.crypto_kx_client_session_keys(
211
  client.publicKey, client.privateKey, server.publicKey
212
);
213
```
214

215
[Key Derivation and Exchange Documentation](./key-derivation.md)
216

217
### Streaming Operations
218

219
Streaming encryption and stream cipher operations for handling large data efficiently or implementing custom protocols.
220

221
```javascript { .api }
222
// Secret stream (XChaCha20-Poly1305)
223
const key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
224
const { state, header } = sodium.crypto_secretstream_xchacha20poly1305_init_push(key);
225

226
// Stream cipher  
227
const key = sodium.crypto_stream_chacha20_keygen();
228
const stream = sodium.crypto_stream_chacha20(64, key, nonce);
229
```
230

231
[Streaming Operations Documentation](./streaming.md)
232

233
### Utilities and Helpers
234

235
Random number generation, data conversion utilities, memory operations, and various helper functions for cryptographic operations.
236

237
```javascript { .api }
238
// Random generation
239
const randomBytes = sodium.randombytes_buf(32);
240
const randomInt = sodium.randombytes_uniform(100);
241

242
// Data conversion
243
const bytes = sodium.from_string('hello');
244
const hex = sodium.to_hex(bytes);
245
const base64 = sodium.to_base64(bytes);
246

247
// Memory operations
248
const isEqual = sodium.memcmp(buffer1, buffer2);
249
sodium.memzero(sensitiveData);
250
```
251

252
[Utilities Documentation](./utilities.md)