Add IP address encryption (crypto_ipcrypt) and bump to libsodium 1.0.22

.github/workflows/test.yml

@@ -4,7 +4,7 @@ on: [pull_request]
 
 jobs:
   test_linux:
-    name: Linux build and tests
+    name: tests
     runs-on: ubuntu-latest
     steps:
       - name: Checkout source code
@@ -25,9 +25,9 @@ jobs:
 
   #     - name: Install dependencies
   #       run: |
-  #         Invoke-WebRequest -URI https://download.libsodium.org/libsodium/releases/libsodium-1.0.18-stable-msvc.zip -OutFile libsodium-1.0.18-stable-msvc.zip
-  #         tar -xf libsodium-1.0.18-stable-msvc.zip
-  #         rm libsodium-1.0.18-stable-msvc.zip
+  #         Invoke-WebRequest -URI https://download.libsodium.org/libsodium/releases/libsodium-1.0.22-stable-msvc.zip -OutFile libsodium-1.0.22-stable-msvc.zip
+  #         tar -xf libsodium-1.0.22-stable-msvc.zip
+  #         rm libsodium-1.0.22-stable-msvc.zip
   #         cp .\libsodium\x64\Release\v143\dynamic\libsodium.dll $env:PGROOT\lib
   #         Invoke-WebRequest -URI https://github.com/theory/pgtap/archive/refs/tags/v1.2.0.zip -OutFile pgtap.zip
   #         tar -xf pgtap.zip

Dockerfile

@@ -23,12 +23,12 @@ RUN curl -s -L https://ftp.postgresql.org/pub/source/v${version}/postgresql-${ve
     cd .. && rm -rf postgresql-${version}
 
 # Build libsodium
-RUN curl -s -L https://github.com/jedisct1/libsodium/releases/download/1.0.20-RELEASE/libsodium-1.0.20.tar.gz | tar zxf - && \
-    cd libsodium-1.0.20 && \
+RUN curl -s -L https://github.com/jedisct1/libsodium/releases/download/1.0.22-RELEASE/libsodium-1.0.22.tar.gz | tar zxf - && \
+    cd libsodium-1.0.22 && \
     ./configure --prefix=/usr/local && \
     make -j$(nproc) && \
     make install && \
-    cd .. && rm -rf libsodium-1.0.20
+    cd .. && rm -rf libsodium-1.0.22
 
 # Build pgTAP (for testing)
 RUN curl -s -L https://github.com/theory/pgtap/archive/v1.2.0.tar.gz | tar zxf - && \

Dockerfile-debug

@@ -15,7 +15,7 @@ RUN git clone --branch REL_${version}_STABLE https://github.com/postgres/postgre
     && make -j 4 && make install
 
 RUN curl -s -L https://github.com/theory/pgtap/archive/v1.1.0.tar.gz | tar zxvf - && cd pgtap-1.1.0 && make && make install
-RUN curl -s -L https://download.libsodium.org/libsodium/releases/libsodium-1.0.18.tar.gz | tar zxvf - && cd libsodium-1.0.18 && ./configure && make check && make install
+RUN curl -s -L https://github.com/jedisct1/libsodium/releases/download/1.0.22-RELEASE/libsodium-1.0.22.tar.gz | tar zxvf - && cd libsodium-1.0.22 && ./configure && make check && make install
 RUN mkdir "/pgsodium"
 WORKDIR "/pgsodium"
 COPY . .

META.json

@@ -2,7 +2,7 @@
     "name": "pgsodium",
     "abstract": "Postgres extension for libsodium functions",
     "description": "pgsodium is a PostgreSQL extension that exposes modern libsodium based cryptographic functions to SQL.",
-    "version": "3.1.9",
+    "version": "3.1.11",
     "maintainer": [
         "Michel Pelletier <pelletier.michel@gmail.com>"
     ],
@@ -13,7 +13,7 @@
             "abstract": "Postgres extension for libsodium functions",
             "file": "src/pgsodium.h",
             "docfile": "README.md",
-            "version": "3.1.9"
+            "version": "3.1.11"
         }
     },
     "prereqs": {

README.md

@@ -1118,6 +1118,56 @@ Example:
 
 [C API Documentation](https://doc.libsodium.org/hashing)
 
+## IP Address Encryption
+
+pgsodium exposes the libsodium `crypto_ipcrypt_*` family, which encrypts and
+anonymizes IP addresses following the
+[ipcrypt-std](https://ipcrypt-std.github.io) specification. Addresses are
+processed as their 16 byte binary form (IPv4 addresses are represented as
+IPv4-mapped IPv6 addresses). The `crypto_ipcrypt_ip2bin()` and
+`crypto_ipcrypt_bin2ip()` helpers convert between text and binary forms:
+
+    SELECT crypto_ipcrypt_ip2bin('192.0.2.1');
+    SELECT crypto_ipcrypt_bin2ip(crypto_ipcrypt_ip2bin('2001:db8::1'));
+
+Four variants are provided, each with a different privacy/utility trade-off:
+
+| Variant | Function prefix | Key | Output | Properties |
+| --- | --- | --- | --- | --- |
+| Deterministic | `crypto_ipcrypt_` | 16 bytes | 16 bytes | Format-preserving. Same input always yields the same output (joinable, but reveals equality). |
+| Prefix-preserving | `crypto_ipcrypt_pfx_` | 32 bytes | 16 bytes | Format-preserving and preserves network-prefix relationships (subnet structure stays visible). |
+| Non-deterministic | `crypto_ipcrypt_nd_` | 16 bytes | 24 bytes | Randomized per call via an 8 byte tweak (KIASU-BC). Unlinkable. |
+| Extended non-deterministic | `crypto_ipcrypt_ndx_` | 32 bytes | 32 bytes | Randomized per call via a 16 byte tweak (AES-XTS). Largest birthday bound. |
+
+For the two format-preserving variants there are `inet` overloads that accept
+and return an `inet`, in addition to the `bytea` forms:
+
+    -- generate a key and prefix-preservingly encrypt an address
+    SELECT crypto_ipcrypt_pfx_encrypt('203.0.113.42'::inet, crypto_ipcrypt_pfx_keygen());
+
+    -- deterministic encryption round-trip on the binary form
+    SELECT crypto_ipcrypt_keygen() detkey \gset
+    SELECT crypto_ipcrypt_decrypt(
+             crypto_ipcrypt_encrypt(crypto_ipcrypt_ip2bin('192.0.2.1'), :'detkey'::bytea),
+             :'detkey'::bytea);
+
+The non-deterministic variants take a caller-supplied tweak (generate one with
+`crypto_ipcrypt_nd_tweakgen()` / `crypto_ipcrypt_ndx_tweakgen()`); the tweak is
+prepended to the ciphertext, so decryption needs only the ciphertext and key:
+
+    SELECT crypto_ipcrypt_nd_keygen() ndkey \gset
+    SELECT crypto_ipcrypt_nd_encrypt(crypto_ipcrypt_ip2bin('192.0.2.1'),
+             crypto_ipcrypt_nd_tweakgen(), :'ndkey'::bytea) ndct \gset
+    SELECT crypto_ipcrypt_nd_decrypt(:'ndct'::bytea, :'ndkey'::bytea);
+
+As with the other primitives, every variant also has server-managed key
+overloads: a `key_id bigint` (plus optional 8 byte `context`) form that derives
+the key from the server root key, and a `key_uuid uuid` form that looks the key
+up in the pgsodium key table. Use `create_key('ipcrypt-det')`,
+`'ipcrypt-pfx'`, `'ipcrypt-nd'` or `'ipcrypt-ndx'` to create managed keys.
+
+[ipcrypt-std specification](https://ipcrypt-std.github.io)
+
 ## Password hashing
 
     SELECT lives_ok($$SELECT crypto_pwhash_saltgen()$$, 'crypto_pwhash_saltgen');

build/windows.md

@@ -1,7 +1,7 @@
 #### Building on Windows
 ---------
 
-- Download [libsodium](https://download.libsodium.org/libsodium/releases/libsodium-1.0.18-stable-msvc.zip) >= 1.018 and unzip
+- Download [libsodium](https://download.libsodium.org/libsodium/releases/libsodium-1.0.22-stable-msvc.zip) >= 1.0.18 and unzip
 - Download and run the [postgresql installer](https://www.postgresql.org/download/windows/)
 - From the `/pgsodium/build` directory, run `msbuild` on `pgsodium.vcxproj`
 	- `msbuild` can be invoked though the *x64 Native Tools Command Prompt for VS 2022*

example/Dockerfile

@@ -3,7 +3,7 @@ FROM postgres:${version}
 ARG version
 
 RUN apt-get update && apt-get install -y make git postgresql-server-dev-${version} curl build-essential libreadline-dev pgxnclient python3-notebook jupyter jupyter-core python3-pip
-RUN curl -s -L https://download.libsodium.org/libsodium/releases/libsodium-1.0.18.tar.gz | tar zxvf - && cd libsodium-1.0.18 && ./configure && make check && make install
+RUN curl -s -L https://github.com/jedisct1/libsodium/releases/download/1.0.22-RELEASE/libsodium-1.0.22.tar.gz | tar zxvf - && cd libsodium-1.0.22 && ./configure && make check && make install
 
 # RUN curl -s -L https://github.com/theory/pgtap/archive/v1.1.0.tar.gz | tar zxvf - && cd pgtap-1.1.0 && make && make install
 # RUN curl -s -L https://gitlab.com/dalibo/postgresql_anonymizer/-/archive/0.6.0/postgresql_anonymizer-0.6.0.tar.gz | tar zxvf - && cd postgresql_anonymizer-0.6.0 && make extension && make install