libsodium_crypto_ipcrypt (libsodium v3.0.1)

IP address encryption (ipcrypt) for pseudonymizing addresses in logs and telemetry. Every mode works on the 16-byte IPv6 representation of an address, in which IPv4 addresses are IPv4-mapped; use libsodium_utils:ip2bin/1 and libsodium_utils:bin2ip/1 to convert between textual addresses and these binaries.

The deterministic mode (encrypt/2) maps an address to another 16-byte address, so equal inputs give equal outputs. The non-deterministic modes add a random tweak and produce longer outputs that hide repeated addresses: nd_encrypt/2 (8-byte tweak, 24-byte output) and ndx_encrypt/2 (16-byte tweak, 32-byte output, a larger tweak space for more encryptions per key). The prefix-preserving mode (pfx_encrypt/2) keeps addresses that share a network prefix sharing an encrypted prefix, and keeps IPv4 addresses IPv4.

Each mode has its own key size and keygen function. Encryption hides addresses but does not authenticate them: decryption never fails.

K = libsodium_crypto_ipcrypt:keygen(),
Ip = libsodium_utils:ip2bin(<<"192.0.2.1">>),
Encrypted = libsodium_crypto_ipcrypt:encrypt(Ip, K),
Encrypted = libsodium_crypto_ipcrypt:encrypt(Ip, K),
<<"192.0.2.1">> = libsodium_utils:bin2ip(libsodium_crypto_ipcrypt:decrypt(Encrypted, K)),
NdK = libsodium_crypto_ipcrypt:nd_keygen(),
Nd = libsodium_crypto_ipcrypt:nd_encrypt(Ip, NdK),
24 = byte_size(Nd),
Ip = libsodium_crypto_ipcrypt:nd_decrypt(Nd, NdK).

Summary

Types

ip()

A crypto_ipcrypt_BYTES (16-byte) binary.

key()

A crypto_ipcrypt_KEYBYTES (16-byte) binary.

nd_ciphertext()

A crypto_ipcrypt_ND_OUTPUTBYTES (24-byte) binary.

nd_key()

A crypto_ipcrypt_ND_KEYBYTES (16-byte) binary.

nd_tweak()

A crypto_ipcrypt_ND_TWEAKBYTES (8-byte) binary.

ndx_ciphertext()

A crypto_ipcrypt_NDX_OUTPUTBYTES (32-byte) binary.

ndx_key()

A crypto_ipcrypt_NDX_KEYBYTES (32-byte) binary.

ndx_tweak()

A crypto_ipcrypt_NDX_TWEAKBYTES (16-byte) binary.

pfx_key()

A crypto_ipcrypt_PFX_KEYBYTES (32-byte) binary.

Functions

bytes()

Return crypto_ipcrypt_bytes(), in bytes.

decrypt(In, K)

Decrypt the bytes/0 byte address In produced by encrypt/2 with the key K.

encrypt(In, K)

Deterministically encrypt the bytes/0 byte address In with the keybytes/0 byte key K, returning another bytes/0 byte address.

keybytes()

Return crypto_ipcrypt_keybytes(), in bytes.

keygen()

Generate a random keybytes/0 byte key for encrypt/2.

nd_decrypt(In, K)

Decrypt the nd_outputbytes/0 byte output In of nd_encrypt/2 with the key K, returning the nd_inputbytes/0 byte address.

nd_encrypt(In, K)

Encrypt the nd_inputbytes/0 byte address In with the nd_keybytes/0 byte key K and a fresh random tweak. Returns nd_outputbytes/0 bytes: the tweak followed by the encrypted address.

nd_encrypt(In, T, K)

Encrypt the nd_inputbytes/0 byte address In with the nd_keybytes/0 byte key K and the nd_tweakbytes/0 byte tweak T. Returns nd_outputbytes/0 bytes: the tweak followed by the encrypted address. The tweak must be random and should not repeat for a key.

nd_inputbytes()

Return crypto_ipcrypt_nd_inputbytes(), in bytes.

nd_keybytes()

Return crypto_ipcrypt_nd_keybytes(), in bytes.

nd_keygen()

Generate a random nd_keybytes/0 byte key for nd_encrypt/2.

nd_outputbytes()

Return crypto_ipcrypt_nd_outputbytes(), in bytes.

nd_tweakbytes()

Return crypto_ipcrypt_nd_tweakbytes(), in bytes.

ndx_decrypt(In, K)

Decrypt the ndx_outputbytes/0 byte output In of ndx_encrypt/2 with the key K, returning the ndx_inputbytes/0 byte address.

ndx_encrypt(In, K)

Encrypt the ndx_inputbytes/0 byte address In with the ndx_keybytes/0 byte key K and a fresh random tweak. Returns ndx_outputbytes/0 bytes: the tweak followed by the encrypted address.

ndx_encrypt(In, T, K)

Encrypt the ndx_inputbytes/0 byte address In with the ndx_keybytes/0 byte key K and the ndx_tweakbytes/0 byte tweak T. Returns ndx_outputbytes/0 bytes: the tweak followed by the encrypted address. The tweak must be random and should not repeat for a key.

ndx_inputbytes()

Return crypto_ipcrypt_ndx_inputbytes(), in bytes.

ndx_keybytes()

Return crypto_ipcrypt_ndx_keybytes(), in bytes.

ndx_keygen()

Generate a random ndx_keybytes/0 byte key for ndx_encrypt/2.

ndx_outputbytes()

Return crypto_ipcrypt_ndx_outputbytes(), in bytes.

ndx_tweakbytes()

Return crypto_ipcrypt_ndx_tweakbytes(), in bytes.

pfx_bytes()

Return crypto_ipcrypt_pfx_bytes(), in bytes.

pfx_decrypt(In, K)

Decrypt the pfx_bytes/0 byte address In produced by pfx_encrypt/2 with the key K.

pfx_encrypt(In, K)

Encrypt the pfx_bytes/0 byte address In with the pfx_keybytes/0 byte key K, preserving prefixes: addresses that share their first bits share the first bits of their encryptions, and IPv4 addresses stay IPv4-mapped.

pfx_keybytes()

Return crypto_ipcrypt_pfx_keybytes(), in bytes.

pfx_keygen()

Generate a random pfx_keybytes/0 byte key for pfx_encrypt/2.