Skip to content

Commit 7621fda

Browse files
alterstepjedisct1
alterstep
authored and
jedisct1
committed
docs(vrl): add documentation for IPCrypt functions
Add documentation for the new `encrypt_ip` and `decrypt_ip` VRL functions that implement format-preserving encryption for IP addresses. These functions support two modes: - AES128: Scrambles entire IP address using AES-128 encryption - PFX: Prefix-preserving mode that maintains network hierarchy The functions implement the `ipcrypt-deterministic` and `ipcrypt-pfx` algorithms from the IPCrypt specification. Related PR: vectordotdev/vrl#1506
1 parent 5671d44 commit 7621fda

File tree

2 files changed

+173
-0
lines changed

2 files changed

+173
-0
lines changed

‎website/cue/reference/remap/functions/decrypt_ip.cue‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
package metadata
2+
3+
remap: functions: decrypt_ip: {
4+
category: "IP"
5+
description: """
6+
Decrypts an IP address that was previously encrypted, restoring the original IP address.
7+
8+
Supported Modes:
9+
10+
* AES128 - Decrypts an IP address that was scrambled using AES-128 encryption. Can transform between IPv4 and IPv6.
11+
* PFX (Prefix-preserving) - Decrypts an IP address that was encrypted with prefix-preserving mode, where network hierarchy was maintained.
12+
"""
13+
notices: [
14+
"""
15+
The `aes128` mode implements the `ipcrypt-deterministic` algorithm from the IPCrypt specification, while the `pfx` mode implements the `ipcrypt-pfx` algorithm. This function reverses the encryption performed by `encrypt_ip` - the same key and algorithm that were used for encryption must be used for decryption.
16+
""",
17+
]
18+
19+
arguments: [
20+
{
21+
name: "ip"
22+
description: "The encrypted IP address to decrypt (v4 or v6)."
23+
required: true
24+
type: ["string"]
25+
},
26+
{
27+
name: "key"
28+
description: "The decryption key in raw bytes (not encoded). Must be the same key that was used for encryption. For AES128 mode, the key must be exactly 16 bytes. For PFX mode, the key must be exactly 32 bytes."
29+
required: true
30+
type: ["string"]
31+
},
32+
{
33+
name: "mode"
34+
description: "The decryption mode to use. Must match the mode used for encryption: either `aes128` or `pfx`."
35+
required: true
36+
type: ["string"]
37+
},
38+
]
39+
internal_failure_reasons: [
40+
"`ip` is not a valid IP address.",
41+
"`mode` is not a supported mode (must be `aes128` or `pfx`).",
42+
"`key` length does not match the requirements for the specified mode (16 bytes for `aes128`, 32 bytes for `pfx`).",
43+
]
44+
return: types: ["string"]
45+
46+
examples: [
47+
{
48+
title: "Decrypt IPv4 address with AES128"
49+
source: #"""
50+
decrypted_ip = decrypt_ip!("72b9:a747:f2e9:72af:76ca:5866:6dcf:c3b0", "sixteen byte key", "aes128")
51+
decrypted_ip
52+
"""#
53+
return: "192.168.1.1"
54+
},
55+
{
56+
title: "Decrypt IPv6 address with AES128"
57+
source: #"""
58+
decrypted_ip = decrypt_ip!("d09e:a5ea:585a:2547:dc6d:65ea:d9f1:d09d", "sixteen byte key", "aes128")
59+
decrypted_ip
60+
"""#
61+
return: "2001:db8::1"
62+
},
63+
{
64+
title: "Decrypt IPv4 address with prefix-preserving mode"
65+
source: #"""
66+
decrypted_ip = decrypt_ip!("b51c:3c43:4e89:819e:64ce:225f:d6d1:bf01", "thirty-two bytes key for pfx use", "pfx")
67+
decrypted_ip
68+
"""#
69+
return: "192.168.1.1"
70+
},
71+
{
72+
title: "Decrypt IPv6 address with prefix-preserving mode"
73+
source: #"""
74+
decrypted_ip = decrypt_ip!("88bd:d2bf:8865:8c4d:84b:44f6:6077:72c9", "thirty-two bytes key for ipv6pfx", "pfx")
75+
decrypted_ip
76+
"""#
77+
return: "2001:db8::1"
78+
},
79+
{
80+
title: "Round-trip encryption and decryption"
81+
source: #"""
82+
original_ip = "192.168.1.100"
83+
key = "sixteen byte key"
84+
85+
encrypted = encrypt_ip!(original_ip, key, "aes128")
86+
decrypted = decrypt_ip!(encrypted, key, "aes128")
87+
88+
decrypted == original_ip
89+
"""#
90+
return: true
91+
},
92+
]
93+
}

‎website/cue/reference/remap/functions/encrypt_ip.cue‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
package metadata
2+
3+
remap: functions: encrypt_ip: {
4+
category: "IP"
5+
description: """
6+
Encrypts an IP address, transforming it into a different valid IP address.
7+
8+
Supported Modes:
9+
10+
* AES128 - Scrambles the entire IP address using AES-128 encryption. Can transform between IPv4 and IPv6.
11+
* PFX (Prefix-preserving) - Maintains network hierarchy by ensuring that IP addresses within the same network are encrypted to addresses that also share a common network. This preserves prefix relationships while providing confidentiality.
12+
"""
13+
notices: [
14+
"""
15+
The `aes128` mode implements the `ipcrypt-deterministic` algorithm from the IPCrypt specification, while the `pfx` mode implements the `ipcrypt-pfx` algorithm. Both modes provide deterministic encryption where the same input IP address encrypted with the same key will always produce the same encrypted output.
16+
""",
17+
]
18+
19+
arguments: [
20+
{
21+
name: "ip"
22+
description: "The IP address to encrypt (v4 or v6)."
23+
required: true
24+
type: ["string"]
25+
},
26+
{
27+
name: "key"
28+
description: "The encryption key in raw bytes (not encoded). For AES128 mode, the key must be exactly 16 bytes. For PFX mode, the key must be exactly 32 bytes."
29+
required: true
30+
type: ["string"]
31+
},
32+
{
33+
name: "mode"
34+
description: "The encryption mode to use. Must be either `aes128` or `pfx`."
35+
required: true
36+
type: ["string"]
37+
},
38+
]
39+
internal_failure_reasons: [
40+
"`ip` is not a valid IP address.",
41+
"`mode` is not a supported mode (must be `aes128` or `pfx`).",
42+
"`key` length does not match the requirements for the specified mode (16 bytes for `aes128`, 32 bytes for `pfx`).",
43+
]
44+
return: types: ["string"]
45+
46+
examples: [
47+
{
48+
title: "Encrypt IPv4 address with AES128"
49+
source: #"""
50+
encrypted_ip = encrypt_ip!("192.168.1.1", "sixteen byte key", "aes128")
51+
encrypted_ip
52+
"""#
53+
return: "72b9:a747:f2e9:72af:76ca:5866:6dcf:c3b0"
54+
},
55+
{
56+
title: "Encrypt IPv6 address with AES128"
57+
source: #"""
58+
encrypted_ip = encrypt_ip!("2001:db8::1", "sixteen byte key", "aes128")
59+
encrypted_ip
60+
"""#
61+
return: "d09e:a5ea:585a:2547:dc6d:65ea:d9f1:d09d"
62+
},
63+
{
64+
title: "Encrypt IPv4 address with prefix-preserving mode"
65+
source: #"""
66+
encrypted_ip = encrypt_ip!("192.168.1.1", "thirty-two bytes key for pfx use", "pfx")
67+
encrypted_ip
68+
"""#
69+
return: "b51c:3c43:4e89:819e:64ce:225f:d6d1:bf01"
70+
},
71+
{
72+
title: "Encrypt IPv6 address with prefix-preserving mode"
73+
source: #"""
74+
encrypted_ip = encrypt_ip!("2001:db8::1", "thirty-two bytes key for ipv6pfx", "pfx")
75+
encrypted_ip
76+
"""#
77+
return: "88bd:d2bf:8865:8c4d:84b:44f6:6077:72c9"
78+
},
79+
]
80+
}

0 commit comments

Comments
 (0)