SimpleSecurity.DataProtection
1.0.1
dotnet add package SimpleSecurity.DataProtection --version 1.0.1
NuGet\Install-Package SimpleSecurity.DataProtection -Version 1.0.1
<PackageReference Include="SimpleSecurity.DataProtection" Version="1.0.1" />
<PackageVersion Include="SimpleSecurity.DataProtection" Version="1.0.1" />
<PackageReference Include="SimpleSecurity.DataProtection" />
paket add SimpleSecurity.DataProtection --version 1.0.1
#r "nuget: SimpleSecurity.DataProtection, 1.0.1"
#:package SimpleSecurity.DataProtection@1.0.1
#addin nuget:?package=SimpleSecurity.DataProtection&version=1.0.1
#tool nuget:?package=SimpleSecurity.DataProtection&version=1.0.1
SimpleSecurity.DataProtection
English | 中文
A replacement for ASP.NET Core's IDataProtectionProvider. All keys are derived from a single
secret string, like Laravel (PHP)'s APP_KEY. There is no key-ring XML under
~/.aspnet/dataprotection-keys/, no key rotation, and no shared storage to configure.
Instances configured with the same secret can decrypt each other's payloads.
Behavior
- Default ASP.NET Core data protection generates a random key, writes it to a key-ring (disk, Redis, or blob storage), and rotates it every 90 days. If the key-ring is lost, existing cookies, tokens, and antiforgery values cannot be decrypted.
- This library uses one fixed secret instead. The secret is supplied by the application and is not persisted by the library. There is no automatic rotation.
How it works
- HKDF-SHA256 derives a separate AES-256 key per purpose.
CreateProtector("cookies")andCreateProtector("antiforgery")use different keys, so a protector cannot decrypt another purpose's payloads. - AES-GCM provides authenticated encryption. Its 128-bit tag detects tampering, so no separate HMAC is used.
- Payload layout:
[version:1][nonce:12][tag:16][ciphertext:n]. The version byte is bound as AES-GCM associated data. The format can change without breaking older payloads.
Install
dotnet add package SimpleSecurity.DataProtection
Target frameworks: net8.0, net9.0, net10.0.
Usage
Inline secret
builder.Services.UseSimpleDataProtection("a-long-random-secret");
From an environment variable
builder.Services.UseSimpleDataProtection()
.UseSecretFromEnvironment("APP_KEY");
Throws at startup if the variable is missing or empty.
From configuration (appsettings.json, user secrets, Key Vault)
builder.Services.UseSimpleDataProtection()
.UseSecret(builder.Configuration["Security:DataProtectionKey"]!);
Options delegate and optional salt
builder.Services.UseSimpleDataProtection(options =>
{
options.UseSecret(builder.Configuration["Security:Key"]!);
options.UseSalt("my-app-domain-separator"); // optional HKDF salt
});
Every UseSimpleDataProtection(...) overload returns ISimpleDataProtectionBuilder for chaining:
builder.Services
.UseSimpleDataProtection("secret")
.UseSalt("tenant-42");
On the host builder
IHostApplicationBuilder overloads register the provider and return the builder. They work with
WebApplicationBuilder and HostApplicationBuilder:
builder.UseSimpleDataProtection("a-long-random-secret");
// or
builder.UseSimpleDataProtection(o => o.UseSecret(builder.Configuration["APP_KEY"]!));
Consuming the provider
Same API as the built-in provider. Inject IDataProtectionProvider and create a protector:
public class TokenService(IDataProtectionProvider provider)
{
private readonly IDataProtector _protector = provider.CreateProtector("MyApp.Tokens.v1");
public string Protect(string value) =>
Convert.ToBase64String(_protector.Protect(Encoding.UTF8.GetBytes(value)));
}
Notes
- Keep the secret confidential and stable. Anyone with the secret can read and forge payloads. Changing the secret invalidates existing cookies, tokens, and antiforgery values.
- Use a high-entropy secret. HKDF stretches the input but does not add entropy. Use 32+ random
bytes (for example
openssl rand -base64 32), not a short passphrase. - The same secret and salt produce interchangeable instances. The secret must be distributed to every instance that needs to interoperate.
- No automatic rotation. To rotate, change the secret (existing payloads stop decrypting) or
bump the purpose string (for example
...Tokens.v2).
License
MIT
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Microsoft.AspNetCore.DataProtection.Abstractions (>= 8.0.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Hosting.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Options (>= 8.0.0)
-
net8.0
- Microsoft.AspNetCore.DataProtection.Abstractions (>= 8.0.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Hosting.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Options (>= 8.0.0)
-
net9.0
- Microsoft.AspNetCore.DataProtection.Abstractions (>= 8.0.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Hosting.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Options (>= 8.0.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.