Skip to content

Commit 92f542a

Browse files
jedisct1jedisct1
committed
Add libsodium implementation
1 parent 8eb56f3 commit 92f542a

File tree

2 files changed

+274
-0
lines changed

2 files changed

+274
-0
lines changed

‎www/_implementations/libsodium.md‎

Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
1+
---
2+
layout: implementation
3+
title: IPCrypt libsodium Implementation
4+
description: High-performance C implementation of IPCrypt in libsodium, supporting all four encryption modes with hardware-accelerated AES.
5+
permalink: /implementations/libsodium/
6+
language: C
7+
repository: https://github.com/jedisct1/libsodium
8+
package_manager: libsodium
9+
package_url: https://doc.libsodium.org/
10+
examples:
11+
- title: Deterministic Encryption
12+
description: Encrypt an IP address using deterministic mode
13+
code: |
14+
#include <sodium.h>
15+
#include <stdio.h>
16+
17+
int main(void) {
18+
unsigned char key[crypto_ipcrypt_KEYBYTES];
19+
unsigned char ip[16], encrypted_ip[16], decrypted_ip[16];
20+
21+
if (sodium_init() < 0) return 1;
22+
23+
/* Generate a random key */
24+
crypto_ipcrypt_keygen(key);
25+
26+
/* Parse an IPv4 address into a 16-byte representation */
27+
/* 192.0.2.1 -> 0x00000000 0x00000000 0x0000FFFF 0xC0000201 */
28+
memset(ip, 0, 16);
29+
ip[10] = 0xff; ip[11] = 0xff;
30+
ip[12] = 192; ip[13] = 0; ip[14] = 2; ip[15] = 1;
31+
32+
/* Encrypt */
33+
crypto_ipcrypt_encrypt(encrypted_ip, ip, key);
34+
35+
/* Decrypt */
36+
crypto_ipcrypt_decrypt(decrypted_ip, encrypted_ip, key);
37+
}
38+
- title: Non-Deterministic Encryption (ND)
39+
description: Encrypt an IP address using non-deterministic mode with KIASU-BC
40+
code: |
41+
#include <sodium.h>
42+
43+
int main(void) {
44+
unsigned char key[crypto_ipcrypt_KEYBYTES];
45+
unsigned char ip[16];
46+
unsigned char encrypted[crypto_ipcrypt_nd_BYTES]; /* 24 bytes */
47+
unsigned char decrypted_ip[16];
48+
49+
if (sodium_init() < 0) return 1;
50+
51+
crypto_ipcrypt_keygen(key);
52+
53+
memset(ip, 0, 16);
54+
ip[10] = 0xff; ip[11] = 0xff;
55+
ip[12] = 192; ip[13] = 0; ip[14] = 2; ip[15] = 1;
56+
57+
/* Encrypt (tweak is generated automatically) */
58+
crypto_ipcrypt_nd_encrypt(encrypted, ip, key);
59+
60+
/* Decrypt */
61+
crypto_ipcrypt_nd_decrypt(decrypted_ip, encrypted, key);
62+
}
63+
- title: Non-Deterministic Extended Encryption (NDX)
64+
description: Encrypt an IP address using non-deterministic extended mode with AES-XTS
65+
code: |
66+
#include <sodium.h>
67+
68+
int main(void) {
69+
unsigned char key[crypto_ipcrypt_ndx_KEYBYTES]; /* 32 bytes */
70+
unsigned char ip[16];
71+
unsigned char encrypted[crypto_ipcrypt_ndx_BYTES]; /* 32 bytes */
72+
unsigned char decrypted_ip[16];
73+
74+
if (sodium_init() < 0) return 1;
75+
76+
crypto_ipcrypt_ndx_keygen(key);
77+
78+
memset(ip, 0, 16);
79+
ip[10] = 0xff; ip[11] = 0xff;
80+
ip[12] = 192; ip[13] = 0; ip[14] = 2; ip[15] = 1;
81+
82+
/* Encrypt (tweak is generated automatically) */
83+
crypto_ipcrypt_ndx_encrypt(encrypted, ip, key);
84+
85+
/* Decrypt */
86+
crypto_ipcrypt_ndx_decrypt(decrypted_ip, encrypted, key);
87+
}
88+
---
89+
90+
## IPCrypt libsodium Implementation
91+
92+
[libsodium](https://libsodium.org) includes a high-performance, production-ready implementation of IPCrypt. It supports all four encryption modes and leverages hardware AES instructions (AES-NI / ARMv8 Crypto Extensions) when available.
93+
94+
## Installation
95+
96+
libsodium is available on all major platforms:
97+
98+
```bash
99+
# macOS
100+
brew install libsodium
101+
102+
# Debian / Ubuntu
103+
apt install libsodium-dev
104+
105+
# Fedora / RHEL
106+
dnf install libsodium-devel
107+
108+
# From source
109+
git clone https://github.com/jedisct1/libsodium.git
110+
cd libsodium
111+
./configure && make && make install
112+
```
113+
114+
## Requirements
115+
116+
- libsodium 1.0.21 or higher
117+
- A C compiler (gcc, clang, MSVC)
118+
119+
## Usage
120+
121+
The libsodium implementation provides a simple C API for all four encryption modes. IP addresses are represented as 16-byte arrays (IPv4-mapped IPv6 format).
122+
123+
### Deterministic Encryption
124+
125+
```c
126+
#include <sodium.h>
127+
128+
unsigned char key[crypto_ipcrypt_KEYBYTES];
129+
unsigned char ip[16], encrypted_ip[16], decrypted_ip[16];
130+
131+
crypto_ipcrypt_keygen(key);
132+
133+
crypto_ipcrypt_encrypt(encrypted_ip, ip, key);
134+
crypto_ipcrypt_decrypt(decrypted_ip, encrypted_ip, key);
135+
```
136+
137+
### Non-Deterministic Encryption (ND)
138+
139+
```c
140+
#include <sodium.h>
141+
142+
unsigned char key[crypto_ipcrypt_KEYBYTES];
143+
unsigned char ip[16];
144+
unsigned char encrypted[crypto_ipcrypt_nd_BYTES]; /* 24 bytes: 8-byte tweak + 16-byte ciphertext */
145+
unsigned char decrypted_ip[16];
146+
147+
crypto_ipcrypt_keygen(key);
148+
149+
crypto_ipcrypt_nd_encrypt(encrypted, ip, key);
150+
crypto_ipcrypt_nd_decrypt(decrypted_ip, encrypted, key);
151+
```
152+
153+
### Non-Deterministic Extended Encryption (NDX)
154+
155+
```c
156+
#include <sodium.h>
157+
158+
unsigned char key[crypto_ipcrypt_ndx_KEYBYTES]; /* 32 bytes */
159+
unsigned char ip[16];
160+
unsigned char encrypted[crypto_ipcrypt_ndx_BYTES]; /* 32 bytes: 16-byte tweak + 16-byte ciphertext */
161+
unsigned char decrypted_ip[16];
162+
163+
crypto_ipcrypt_ndx_keygen(key);
164+
165+
crypto_ipcrypt_ndx_encrypt(encrypted, ip, key);
166+
crypto_ipcrypt_ndx_decrypt(decrypted_ip, encrypted, key);
167+
```
168+
169+
## API Reference
170+
171+
### Constants
172+
173+
| Constant | Value | Description |
174+
|---|---|---|
175+
| `crypto_ipcrypt_KEYBYTES` | 16 | Key size for deterministic and ND modes |
176+
| `crypto_ipcrypt_INPUTBYTES` | 16 | IP address size (IPv4-mapped IPv6) |
177+
| `crypto_ipcrypt_nd_BYTES` | 24 | ND ciphertext size (8-byte tweak + 16-byte ciphertext) |
178+
| `crypto_ipcrypt_ndx_KEYBYTES` | 32 | Key size for NDX mode |
179+
| `crypto_ipcrypt_ndx_BYTES` | 32 | NDX ciphertext size (16-byte tweak + 16-byte ciphertext) |
180+
181+
### Deterministic Encryption
182+
183+
```c
184+
void crypto_ipcrypt_keygen(unsigned char k[crypto_ipcrypt_KEYBYTES]);
185+
186+
int crypto_ipcrypt_encrypt(unsigned char out[16], const unsigned char in[16],
187+
const unsigned char k[crypto_ipcrypt_KEYBYTES]);
188+
189+
int crypto_ipcrypt_decrypt(unsigned char out[16], const unsigned char in[16],
190+
const unsigned char k[crypto_ipcrypt_KEYBYTES]);
191+
```
192+
193+
### Non-Deterministic Encryption (ND)
194+
195+
```c
196+
int crypto_ipcrypt_nd_encrypt(unsigned char out[crypto_ipcrypt_nd_BYTES],
197+
const unsigned char in[16],
198+
const unsigned char k[crypto_ipcrypt_KEYBYTES]);
199+
200+
int crypto_ipcrypt_nd_decrypt(unsigned char out[16],
201+
const unsigned char in[crypto_ipcrypt_nd_BYTES],
202+
const unsigned char k[crypto_ipcrypt_KEYBYTES]);
203+
```
204+
205+
### Non-Deterministic Extended Encryption (NDX)
206+
207+
```c
208+
void crypto_ipcrypt_ndx_keygen(unsigned char k[crypto_ipcrypt_ndx_KEYBYTES]);
209+
210+
int crypto_ipcrypt_ndx_encrypt(unsigned char out[crypto_ipcrypt_ndx_BYTES],
211+
const unsigned char in[16],
212+
const unsigned char k[crypto_ipcrypt_ndx_KEYBYTES]);
213+
214+
int crypto_ipcrypt_ndx_decrypt(unsigned char out[16],
215+
const unsigned char in[crypto_ipcrypt_ndx_BYTES],
216+
const unsigned char k[crypto_ipcrypt_ndx_KEYBYTES]);
217+
```
218+
219+
## Implementation Details
220+
221+
The libsodium implementation includes:
222+
223+
1. **Hardware Acceleration**: Uses AES-NI on x86/x86_64 and Crypto Extensions on ARMv8 for maximum performance
224+
2. **Constant-Time Operations**: All operations are designed to run in constant time to prevent timing side-channel attacks
225+
3. **Secure Memory**: Keys can be stored in secure memory using `sodium_malloc()` and locked with `sodium_mlock()`
226+
4. **Cross-Platform**: Works on Linux, macOS, Windows, iOS, Android, and WebAssembly
227+
228+
## Supported Features
229+
230+
- IPv4 address encryption/decryption
231+
- IPv6 address encryption/decryption
232+
- Deterministic encryption (AES-128)
233+
- Non-deterministic encryption (KIASU-BC)
234+
- Extended non-deterministic encryption (AES-XTS)
235+
- Hardware-accelerated AES (AES-NI, ARMv8)
236+
- Constant-time implementation
237+
238+
## Compilation
239+
240+
```bash
241+
# Compile with pkg-config
242+
cc -o example example.c $(pkg-config --cflags --libs libsodium)
243+
244+
# Or link directly
245+
cc -o example example.c -lsodium
246+
```
247+
248+
## License
249+
250+
libsodium is licensed under the ISC License.

‎www/pages/implementations.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,19 @@ Below is a comprehensive list of all available IPCrypt implementations. Click on
3535
<a href="https://github.com/jedisct1/ipcrypt2" class="btn btn-primary btn-sm" target="_blank" rel="noopener">GitHub</a>
3636
</p>
3737
</div>
38+
39+
<div class="implementation-card">
40+
<span class="language-badge">C</span>
41+
<h3 class="text-xl font-bold">libsodium</h3>
42+
<p>Production-ready implementation with hardware-accelerated AES.</p>
43+
<p class="text-sm text-gray-600 mt-2">
44+
<span class="text-primary">✓</span> Detailed documentation available
45+
</p>
46+
<p class="mt-4">
47+
<a href="{{ site.baseurl }}/implementations/libsodium/" class="btn btn-primary btn-sm">Documentation</a>
48+
<a href="https://github.com/jedisct1/libsodium" class="btn btn-secondary btn-sm" target="_blank" rel="noopener">GitHub</a>
49+
</p>
50+
</div>
3851

3952
<div class="implementation-card">
4053
<span class="language-badge">Rust</span>
@@ -210,6 +223,17 @@ Below is a comprehensive list of all available IPCrypt implementations. Click on
210223
<td class="py-2 px-4 border text-center">✓</td>
211224
<td class="py-2 px-4 border">ISC</td>
212225
</tr>
226+
<tr>
227+
<td class="py-2 px-4 border">C (libsodium)</td>
228+
<td class="py-2 px-4 border">Native</td>
229+
<td class="py-2 px-4 border text-center">✓</td>
230+
<td class="py-2 px-4 border text-center">✓</td>
231+
<td class="py-2 px-4 border text-center">✓</td>
232+
<td class="py-2 px-4 border text-center">✓</td>
233+
<td class="py-2 px-4 border text-center">✓</td>
234+
<td class="py-2 px-4 border text-center">✓</td>
235+
<td class="py-2 px-4 border">ISC</td>
236+
</tr>
213237
<tr>
214238
<td class="py-2 px-4 border">Rust</td>
215239
<td class="py-2 px-4 border">Bindings</td>

0 commit comments

Comments
 (0)