0
# Data Utilities
1

2
Helper functions for data format conversion, binary operations, memory management, and library information. These utilities handle common operations needed when working with cryptographic data.
3

4
## Capabilities
5

6
### Format Conversion
7

8
Convert between different data representations commonly used in cryptographic applications.
9

10
```javascript { .api }
11
/**
12
 * Converts a UTF-8 string to bytes
13
 * @param str - UTF-8 string to convert
14
 * @returns Uint8Array containing UTF-8 encoded bytes
15
 */
16
function from_string(str);
17

18
/**
19
 * Converts bytes to UTF-8 string
20
 * @param bytes - Uint8Array to convert to string
21
 * @returns UTF-8 decoded string
22
 * @throws TypeError if bytes contain invalid UTF-8
23
 */
24
function to_string(bytes);
25

26
/**
27
 * Converts hexadecimal string to bytes
28
 * @param hexString - Hex string (e.g., "48656c6c6f")
29
 * @returns Uint8Array with decoded bytes
30
 * @throws Error if hex string is invalid
31
 */
32
function from_hex(hexString);
33

34
/**
35
 * Converts bytes to hexadecimal string
36
 * @param bytes - Uint8Array to convert
37
 * @returns Lowercase hex string
38
 */
39
function to_hex(bytes);
40

41
/**
42
 * Converts base64 string to bytes
43
 * @param base64String - Base64 encoded string
44
 * @param variant - Base64 variant (see base64_variants)
45
 * @returns Uint8Array with decoded bytes
46
 */
47
function from_base64(base64String, variant);
48

49
/**
50
 * Converts bytes to base64 string
51
 * @param bytes - Uint8Array to encode
52
 * @param variant - Base64 variant (see base64_variants)
53
 * @returns Base64 encoded string
54
 */
55
function to_base64(bytes, variant);
56
```
57

58
**Usage Examples:**
59

60
```javascript
61
// String conversion
62
const message = "Hello, World!";
63
const messageBytes = sodium.from_string(message);
64
const backToString = sodium.to_string(messageBytes);
65

66
// Hex conversion
67
const key = sodium.from_hex("0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef");
68
const keyHex = sodium.to_hex(key);
69

70
// Base64 conversion
71
const data = sodium.randombytes_buf(32);
72
const base64 = sodium.to_base64(data, sodium.base64_variants.URLSAFE);
73
const decodedData = sodium.from_base64(base64, sodium.base64_variants.URLSAFE);
74
```
75

76
### Binary Operations
77

78
Constant-time operations for secure binary data manipulation.
79

80
```javascript { .api }
81
/**
82
 * Constant-time comparison of two byte arrays
83
 * @param a - First byte array
84
 * @param b - Second byte array  
85
 * @returns -1 if a < b, 0 if a === b, 1 if a > b
86
 * @throws TypeError if arrays have different lengths
87
 */
88
function compare(a, b);
89

90
/**
91
 * Constant-time equality comparison
92
 * @param a - First byte array
93
 * @param b - Second byte array
94
 * @returns true if arrays are equal, false otherwise
95
 * @throws TypeError if arrays have different lengths
96
 */
97
function memcmp(a, b);
98

99
/**
100
 * Increments a byte array as a big-endian integer
101
 * @param bytes - Uint8Array to increment (modified in place)
102
 */
103
function increment(bytes);
104

105
/**
106
 * Adds two byte arrays as big-endian integers
107
 * @param a - First array (modified in place with result)
108
 * @param b - Second array to add
109
 * @throws TypeError if arrays have different lengths
110
 */
111
function add(a, b);
112

113
/**
114
 * Checks if all bytes in array are zero
115
 * @param bytes - Uint8Array to check
116
 * @returns true if all bytes are zero, false otherwise
117
 */
118
function is_zero(bytes);
119
```
120

121
**Usage Examples:**
122

123
```javascript
124
// Secure comparison
125
const hash1 = sodium.crypto_generichash(32, data1);
126
const hash2 = sodium.crypto_generichash(32, data2);
127
const areEqual = sodium.memcmp(hash1, hash2);
128

129
// Increment nonce
130
const nonce = new Uint8Array(24);
131
sodium.increment(nonce); // nonce is now [0,0,0,...,0,1]
132
sodium.increment(nonce); // nonce is now [0,0,0,...,0,2]
133

134
// Add arrays
135
const a = new Uint8Array([255, 255]);
136
const b = new Uint8Array([0, 1]);
137
sodium.add(a, b); // a is now [0, 0] (overflow)
138
```
139

140
### Memory Management
141

142
Secure memory operations for sensitive data handling.
143

144
```javascript { .api }
145
/**
146
 * Securely zeroes out memory
147
 * @param bytes - Uint8Array to zero (modified in place)
148
 */
149
function memzero(bytes);
150

151
/**
152
 * Pads data to a multiple of block size
153
 * @param buffer - Data to pad
154
 * @param blocksize - Block size for padding
155
 * @returns Padded data
156
 */
157
function pad(buffer, blocksize);
158

159
/**
160
 * Removes padding from data
161
 * @param buffer - Padded data
162
 * @param blocksize - Block size used for padding
163
 * @returns Unpadded data
164
 */
165
function unpad(buffer, blocksize);
166
```
167

168
**Usage Examples:**
169

170
```javascript
171
// Secure memory clearing
172
const sensitiveKey = sodium.crypto_secretbox_keygen();
173
// ... use key ...
174
sodium.memzero(sensitiveKey); // Clear from memory
175

176
// Padding for block ciphers
177
const data = sodium.from_string("Hello");
178
const padded = sodium.pad(data, 16); // Pad to 16-byte blocks
179
const unpadded = sodium.unpad(padded, 16); // Remove padding
180
```
181

182
### Base64 Variants
183

184
```javascript { .api }
185
const base64_variants = {
186
  ORIGINAL: 1,           // Standard base64 with padding
187
  ORIGINAL_NO_PADDING: 3, // Standard base64 without padding
188
  URLSAFE: 5,            // URL-safe base64 with padding
189
  URLSAFE_NO_PADDING: 7  // URL-safe base64 without padding (recommended)
190
};
191
```
192

193
### Library Information
194

195
```javascript { .api }
196
/**
197
 * Returns the libsodium version string
198
 * @returns Version string (e.g., "1.0.18")
199
 */
200
function sodium_version_string();
201

202
/**
203
 * Lists all available function names
204
 * @returns Array of function names sorted alphabetically
205
 */
206
function symbols();
207

208
/**
209
 * Returns available output formats
210
 * @returns Array of format names
211
 */
212
function output_formats();
213

214
/**
215
 * Promise that resolves when library is ready to use
216
 */
217
const ready;
218
```
219

220
**Usage Examples:**
221

222
```javascript
223
// Check library version
224
console.log("libsodium version:", sodium.sodium_version_string());
225

226
// List all available functions
227
const allFunctions = sodium.symbols();
228
console.log("Available functions:", allFunctions.length);
229

230
// Wait for library initialization
231
await sodium.ready;
232
console.log("Library is ready!");
233
```
234

235
## Constants
236

237
```javascript { .api }
238
// Version information
239
const SODIUM_LIBRARY_VERSION_MAJOR;
240
const SODIUM_LIBRARY_VERSION_MINOR;
241
const SODIUM_VERSION_STRING;
242

243
// Comparison results
244
const COMPARE_LESS = -1;
245
const COMPARE_EQUAL = 0;
246
const COMPARE_GREATER = 1;
247
```
248

249
## Advanced Usage
250

251
### Custom Output Formats
252

253
Many functions accept an optional output format parameter:
254

255
```javascript
256
// Different output formats for the same operation
257
const key = sodium.crypto_secretbox_keygen();
258

259
const keyHex = sodium.to_hex(key);
260
const keyBase64 = sodium.to_base64(key, sodium.base64_variants.URLSAFE_NO_PADDING);
261
```
262

263
### Error Handling
264

265
```javascript
266
try {
267
  const decoded = sodium.from_hex("invalid_hex_string");
268
} catch (error) {
269
  console.error("Hex decoding failed:", error.message);
270
}
271

272
try {
273
  const decoded = sodium.from_base64("invalid_base64_string");
274
} catch (error) {
275
  console.error("Base64 decoding failed:", error.message);
276
}
277
```
278

279
## Security Considerations
280

281
- **Constant-Time Operations**: Use `compare()` and `memcmp()` for security-sensitive comparisons to prevent timing attacks
282
- **Memory Clearing**: Use `memzero()` to clear sensitive data from memory when no longer needed
283
- **String Encoding**: Be careful with string encodings - use UTF-8 consistently
284
- **Format Validation**: Handle conversion errors appropriately - invalid input will throw exceptions
285
- **Binary Safety**: All binary operations work with Uint8Array - avoid mixing with other array types