RavenDB uses client certificate authentication (mutual TLS) to secure your database connection.
The .NET Client SDK supports
X509Certificate2 which is passed to the
There are multiple ways to load a certificate:
- Load from .pfx files
- Load from PEM-encoded certificate
- Load from AWS Secrets Manager
Load from .pfx Files
You can load PFX files with or without a password by providing the certificate path using
The dependency injection logic will automatically load the certificate from this path without extra code.
.pfx file requires a password, provide it using the .NET secrets tool by setting
dotnet user-secrets init
dotnet user-secrets set "RavenSettings:CertPassword" "<CertPassword>"
However, keep in mind that using an absolute physical file path or a user secret requires manual steps
for every developer working on a project to configure.
Avoid uploading or deploying .pfx files
PFX files can be compromised, especially if they are not password-protected. Using a physical file also makes
it hard to manage and rotate when they expire. They are only recommended for ease-of-use on your local machine.
For production, it is better to use the PEM certificate method or AWS Secrets Manager.
Load from PEM-encoded certificate
For AWS Lambda, it's recommended to use a PEM-encoded certificate that can be provided through an environment
variable without deploying any files.
.pfx file, a PEM-encoded certificate is plain-text encoded:
-----BEGIN RSA PRIVATE KEY-----
-----END RSA PRIVATE KEY-----
AWS limits the size of an environment variable to 4KB with a 5KB limit for all variables.
To pass a PEM-encoded certificate, you will need to store the public key (
.crt file) alongside your app
files and pass the private key contents through an environment variable like
The private key will be about 3KB, leaving 2KB left for other environment variables.
On the client, you will have to assemble a PEM using the static
X509Certificate2.CreateFromPem(publicKey, privateKey) method.
Here is an example
Program.cs that adds support for assembling a PEM certificate by adding
RavenSettings:CertPrivateKey configuration options:
var builder = WebApplication.CreateBuilder(args);
var certPrivateKey = builder.Configuration.GetSection("RavenSettings:CertPrivateKey");
var certPublicKeyFilePath = builder.Configuration.GetSection("RavenSettings:CertPublicKeyFilePath");
var usePemCert = certPrivateKey != null && certPublicKeyFilePath != null;
var certPem = File.ReadAllText(certPublicKeyFilePath);
// Workaround ephemeral keys in Windows
// See: https://github.com/dotnet/runtime/issues/66283
var intermediateCert = X509Certificate2.CreateFromPem(certPem, certPrivateKey);
var cert = new X509Certificate2(intermediateCert.Export(X509ContentType.Pfx));
options.Certificate = cert;
var app = builder.Build();
This supports using
.pfx files or a PEM-encoded certificate, if provided.
It works around a known issue in Windows with ephemeral keys.
For a full reference implementation, view the code on the template repository.
Load from AWS Secrets Manager
If you want to load your .NET configuration from AWS Secrets Manager, you can use the community package
Kralizek.Extensions.Configuration.AWSSecretsManager to support securely loading certificates
instead of relying on production environment variables.
Learn more about configuring AWS Secrets Manager