Data Protection

Data protection settings control encryption and decryption for authentication cookies and antiforgery tokens.

Overview

{
  "DataProtection": {
    "Enabled": true,
    "CustomApplicationName": null,
    "DefaultKeyLifetimeDays": 90,
    "Storage": "Default",
    "FileSystemPath": "./data-protection-keys",
    "GetAllElementsCommand": "select get_data_protection_keys()",
    "StoreElementCommand": "call store_data_protection_keys($1,$2)",
    "EncryptionAlgorithm": null,
    "ValidationAlgorithm": null,
    "KeyEncryption": "None",
    "CertificatePath": null,
    "CertificatePassword": null,
    "DpapiLocalMachine": false
  }
}

Settings Reference

Setting	Type	Default	Description
Enabled	bool	true	Enable data protection.
CustomApplicationName	string	null	Application name for encryption scope. Uses ApplicationName if null. Different names cannot decrypt each other's data.
DefaultKeyLifetimeDays	int	90	Number of days before keys are rotated.
Storage	string	"Default"	Key storage location: "Default", "FileSystem", or "Database".
FileSystemPath	string	"./data-protection-keys"	Path for file system storage.
GetAllElementsCommand	string	"select get_data_protection_keys()"	Database command to retrieve keys. Returns rows with single text column.
StoreElementCommand	string	"call store_data_protection_keys($1,$2)"	Database command to store keys. Receives name and data as text parameters.
EncryptionAlgorithm	string	null	Encryption algorithm. Uses default if null.
ValidationAlgorithm	string	null	Validation algorithm. Uses default if null.
KeyEncryption	string	"None"	Key encryption method: "None", "Certificate", or "Dpapi" (Windows only).
CertificatePath	string	null	Path to X.509 certificate file (.pfx) when using Certificate encryption.
CertificatePassword	string	null	Password for the certificate file (can be null for passwordless certificates).
DpapiLocalMachine	bool	false	When using DPAPI, set to true to protect keys to the local machine instead of current user.

Storage Options

Default Storage

{
  "DataProtection": {
    "Storage": "Default"
  }
}

Uses the platform's default key storage location.

Linux Users

On Linux, Default storage does not persist keys. When keys are lost on restart, encrypted tokens (authentication cookies) will stop working. Linux deployments should use FileSystem or Database storage.

File System Storage

{
  "DataProtection": {
    "Storage": "FileSystem",
    "FileSystemPath": "/var/lib/npgsqlrest/keys"
  }
}

Stores keys in the specified directory.

Docker

When running in Docker, ensure FileSystemPath points to a Docker volume to persist keys across container restarts.

Database Storage

{
  "DataProtection": {
    "Storage": "Database",
    "GetAllElementsCommand": "select get_data_protection_keys()",
    "StoreElementCommand": "call store_data_protection_keys($1,$2)"
  }
}

Stores keys in the PostgreSQL database using custom functions.

Encryption Algorithms

Configure the encryption algorithm for data protection keys:

Value	Description
null	Use default algorithm
AES_128_CBC	AES 128-bit CBC mode
AES_192_CBC	AES 192-bit CBC mode
AES_256_CBC	AES 256-bit CBC mode
AES_128_GCM	AES 128-bit GCM mode
AES_192_GCM	AES 192-bit GCM mode
AES_256_GCM	AES 256-bit GCM mode

{
  "DataProtection": {
    "EncryptionAlgorithm": "AES_256_GCM"
  }
}

Validation Algorithms

Configure the validation algorithm for data protection keys:

Value	Description
null	Use default algorithm
HMACSHA256	HMAC SHA-256
HMACSHA512	HMAC SHA-512

{
  "DataProtection": {
    "ValidationAlgorithm": "HMACSHA512"
  }
}

Application Name Scope

The CustomApplicationName determines the encryption scope. Applications with different names cannot decrypt each other's data:

{
  "DataProtection": {
    "CustomApplicationName": "my-app-production"
  }
}

If null, uses the top-level ApplicationName setting.

Key Encryption Options

Data protection keys can be encrypted at rest using X.509 certificates or Windows DPAPI for additional security.

No Encryption (Default)

{
  "DataProtection": {
    "KeyEncryption": "None"
  }
}

Keys are stored without additional encryption at rest.

Certificate Encryption

{
  "DataProtection": {
    "Enabled": true,
    "Storage": "Database",
    "KeyEncryption": "Certificate",
    "CertificatePath": "/path/to/cert.pfx",
    "CertificatePassword": "${CERT_PASSWORD}"
  }
}

Encrypts keys using an X.509 certificate. The certificate must be a .pfx file containing both the public and private key.

Environment Variables

Use environment variable substitution for the certificate password to avoid storing secrets in configuration files.

DPAPI Encryption (Windows Only)

{
  "DataProtection": {
    "Enabled": true,
    "Storage": "FileSystem",
    "FileSystemPath": "./keys",
    "KeyEncryption": "Dpapi",
    "DpapiLocalMachine": true
  }
}

Uses Windows Data Protection API to encrypt keys. Only available on Windows.

DpapiLocalMachine	Scope
false (default)	Keys are protected to the current user account
true	Keys are protected to the local machine (any user on the machine can decrypt)

Windows Only

DPAPI encryption is only available on Windows. On other platforms, use Certificate encryption instead.

Complete Example

Production configuration with database storage:

{
  "DataProtection": {
    "Enabled": true,
    "CustomApplicationName": null,
    "DefaultKeyLifetimeDays": 90,
    "Storage": "Database",
    "GetAllElementsCommand": "select get_data_protection_keys()",
    "StoreElementCommand": "call store_data_protection_keys($1,$2)",
    "EncryptionAlgorithm": "AES_256_GCM",
    "ValidationAlgorithm": "HMACSHA512"
  }
}

Production configuration with file system storage (Docker):

{
  "DataProtection": {
    "Enabled": true,
    "DefaultKeyLifetimeDays": 90,
    "Storage": "FileSystem",
    "FileSystemPath": "/app/keys"
  }
}

Related

• Comment Annotations Guide - How annotations work
• Configuration Guide - How configuration works

Next Steps

• Authentication - Configure authentication methods
• Server & SSL - Configure HTTPS and Kestrel web server