docs(vrl): add documentation for IPCrypt functions

.github/actions/spelling/allow.txt

@@ -237,6 +237,7 @@ Intenso
 INTERLAKEN
 ionik
 ipallowlist
+ipcrypt
 ipod
 ircd
 Itamar

LICENSE-3rdparty.csv

@@ -339,6 +339,7 @@ io-lifetimes,https://github.com/sunfishcode/io-lifetimes,Apache-2.0 WITH LLVM-ex
 io-uring,https://github.com/tokio-rs/io-uring,MIT OR Apache-2.0,quininer <[email protected]>
 iovec,https://github.com/carllerche/iovec,MIT OR Apache-2.0,Carl Lerche <[email protected]>
 ipconfig,https://github.com/liranringel/ipconfig,MIT OR Apache-2.0,Liran Ringel <[email protected]>
+ipcrypt-rs,https://github.com/jedisct1/rust-ipcrypt2,ISC,Frank Denis <[email protected]>
 ipnet,https://github.com/krisprice/ipnet,MIT OR Apache-2.0,Kris Price <[email protected]>
 ipnetwork,https://github.com/achanda/ipnetwork,MIT OR Apache-2.0,"Abhishek Chanda <[email protected]>, Linus Färnstrand <[email protected]>"
 is-terminal,https://github.com/sunfishcode/is-terminal,MIT,"softprops <[email protected]>, Dan Gohman <[email protected]>"

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

@@ -0,0 +1,93 @@
+package metadata
+
+remap: functions: decrypt_ip: {
+	category: "IP"
+	description: """
+		Decrypts an IP address that was previously encrypted, restoring the original IP address.
+
+		Supported Modes:
+
+		* AES128 - Decrypts an IP address that was scrambled using AES-128 encryption. Can transform between IPv4 and IPv6.
+		* PFX (Prefix-preserving) - Decrypts an IP address that was encrypted with prefix-preserving mode, where network hierarchy was maintained.
+		"""
+	notices: [
+		"""
+			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.
+			""",
+	]
+
+	arguments: [
+		{
+			name:        "ip"
+			description: "The encrypted IP address to decrypt (v4 or v6)."
+			required:    true
+			type: ["string"]
+		},
+		{
+			name:        "key"
+			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."
+			required:    true
+			type: ["string"]
+		},
+		{
+			name:        "mode"
+			description: "The decryption mode to use. Must match the mode used for encryption: either `aes128` or `pfx`."
+			required:    true
+			type: ["string"]
+		},
+	]
+	internal_failure_reasons: [
+		"`ip` is not a valid IP address.",
+		"`mode` is not a supported mode (must be `aes128` or `pfx`).",
+		"`key` length does not match the requirements for the specified mode (16 bytes for `aes128`, 32 bytes for `pfx`).",
+	]
+	return: types: ["string"]
+
+	examples: [
+		{
+			title: "Decrypt IPv4 address with AES128"
+			source: #"""
+				decrypted_ip = decrypt_ip!("72b9:a747:f2e9:72af:76ca:5866:6dcf:c3b0", "sixteen byte key", "aes128")
+				decrypted_ip
+				"""#
+			return: "192.168.1.1"
+		},
+		{
+			title: "Decrypt IPv6 address with AES128"
+			source: #"""
+				decrypted_ip = decrypt_ip!("d09e:a5ea:585a:2547:dc6d:65ea:d9f1:d09d", "sixteen byte key", "aes128")
+				decrypted_ip
+				"""#
+			return: "2001:db8::1"
+		},
+		{
+			title: "Decrypt IPv4 address with prefix-preserving mode"
+			source: #"""
+				decrypted_ip = decrypt_ip!("b51c:3c43:4e89:819e:64ce:225f:d6d1:bf01", "thirty-two bytes key for pfx use", "pfx")
+				decrypted_ip
+				"""#
+			return: "192.168.1.1"
+		},
+		{
+			title: "Decrypt IPv6 address with prefix-preserving mode"
+			source: #"""
+				decrypted_ip = decrypt_ip!("88bd:d2bf:8865:8c4d:84b:44f6:6077:72c9", "thirty-two bytes key for ipv6pfx", "pfx")
+				decrypted_ip
+				"""#
+			return: "2001:db8::1"
+		},
+		{
+			title: "Round-trip encryption and decryption"
+			source: #"""
+				original_ip = "192.168.1.100"
+				key = "sixteen byte key"
+
+				encrypted = encrypt_ip!(original_ip, key, "aes128")
+				decrypted = decrypt_ip!(encrypted, key, "aes128")
+
+				decrypted == original_ip
+				"""#
+			return: true
+		},
+	]
+}

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

@@ -0,0 +1,80 @@
+package metadata
+
+remap: functions: encrypt_ip: {
+	category: "IP"
+	description: """
+		Encrypts an IP address, transforming it into a different valid IP address.
+
+		Supported Modes:
+
+		* AES128 - Scrambles the entire IP address using AES-128 encryption. Can transform between IPv4 and IPv6.
+		* 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.
+		"""
+	notices: [
+		"""
+			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.
+			""",
+	]
+
+	arguments: [
+		{
+			name:        "ip"
+			description: "The IP address to encrypt (v4 or v6)."
+			required:    true
+			type: ["string"]
+		},
+		{
+			name:        "key"
+			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."
+			required:    true
+			type: ["string"]
+		},
+		{
+			name:        "mode"
+			description: "The encryption mode to use. Must be either `aes128` or `pfx`."
+			required:    true
+			type: ["string"]
+		},
+	]
+	internal_failure_reasons: [
+		"`ip` is not a valid IP address.",
+		"`mode` is not a supported mode (must be `aes128` or `pfx`).",
+		"`key` length does not match the requirements for the specified mode (16 bytes for `aes128`, 32 bytes for `pfx`).",
+	]
+	return: types: ["string"]
+
+	examples: [
+		{
+			title: "Encrypt IPv4 address with AES128"
+			source: #"""
+				encrypted_ip = encrypt_ip!("192.168.1.1", "sixteen byte key", "aes128")
+				encrypted_ip
+				"""#
+			return: "72b9:a747:f2e9:72af:76ca:5866:6dcf:c3b0"
+		},
+		{
+			title: "Encrypt IPv6 address with AES128"
+			source: #"""
+				encrypted_ip = encrypt_ip!("2001:db8::1", "sixteen byte key", "aes128")
+				encrypted_ip
+				"""#
+			return: "d09e:a5ea:585a:2547:dc6d:65ea:d9f1:d09d"
+		},
+		{
+			title: "Encrypt IPv4 address with prefix-preserving mode"
+			source: #"""
+				encrypted_ip = encrypt_ip!("192.168.1.1", "thirty-two bytes key for pfx use", "pfx")
+				encrypted_ip
+				"""#
+			return: "b51c:3c43:4e89:819e:64ce:225f:d6d1:bf01"
+		},
+		{
+			title: "Encrypt IPv6 address with prefix-preserving mode"
+			source: #"""
+				encrypted_ip = encrypt_ip!("2001:db8::1", "thirty-two bytes key for ipv6pfx", "pfx")
+				encrypted_ip
+				"""#
+			return: "88bd:d2bf:8865:8c4d:84b:44f6:6077:72c9"
+		},
+	]
+}