Skip to content

Data protection

To be able to run behind a load balancer the key crypting cookies and anti-CSRF mechanism must be share by all servers or the load balancer must use a session affinity mechanism.
The DataProtectionOptions section configure the ASP.NET Core Data Protection :

minimum configuration sample

"DataProtectionOptions": {
  "StorageKind": "EntityFramework"
}

full configuration sample

"DataProtectionOptions": {
  "StorageKind": "FileSytem",
  "StorageConnectionString": "C:\\data-protection-keys",
  "KeyProtectionOptions": {
    "KeyProtectionKind": "X509",
    "X509CertificatePath": "C:\\certifiactes\\data-protection.pfx",
    "X509CertificatePassword": "P@ssw0rd"
  },
  "KeyManagementOptions": {
    "AutoGenerateKeys": true,
    "NewKeyLifetime": "90.00:00:00"
  },
  "AuthenticatedEncryptorConfiguration" : {
    "EncryptionAlgorithm": "AES_256_CBC",
    "ValidationAlgorithm": "HMACSHA256"
  }
}

Storages

  • StorageKind defines the storage kind to use.
  • StorageConnectionString defines how to access the storage.

The configuration support all Key storage providers

File system

  "StorageKind": "FileSytem",
  "StorageConnectionString": "C:\\data-protection-keys",

For FileSytem storage kind, the StorageConnectionString defines the path where to store keys.

Azure Storage

  "StorageKind": "AzureStorage",
  "StorageConnectionString": "<blob URI including SAS token>",

For AzureStorage storage kind, the StorageConnectionString defines the blog URI including SAS token where to store keys.

Redis

  "StorageKind": "Redis",
  "StorageConnectionString": "localhost:6379",
  "RedisKey": "DataProtection-Keys"

For Redis storage kind, the StorageConnectionString defines the redis connection string.
(optional) RedisKey defines the redis list key where to store generated keys.

Entity Framework Core

  "StorageKind": "EntityFramework"

For EntityFramework storage king, keys are store in the DataProtectionKeys table of TheIdServer database

RavenDb

  "StorageKind": "RavenDb"

For RavenDb storage king, keys are store in the DataProtectionKeys document of RavenDb database

MongoDb

  "StorageKind": "MongoDb"

For MongoDb storage king, keys are store in the DataProtectionKeys collection of MongoDb database

Registry

Only applies to Windows deployments.

  "StorageKind": "Registry",
  "StorageConnectionString": "SOFTWARE\\Sample\\keys"

For Registry storage kind, the StorageConnectionString defines the registry path where to store keys.

Keys cannot be shared across several instances of a web app using Registry store

Key protection

KeyProtectionOptions controls Key encryption at rest configuration.
The configuartion support all kind of encryption systems.

  • KeyProtectionKind defines the kind of key protection to use.

Azure Key Vault

  "KeyProtectionOptions": {
    "KeyProtectionKind": "AzureKeyVault",
    "AzureKeyVaultKeyId": "<keyIdentifier>",
    "AzureKeyVaultClientId": "<clientId>",
    "AzureKeyVaultClientSecret": "<clientSecret>"
  }

Windows DPAPI

Only applies to Windows deployments.

  "KeyProtectionOptions": {
    "KeyProtectionKind": "WindowsDpApi",
    "WindowsDPAPILocalMachine": false
  }

X.509 certificate

From certificate file :

  "KeyProtectionOptions": {
    "KeyProtectionKind": "X509",  
    "X509CertificatePath": "C:\\certificates\\theidserver.pfx",
    "X509CertificatePassword": "P@ssw0rd"
  }

If the certificate is loaded from a file, it can be selfsigned/seflencrypted and expired.

From certificate thumbprint :

  "KeyProtectionOptions": {
    "KeyProtectionKind": "X509",
    "X509CertificatePath": "3BCE558E2AD3E0E34A7743EAB5AEA2A9BD2575A0"
  }

Using the thumbprint, the certificate must be valid.

Windows DPAPI-NG

This mechanism is available only on Windows 8/Windows Server 2012 or later.

  "KeyProtectionOptions": {
    "KeyProtectionKind": "WindowsDpApiNg"
  }

Using a SID

  "KeyProtectionOptions": {
    "KeyProtectionKind": "WindowsDpApiNg"
    "WindowsDpApiNgSid": "S-1-5-21-..."
  }

Using a certificate thumbprint

  "KeyProtectionOptions": {
    "KeyProtectionKind": "WindowsDpApiNg"
    "WindowsDpApiNgCerticate": "3BCE558E2...B5AEA2A9BD2575A0"
  }

Key management

The section KeyManagementOptions congrols the Key management configuration

  "KeyManagementOptions": {
    "AutoGenerateKeys": true,
    "NewKeyLifetime": "90.00:00:00"
  }
  • AutoGenerateKeys by default keys are auto generated, you can disable auto generation with "AutoGenerateKeys": false.
  • NewKeyLifetime by default the key lifetime is 90 days. You can set your lifetime with NewKeyLifetime but it cannot be less than 1 week.

Algorithms

You can change alrorithms with the section AuthenticatedEncryptorConfiguration. It's binded to a AuthenticatedEncryptorConfiguration object.

  "AuthenticatedEncryptorConfiguration" : {
    "EncryptionAlgorithm": "AES_256_CBC",
    "ValidationAlgorithm": "HMACSHA256"
  }

Additionals resources

Authors: Olivier Lefebvre