ipcrypt2 0.1.0

IP address obfuscation library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

# ipcrypt2

**ipcrypt2** is a Rust library to enable encryption and decryption of IP addresses (both IPv4 and IPv6).

## Features

- **Deterministic (Format-Preserving) Encryption/Decryption:**  
  Encrypt and decrypt IP addresses in a way that preserves their format. The output remains a valid IP address.

- **Non-Deterministic Encryption/Decryption:**  
  For increased privacy, non-deterministic encryption produces a compact 24-byte array (or its hex string representation) instead of an IP address. This mode uses random tweaks, so the same input will yield different outputs on each encryption.

- **IP Conversion Utilities:**  
  Seamlessly convert between `std::net::IpAddr`, 16-byte binary representations, and IP strings. IPv4 addresses are automatically converted to IPv4‑mapped IPv6 format when needed.

- **WebAssembly Support:**  
  The library is fully compatible with WebAssembly.

## Installation

To use **ipcrypt2** in your project, add it to your `Cargo.toml`:

```toml
[dependencies]
ipcrypt2 = "0.1"  # Replace with the latest version
```

## Usage

Below is an example demonstrating both deterministic (format-preserving) and non-deterministic encryption modes:

```rust
use std::net::{IpAddr, Ipv4Addr};
use ipcrypt2::{Ipcrypt, IPCRYPT_KEYBYTES};

// Create a secret key with the required length.
let key = [0u8; IPCRYPT_KEYBYTES];

// Initialize the ipcrypt2 context.
let ipcrypt = Ipcrypt::new(&key);

// --- Deterministic (Format-Preserving) Mode ---
// Encrypting an IP address preserves its format.
let ip: IpAddr = IpAddr::V4(Ipv4Addr::new(192, 168, 1, 1));
let encrypted_ip = ipcrypt.encrypt_ipaddr(ip)
    .expect("IP encryption failed");
println!("Deterministically Encrypted IP: {}", encrypted_ip);

let decrypted_ip = ipcrypt.decrypt_ipaddr(encrypted_ip)
    .expect("IP decryption failed");
println!("Decrypted IP: {}", decrypted_ip);

// --- Non-Deterministic Mode ---
// Non-deterministic encryption produces a compact 24-byte array (or hex string).
let ip_str = "10.0.0.1";
let nd_encrypted = ipcrypt.nd_encrypt_ip_str(ip_str)
    .expect("Non-deterministic encryption failed");
println!("Non-Deterministically Encrypted IP String: {}", nd_encrypted);

let nd_decrypted = ipcrypt.nd_decrypt_ip_str(&nd_encrypted)
    .expect("Non-deterministic decryption failed");
println!("Non-Deterministically Decrypted IP String: {}", nd_decrypted);
```

## API Overview

The primary interface is provided by the `Ipcrypt` struct, which exposes several functionalities:

### Initialization

- **`Ipcrypt::new(key: &[u8])`**  
  Creates a new instance with a secret key. The key must be exactly `IPCRYPT_KEYBYTES` bytes long.

### Deterministic Methods (Format-Preserving)

- **`encrypt_ip16(&self, ip: &mut [u8; 16])` / `decrypt_ip16(&self, ip: &mut [u8; 16])`**  
  Encrypts and decrypts a 16-byte IP address in-place.

- **`encrypt_ip_str(&self, ip: &str)` / `decrypt_ip_str(&self, encrypted: &str)`**  
  Encrypts and decrypts IP address strings, supporting both IPv4 and IPv6 formats.

- **`encrypt_ipaddr(&self, ip: IpAddr)` / `decrypt_ipaddr(&self, encrypted: IpAddr)`**  
  Encrypts and decrypts `std::net::IpAddr` types. The encrypted output is still a valid IP address, with IPv4 addresses represented in IPv4‑mapped IPv6 format.

### Non-Deterministic Methods

- **`nd_encrypt_ip16(&self, ip: &[u8; 16])` / `nd_decrypt_ip16(&self, ndip: &[u8; IPCRYPT_NDIP_BYTES])`**  
  Encrypts and decrypts 16-byte IP addresses non-deterministically, outputting a 24-byte encrypted array.

- **`nd_encrypt_ip_str(&self, ip: &str)` / `nd_decrypt_ip_str(&self, encrypted: &str)`**  
  Encrypts and decrypts IP address strings in non-deterministic mode. The encrypted value is returned as a hex-encoded string.

- **`nd_encrypt_ipaddr_str(&self, ip: IpAddr)` / `nd_decrypt_ipaddr_str(&self, encrypted: &str)`**  
  Encrypts an `IpAddr` to a non-deterministic hex string and converts it back upon decryption.

### Conversion Utilities

- **`ipaddr_to_ip16(ip: IpAddr)` and `ip16_to_ipaddr(ip16: [u8; 16])`**  
  Convert between `IpAddr` and its 16-byte representation. IPv4 addresses are represented as IPv4‑mapped IPv6 addresses.

- **`str_to_ip16(ip: &str)` and `ip16_to_str(ip16: &[u8; 16])`**  
  Convert between IP address strings and their corresponding 16-byte binary forms.

For detailed API documentation, refer to the inline comments in the source code.

## Contributing

Contributions are welcome! If you encounter any issues or have feature requests, please open an issue or submit a pull request.

## License

This project is distributed under the MIT License. See the [LICENSE](LICENSE) file for more details.