0
# Memory Management
1

2
Secure memory allocation, protection, and cleanup utilities for handling sensitive cryptographic data in sodium-native.
3

4
## Capabilities
5

6
### Secure Memory Allocation
7

8
Allocates secure memory that is protected from being swapped to disk and automatically locked in memory.
9

10
```javascript { .api }
11
/**
12
 * Allocate secure memory buffer
13
 * @param size - Number of bytes to allocate
14
 * @returns SecureBuffer with .secure property set to true
15
 * @throws Error if size is negative
16
 */
17
function sodium_malloc(size: number): SecureBuffer;
18
```
19

20
**Usage Example:**
21

22
```javascript
23
const sodium = require('sodium-native');
24

25
// Allocate secure memory for a secret key
26
const key = sodium.sodium_malloc(32);
27
console.log(key.secure); // true
28

29
// Use the key for cryptographic operations
30
sodium.randombytes_buf(key);
31
```
32

33
### Secure Memory Deallocation
34

35
Safely deallocates secure memory and zeros it before freeing.
36

37
```javascript { .api }
38
/**
39
 * Free secure memory buffer
40
 * @param buf - Buffer to free (must have .secure property)
41
 */
42
function sodium_free(buf: Buffer): void;
43
```
44

45
**Usage Example:**
46

47
```javascript
48
const key = sodium.sodium_malloc(32);
49
// ... use key for cryptographic operations
50
sodium.sodium_free(key); // Memory is zeroed and freed
51
```
52

53
### Memory Zeroing
54

55
Securely zeros memory content to prevent sensitive data from remaining in memory.
56

57
```javascript { .api }
58
/**
59
 * Zero memory buffer content
60
 * @param buf - Buffer to zero
61
 */
62
function sodium_memzero(buf: Buffer): void;
63
```
64

65
### Memory Locking
66

67
Lock memory pages to prevent them from being swapped to disk.
68

69
```javascript { .api }
70
/**
71
 * Lock memory buffer to prevent swapping
72
 * @param buf - Buffer to lock
73
 * @throws Error if memory lock fails
74
 */
75
function sodium_mlock(buf: Buffer): void;
76

77
/**
78
 * Unlock previously locked memory buffer
79
 * @param buf - Buffer to unlock
80
 * @throws Error if memory unlock fails
81
 */
82
function sodium_munlock(buf: Buffer): void;
83
```
84

85
### Memory Protection
86

87
Control read/write access to memory regions for additional security.
88

89
```javascript { .api }
90
/**
91
 * Make buffer inaccessible (no read/write access)
92
 * @param buf - Buffer to protect
93
 * @throws Error if protection fails
94
 */
95
function sodium_mprotect_noaccess(buf: Buffer): void;
96

97
/**
98
 * Make buffer read-only
99
 * @param buf - Buffer to make read-only
100
 * @throws Error if protection fails
101
 */
102
function sodium_mprotect_readonly(buf: Buffer): void;
103

104
/**
105
 * Make buffer read-write accessible
106
 * @param buf - Buffer to make read-write
107
 * @throws Error if protection fails
108
 */
109
function sodium_mprotect_readwrite(buf: Buffer): void;
110
```
111

112
**Usage Example:**
113

114
```javascript
115
const sodium = require('sodium-native');
116

117
// Allocate and use secure memory
118
const secret = sodium.sodium_malloc(32);
119
sodium.randombytes_buf(secret);
120

121
// Make read-only while not being modified
122
sodium.sodium_mprotect_readonly(secret);
123

124
// Later, make writable again if needed
125
sodium.sodium_mprotect_readwrite(secret);
126

127
// Clean up
128
sodium.sodium_free(secret);
129
```
130

131
## Types
132

133
```javascript { .api }
134
interface SecureBuffer extends Buffer {
135
  secure: true;
136
}
137
```