Skip to content

Commit ddfa35d

Browse files
jedisct1jedisct1
committed
Add detailed encryption modes page with text-based diagrams
1 parent 00071a3 commit ddfa35d

File tree

3 files changed

+309
-0
lines changed

3 files changed

+309
-0
lines changed

‎www/assets/css/main.css‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -500,6 +500,25 @@ p {
500500
margin-top: 0.25rem;
501501
}
502502

503+
/* Encryption Diagrams */
504+
.diagram-container {
505+
margin: 2rem 0;
506+
overflow-x: auto;
507+
}
508+
509+
.encryption-diagram {
510+
font-family: var(--font-mono);
511+
line-height: 1.2;
512+
white-space: pre;
513+
background-color: #f8f9fa;
514+
border: 1px solid #e2e8f0;
515+
border-radius: 0.5rem;
516+
padding: 1rem;
517+
color: #1e293b;
518+
overflow-x: auto;
519+
font-size: 0.9rem;
520+
}
521+
503522
.max-w-4xl {
504523
max-width: 56rem;
505524
}

‎www/pages/encryption-modes.md‎

Lines changed: 289 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,289 @@
1+
---
2+
layout: page
3+
title: IPCrypt Encryption Modes
4+
description: Detailed explanations of IPCrypt's encryption modes - deterministic, non-deterministic (nd), and extended non-deterministic (ndx).
5+
permalink: /encryption-modes/
6+
---
7+
8+
# IPCrypt Encryption Modes
9+
10+
IPCrypt provides three distinct encryption modes, each designed for specific use cases and security requirements. This page explains each mode in detail, including their operation, properties, and appropriate use cases.
11+
12+
## Overview of Encryption Modes
13+
14+
IPCrypt offers the following encryption modes:
15+
16+
1. **ipcrypt-deterministic**: Format-preserving encryption using AES-128
17+
2. **ipcrypt-nd**: Non-deterministic encryption using KIASU-BC with an 8-byte tweak
18+
3. **ipcrypt-ndx**: Non-deterministic encryption using AES-XTS with a 16-byte tweak
19+
20+
Each mode has different characteristics in terms of format preservation, correlation protection, and output size.
21+
22+
## ipcrypt-deterministic Mode
23+
24+
### How It Works
25+
26+
The deterministic mode uses AES-128 as a single-block operation to encrypt IP addresses while preserving their format.
27+
28+
<div class="diagram-container">
29+
<pre class="encryption-diagram">
30+
+----------------+ +----------------+ +----------------+
31+
| | | | | |
32+
| IP Address |---->| Convert to |---->| AES-128 |
33+
| (192.168.1.1) | | 16-byte form | | Encryption |
34+
| | | | | |
35+
+----------------+ +----------------+ +----------------+
36+
|
37+
+----------------+ |
38+
| | |
39+
| 16-byte Key |------+
40+
| |
41+
+----------------+
42+
|
43+
v
44+
+----------------+ +----------------+
45+
| | | |
46+
| Encrypted |<----| Convert back |
47+
| IP Address | | to IP format |
48+
| | | |
49+
+----------------+ +----------------+
50+
</pre>
51+
</div>
52+
53+
### Process Flow
54+
55+
1. **Input Preparation**: The IP address (IPv4 or IPv6) is converted to a standard 16-byte representation
56+
2. **Encryption**: The 16-byte representation is encrypted using AES-128 with the provided key
57+
3. **Output Formatting**: The encrypted result is converted back to an IP address format
58+
59+
### Key Properties
60+
61+
- **Format Preservation**: The output maintains the IP address format
62+
- **Deterministic**: The same input always produces the same output with a given key
63+
- **Invertible**: The original IP address can be recovered with the key
64+
- **Uniform**: Both IPv4 and IPv6 addresses are handled consistently
65+
66+
### Use Cases
67+
68+
- **Logging**: When you need to correlate log entries by IP address
69+
- **Rate Limiting**: When you need to count or limit requests by IP
70+
- **Database Indexing**: When you need to query or join on encrypted IP addresses
71+
72+
### Code Example
73+
74+
```python
75+
from ipcrypt import IPCrypt
76+
77+
# Initialize with a 16-byte key
78+
key = bytes.fromhex("000102030405060708090a0b0c0d0e0f")
79+
ipcrypt = IPCrypt(key)
80+
81+
# Encrypt an IPv4 address
82+
ip = "192.168.1.1"
83+
encrypted_ip = ipcrypt.encrypt_deterministic(ip)
84+
print(f"Original IP: {ip}")
85+
print(f"Encrypted IP: {encrypted_ip}")
86+
87+
# Decrypt the IP address
88+
decrypted_ip = ipcrypt.decrypt_deterministic(encrypted_ip)
89+
print(f"Decrypted IP: {decrypted_ip}")
90+
```
91+
92+
## ipcrypt-nd Mode
93+
94+
### How It Works
95+
96+
The non-deterministic (nd) mode uses KIASU-BC, a tweakable block cipher based on AES, with an 8-byte tweak to provide non-deterministic encryption.
97+
98+
<div class="diagram-container">
99+
<pre class="encryption-diagram">
100+
+----------------+ +----------------+ +----------------+
101+
| | | | | |
102+
| IP Address |---->| Convert to |---->| KIASU-BC |
103+
| (192.168.1.1) | | 16-byte form | | Encryption |
104+
| | | | | |
105+
+----------------+ +----------------+ +----------------+
106+
|
107+
+----------------+ |
108+
| | |
109+
| 16-byte Key |------+
110+
| |
111+
+----------------+
112+
|
113+
+----------------+ |
114+
| | |
115+
| 8-byte Tweak |------+
116+
| (random) |
117+
+----------------+
118+
|
119+
v
120+
+----------------+
121+
| |
122+
| Encrypted |
123+
| 24-byte value |
124+
| (tweak+cipher) |
125+
+----------------+
126+
</pre>
127+
</div>
128+
129+
### Process Flow
130+
131+
1. **Input Preparation**: The IP address is converted to a 16-byte representation
132+
2. **Tweak Generation**: An 8-byte random tweak is generated
133+
3. **Encryption**: The 16-byte representation is encrypted using KIASU-BC with the key and tweak
134+
4. **Output Formatting**: The tweak and encrypted result are combined to form a 24-byte output
135+
136+
### Key Properties
137+
138+
- **Non-Deterministic**: Different encryptions of the same IP address produce different outputs
139+
- **Correlation Protection**: Prevents linking different encrypted versions of the same IP
140+
- **Larger Output**: Produces a 24-byte output that is not in IP address format
141+
- **Tweak-Dependent**: Decryption requires both the key and the original tweak
142+
143+
### Use Cases
144+
145+
- **Data Sharing**: When sharing data with third parties and correlation protection is important
146+
- **Long-term Storage**: When data will be stored for extended periods
147+
- **Privacy-Critical Applications**: When maximum privacy protection is required
148+
149+
### Code Example
150+
151+
```python
152+
from ipcrypt import IPCrypt
153+
import os
154+
155+
# Initialize with a 16-byte key
156+
key = bytes.fromhex("000102030405060708090a0b0c0d0e0f")
157+
ipcrypt = IPCrypt(key)
158+
159+
# Generate a random 8-byte tweak
160+
tweak = os.urandom(8)
161+
162+
# Encrypt an IPv4 address
163+
ip = "192.168.1.1"
164+
encrypted_ip = ipcrypt.encrypt_nd(ip, tweak)
165+
print(f"Original IP: {ip}")
166+
print(f"Encrypted IP: {encrypted_ip}")
167+
168+
# Decrypt the IP address
169+
decrypted_ip = ipcrypt.decrypt_nd(encrypted_ip, tweak)
170+
print(f"Decrypted IP: {decrypted_ip}")
171+
```
172+
173+
## ipcrypt-ndx Mode
174+
175+
### How It Works
176+
177+
The extended non-deterministic (ndx) mode uses AES-XTS, a tweakable block cipher designed for disk encryption, with a 16-byte tweak to provide maximum security.
178+
179+
<div class="diagram-container">
180+
<pre class="encryption-diagram">
181+
+----------------+ +----------------+ +----------------+
182+
| | | | | |
183+
| IP Address |---->| Convert to |---->| AES-XTS |
184+
| (192.168.1.1) | | 16-byte form | | Encryption |
185+
| | | | | |
186+
+----------------+ +----------------+ +----------------+
187+
|
188+
+----------------+ |
189+
| | |
190+
| 16-byte Key |------+
191+
| |
192+
+----------------+
193+
|
194+
+----------------+ |
195+
| | |
196+
| 16-byte Tweak |------+
197+
| (random) |
198+
+----------------+
199+
|
200+
v
201+
+----------------+
202+
| |
203+
| Encrypted |
204+
| 32-byte value |
205+
| (tweak+cipher) |
206+
+----------------+
207+
</pre>
208+
</div>
209+
210+
### Process Flow
211+
212+
1. **Input Preparation**: The IP address is converted to a 16-byte representation
213+
2. **Tweak Generation**: A 16-byte random tweak is generated
214+
3. **Encryption**: The 16-byte representation is encrypted using AES-XTS with the key and tweak
215+
4. **Output Formatting**: The tweak and encrypted result are combined to form a 32-byte output
216+
217+
### Key Properties
218+
219+
- **Maximum Security**: Provides the highest security margin of all modes
220+
- **Non-Deterministic**: Different encryptions of the same IP address produce different outputs
221+
- **Largest Output**: Produces a 32-byte output
222+
- **128-bit Tweak Space**: Uses a full 16-byte tweak for maximum randomness
223+
224+
### Use Cases
225+
226+
- **Highest Security Requirements**: When maximum security is needed
227+
- **Regulatory Compliance**: When strict privacy regulations must be met
228+
- **Sensitive Data Protection**: When protecting highly sensitive information
229+
230+
### Code Example
231+
232+
```python
233+
from ipcrypt import IPCrypt
234+
import os
235+
236+
# Initialize with a 16-byte key
237+
key = bytes.fromhex("000102030405060708090a0b0c0d0e0f")
238+
ipcrypt = IPCrypt(key)
239+
240+
# Generate a random 16-byte tweak
241+
tweak = os.urandom(16)
242+
243+
# Encrypt an IPv4 address
244+
ip = "192.168.1.1"
245+
encrypted_ip = ipcrypt.encrypt_ndx(ip, tweak)
246+
print(f"Original IP: {ip}")
247+
print(f"Encrypted IP: {encrypted_ip}")
248+
249+
# Decrypt the IP address
250+
decrypted_ip = ipcrypt.decrypt_ndx(encrypted_ip, tweak)
251+
print(f"Decrypted IP: {decrypted_ip}")
252+
```
253+
254+
## Comparison of Encryption Modes
255+
256+
| Feature | ipcrypt-deterministic | ipcrypt-nd | ipcrypt-ndx |
257+
| ---------------------- | ---------------------- | ------------ | ---------------------- |
258+
| Underlying Algorithm | AES-128 | KIASU-BC | AES-XTS |
259+
| Format Preservation | Yes | No | No |
260+
| Correlation Protection | No | Yes | Yes |
261+
| Output Size | 16 bytes | 24 bytes | 32 bytes |
262+
| Tweak Size | N/A | 8 bytes | 16 bytes |
263+
| Security Margin | Standard | High | Highest |
264+
| Performance | Fastest | Fast | Moderate |
265+
| Recommended Use Case | Logging, Rate Limiting | Data Sharing | Highest Security Needs |
266+
267+
## Choosing the Right Mode
268+
269+
When selecting an encryption mode, consider the following factors:
270+
271+
1. **Format Requirements**: If you need to maintain the IP address format, use deterministic mode
272+
2. **Correlation Protection**: If preventing correlation is important, use nd or ndx mode
273+
3. **Security Requirements**: For maximum security, use ndx mode
274+
4. **Performance Considerations**: Deterministic mode is fastest, followed by nd and ndx
275+
5. **Storage Constraints**: Consider the different output sizes when storage is limited
276+
277+
For most applications, the deterministic mode provides a good balance of security and usability. However, when privacy concerns are paramount, the non-deterministic modes offer stronger protection against correlation attacks.
278+
279+
## Implementation Considerations
280+
281+
When implementing these encryption modes, keep in mind:
282+
283+
1. **Key Management**: Securely generate and store encryption keys
284+
2. **Tweak Generation**: For nd and ndx modes, use a cryptographically secure random number generator for tweaks
285+
3. **Tweak Storage**: Store tweaks alongside encrypted values for later decryption
286+
4. **Error Handling**: Implement proper error handling for invalid inputs
287+
5. **Testing**: Verify your implementation against the provided test vectors
288+
289+
For more information on implementing these modes, see the [Code Examples](/code-examples/) page.

‎www/pages/resources.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -212,6 +212,7 @@ When implementing IPCrypt, be aware of these security considerations:
212212

213213
### Documentation
214214

215+
- [Encryption Modes]({{ site.baseurl }}/encryption-modes/): Detailed explanations of IPCrypt's encryption modes
215216
- [FAQ]({{ site.baseurl }}/faq/): Answers to frequently asked questions about IPCrypt
216217
- [Glossary]({{ site.baseurl }}/glossary/): Definitions of technical terms related to IPCrypt
217218
- [Code Examples]({{ site.baseurl }}/code-examples/): Sample code in various programming languages

0 commit comments

Comments
 (0)