0
# Sodium Native
1

2
Sodium Native provides low-level Node.js bindings for the libsodium cryptographic library. It offers direct access to libsodium's C API for high-performance cryptographic operations with a focus on buffer-based operations and manual memory management.
3

4
## Package Information
5

6
- **Package Name**: sodium-native
7
- **Package Type**: npm
8
- **Language**: JavaScript (with native C++ bindings)
9
- **Installation**: `npm install sodium-native`
10

11
## Core Imports
12

13
```javascript
14
const sodium = require('sodium-native');
15
```
16

17
All functions and constants are available as properties of the sodium module:
18

19
```javascript
20
const { 
21
  crypto_secretbox_easy,
22
  crypto_secretbox_KEYBYTES,
23
  crypto_secretbox_NONCEBYTES,
24
  randombytes_buf
25
} = require('sodium-native');
26
```
27

28
## Basic Usage
29

30
```javascript
31
const sodium = require('sodium-native');
32

33
// Generate random key and nonce
34
const key = sodium.sodium_malloc(sodium.crypto_secretbox_KEYBYTES);
35
const nonce = Buffer.alloc(sodium.crypto_secretbox_NONCEBYTES);
36

37
sodium.randombytes_buf(key);
38
sodium.randombytes_buf(nonce);
39

40
// Encrypt a message
41
const message = Buffer.from('Hello, World!');
42
const ciphertext = Buffer.alloc(message.length + sodium.crypto_secretbox_MACBYTES);
43

44
sodium.crypto_secretbox_easy(ciphertext, message, nonce, key);
45

46
// Decrypt the message
47
const plaintext = Buffer.alloc(ciphertext.length - sodium.crypto_secretbox_MACBYTES);
48
if (sodium.crypto_secretbox_open_easy(plaintext, ciphertext, nonce, key)) {
49
  console.log('Decrypted:', plaintext.toString());
50
}
51

52
// Clean up secure memory
53
sodium.sodium_free(key);
54
```
55

56
## Architecture
57

58
Sodium Native is built around several key principles:
59

60
- **Buffer-based API**: All data types are Buffer objects, requiring manual memory management
61
- **Direct C API mapping**: Functions closely mirror libsodium's C interface for maximum performance
62
- **Secure memory utilities**: Built-in support for secure memory allocation and protection
63
- **Inline operations**: Support for in-place encryption/decryption to minimize memory allocation
64
- **Multi-runtime support**: Compatible with both Node.js and Bare runtime environments
65

66
## Capabilities
67

68
### Memory Management
69

70
Secure memory allocation, protection, and cleanup utilities for handling sensitive cryptographic data.
71

72
```javascript { .api }
73
function sodium_malloc(size: number): Buffer;
74
function sodium_free(buf: Buffer): void;
75
function sodium_memzero(buf: Buffer): void;
76
```
77

78
[Memory Management](./memory.md)
79

80
### Random Number Generation
81

82
Cryptographically secure random number generation for keys, nonces, and other random values.
83

84
```javascript { .api }
85
function randombytes_buf(buffer: Buffer): void;
86
function randombytes_buf_deterministic(buffer: Buffer, seed: Buffer): void;
87
```
88

89
[Random Number Generation](./random.md)
90

91
### Secret Key Encryption
92

93
Symmetric encryption using authenticated encryption schemes for protecting data with shared keys.
94

95
```javascript { .api }
96
function crypto_secretbox_easy(c: Buffer, m: Buffer, n: Buffer, k: Buffer): void;
97
function crypto_secretbox_open_easy(m: Buffer, c: Buffer, n: Buffer, k: Buffer): boolean;
98
```
99

100
[Secret Key Encryption](./secretbox.md)
101

102
### Public Key Encryption
103

104
Asymmetric encryption using Curve25519 elliptic curve cryptography for secure communication between parties.
105

106
```javascript { .api }
107
function crypto_box_keypair(pk: Buffer, sk: Buffer): void;
108
function crypto_box_easy(c: Buffer, m: Buffer, n: Buffer, pk: Buffer, sk: Buffer): void;
109
```
110

111
[Public Key Encryption](./box.md)
112

113
### Digital Signatures
114

115
Ed25519 digital signatures for message authentication and non-repudiation.
116

117
```javascript { .api }
118
function crypto_sign_keypair(pk: Buffer, sk: Buffer): void;
119
function crypto_sign_detached(sig: Buffer, m: Buffer, sk: Buffer): void;
120
function crypto_sign_verify_detached(sig: Buffer, m: Buffer, pk: Buffer): boolean;
121
```
122

123
[Digital Signatures](./sign.md)
124

125
### Hash Functions
126

127
Cryptographic hash functions including BLAKE2b, SHA-256, and SHA-512 for data integrity and key derivation.
128

129
```javascript { .api }
130
function crypto_generichash(output: Buffer, input: Buffer, key?: Buffer): void;
131
function crypto_hash_sha256(out: Buffer, input: Buffer): void;
132
function crypto_hash_sha512(out: Buffer, input: Buffer): void;
133
```
134

135
[Hash Functions](./hash.md)
136

137
### Password Hashing
138

139
Secure password hashing using Argon2 and scrypt for password verification and key derivation.
140

141
```javascript { .api }
142
function crypto_pwhash(
143
  out: Buffer, 
144
  passwd: Buffer, 
145
  salt: Buffer, 
146
  opslimit: number, 
147
  memlimit: number, 
148
  alg: number
149
): void;
150
```
151

152
[Password Hashing](./pwhash.md)
153

154
### Stream Ciphers
155

156
High-performance stream ciphers including ChaCha20, XChaCha20, and Salsa20 for fast encryption.
157

158
```javascript { .api }
159
function crypto_stream_chacha20_xor(c: Buffer, m: Buffer, n: Buffer, k: Buffer): void;
160
function crypto_stream_xchacha20_xor(c: Buffer, m: Buffer, n: Buffer, k: Buffer): void;
161
```
162

163
[Stream Ciphers](./stream.md)
164

165
### Message Authentication
166

167
Message authentication codes (MAC) using HMAC-SHA512 and Poly1305 for data integrity verification.
168

169
```javascript { .api }
170
function crypto_auth(out: Buffer, input: Buffer, k: Buffer): void;
171
function crypto_auth_verify(h: Buffer, input: Buffer, k: Buffer): boolean;
172
```
173

174
[Message Authentication](./auth.md)
175

176
### Key Exchange
177

178
Diffie-Hellman key exchange using X25519 for establishing shared secrets between parties.
179

180
```javascript { .api }
181
function crypto_kx_keypair(pk: Buffer, sk: Buffer): void;
182
function crypto_kx_client_session_keys(
183
  rx: Buffer, 
184
  tx: Buffer, 
185
  clientPk: Buffer, 
186
  clientSk: Buffer, 
187
  serverPk: Buffer
188
): void;
189
```
190

191
[Key Exchange](./kx.md)
192

193
### Elliptic Curve Operations
194

195
Low-level elliptic curve operations on Ed25519 for advanced cryptographic protocols.
196

197
```javascript { .api }
198
function crypto_core_ed25519_add(r: Buffer, p: Buffer, q: Buffer): void;
199
function crypto_core_ed25519_scalar_random(r: Buffer): void;
200
function crypto_scalarmult_ed25519_base(q: Buffer, n: Buffer): void;
201
```
202

203
[Elliptic Curve Operations](./ed25519.md)
204

205
### Secret Streams
206

207
Streaming authenticated encryption using XChaCha20-Poly1305 for encrypting sequences of messages with automatic key rotation.
208

209
```javascript { .api }
210
function crypto_secretstream_xchacha20poly1305_keygen(k: Buffer): void;
211
function crypto_secretstream_xchacha20poly1305_init_push(state: Buffer, header: Buffer, k: Buffer): void;
212
function crypto_secretstream_xchacha20poly1305_push(state: Buffer, c: Buffer, m: Buffer, ad: Buffer | null, tag: number): number;
213
```
214

215
[Secret Streams](./secretstream.md)
216

217
### Authenticated Encryption with Additional Data
218

219
Modern authenticated encryption schemes using ChaCha20-Poly1305 and XChaCha20-Poly1305 for secure encryption with additional data.
220

221
```javascript { .api }
222
function crypto_aead_xchacha20poly1305_ietf_encrypt(c: Buffer, m: Buffer, ad: Buffer | null, nsec: null, npub: Buffer, k: Buffer): number;
223
function crypto_aead_chacha20poly1305_ietf_encrypt(c: Buffer, m: Buffer, ad: Buffer | null, nsec: null, npub: Buffer, k: Buffer): number;
224
```
225

226
[Authenticated Encryption (AEAD)](./aead.md)
227

228
### Key Derivation Functions
229

230
Key derivation functions for generating multiple keys from a single master key with proper domain separation.
231

232
```javascript { .api }
233
function crypto_kdf_keygen(key: Buffer): void;
234
function crypto_kdf_derive_from_key(subkey: Buffer, subkeyId: number, ctx: Buffer, key: Buffer): void;
235
```
236

237
[Key Derivation Functions](./kdf.md)
238

239
### Short Hash Functions
240

241
Fast, non-cryptographic hash function (SipHash-2-4) optimized for hash tables and data structures.
242

243
```javascript { .api }
244
function crypto_shorthash(out: Buffer, input: Buffer, k: Buffer): void;
245
```
246

247
[Short Hash Functions](./shorthash.md)
248

249
## Types
250

251
```javascript { .api }
252
// Buffer type represents a Node.js Buffer object
253
type Buffer = NodeJS.Buffer;
254

255
// Secure Buffer - created with sodium_malloc, has .secure property
256
interface SecureBuffer extends Buffer {
257
  secure: true;
258
}
259

260
// Constants are exported as numbers
261
const crypto_secretbox_KEYBYTES: number;
262
const crypto_secretbox_NONCEBYTES: number;
263
const crypto_secretbox_MACBYTES: number;
264

265
// Algorithm constants for password hashing
266
const crypto_pwhash_ALG_ARGON2I13: number;
267
const crypto_pwhash_ALG_ARGON2ID13: number;
268
const crypto_pwhash_ALG_DEFAULT: number;
269

270
// Stream tags for secret streams
271
const crypto_secretstream_xchacha20poly1305_TAG_MESSAGE: number;
272
const crypto_secretstream_xchacha20poly1305_TAG_PUSH: number;
273
const crypto_secretstream_xchacha20poly1305_TAG_REKEY: number;
274
const crypto_secretstream_xchacha20poly1305_TAG_FINAL: number;
275
```