FUND-2062 Updated README file

Author: ragaumon

README.md

@@ -100,6 +100,66 @@ Configuration can be done through:
 
 For more information, visit our [documentation portal](https://dev.oneground.nl).
 
+## Data Protection & Encryption
+
+The Zaken API supports encryption of sensitive personal data (BSN - Burgerservicenummer) stored in the database. This uses two mechanisms:
+
+### HMAC Hashing (for searchable lookups)
+
+BSN values are hashed using HMAC-SHA256 so they can be searched without storing plaintext. Configure the HMAC key via an environment variable on the Zaken container:
+
+```yaml
+# docker-compose.yml (zgw.zaken.webapi service)
+environment:
+  HmacHasher__HmacKey: "<base64-encoded-key-minimum-32-bytes>"
+```
+
+To generate a key:
+
+```bash
+# Linux/macOS
+openssl rand -base64 32
+
+# PowerShell
+[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Maximum 256 }) -as [byte[]])
+```
+
+> **Warning**: The HMAC key is permanent — if you change it, existing hashes become unsearchable. Back it up securely.
+
+### DataProtection Encryption (for reversible encryption at rest)
+
+BSN values are also encrypted using ASP.NET Core DataProtection. Encryption keys are stored in the database (`data_protection.DataProtectionKeys` table). Optionally, these keys can be protected with an X.509 certificate:
+
+```yaml
+# docker-compose.yml (zgw.zaken.webapi service)
+environment:
+  DataProtection__Certificate: "<base64-encoded-pfx>"
+  DataProtection__CertificatePassword: "<pfx-password>"
+```
+
+To generate a self-signed certificate:
+
+```bash
+# Generate cert + key
+openssl req -x509 -newkey rsa:4096 \
+  -keyout dp-key.pem -out dp-cert.pem \
+  -sha256 -days 3650 -nodes \
+  -subj "/CN=OneGround-DataProtection"
+
+# Convert to PFX
+openssl pkcs12 -export \
+  -in dp-cert.pem -inkey dp-key.pem \
+  -out dataprotection.pfx \
+  -passout pass:YourStrongPassword
+
+# Base64 encode
+base64 -w 0 dataprotection.pfx
+```
+
+> **Warning**: If the certificate is lost, all encrypted data in the database becomes permanently unreadable. Always back up the PFX file.
+
+If no certificate is configured, DataProtection keys are stored unencrypted in the database. This is acceptable for development but not recommended for production.
+
 ## Project Structure
 
 - src: source code