Fallenwood.LettuceEncrypt
1.4.0-alpha0-beta.19
dotnet add package Fallenwood.LettuceEncrypt --version 1.4.0-alpha0-beta.19
NuGet\Install-Package Fallenwood.LettuceEncrypt -Version 1.4.0-alpha0-beta.19
<PackageReference Include="Fallenwood.LettuceEncrypt" Version="1.4.0-alpha0-beta.19" />
paket add Fallenwood.LettuceEncrypt --version 1.4.0-alpha0-beta.19
#r "nuget: Fallenwood.LettuceEncrypt, 1.4.0-alpha0-beta.19"
// Install Fallenwood.LettuceEncrypt as a Cake Addin #addin nuget:?package=Fallenwood.LettuceEncrypt&version=1.4.0-alpha0-beta.19&prerelease // Install Fallenwood.LettuceEncrypt as a Cake Tool #tool nuget:?package=Fallenwood.LettuceEncrypt&version=1.4.0-alpha0-beta.19&prerelease
<h1> <img src="./src/icon.png" width="42" height="42"/> LettuceEncrypt for ASP.NET Core </h1>
LettuceEncrypt provides API for ASP.NET Core projects to integrate with a certificate authority (CA), such as Let's Encrypt, for free, automatic HTTPS (SSL/TLS) certificates using the ACME protocol.
When enabled, your web server will automatically generate an HTTPS certificate during start up. It then configures Kestrel to use this certificate for all HTTPS traffic. See usage instructions below to get started.
Created and developed by @natemcmaster with ❤️ from Seattle ☕️. Forked by @Fallenwood at 2024 Jun. This project was formerly known as "McMaster.AspNetCore.LetsEncrypt", but has been renamed for trademark reasons. This project is not an official offering from Let's Encrypt® or ISRG™.
This project is 100% organic and best served cold with ranch and carrots. 🥬
Project status
This project is in maintenance mode. I lost interest in developing features. I will make a patch if there is a security issue. I'll also consider an update if a new .NET major version breaks and the patch fix required is small. Please see https://github.com/fallenwood/LettuceEncrypt/security/policy if you wish to report a security concern.
Will this work for me?
That depends on which kind of web server you are using. This library only works with Kestrel, which is the default server configuration for ASP.NET Core projects. Other servers, such as IIS and HTTP.sys, are not supported. Furthermore, this only works when Kestrel is the edge server.
Not sure? Read "Web Server Scenarios" below for more details.
Using ☁️ Azure App Services (aka WebApps)? This library isn't for you, but you can still get free HTTPS certificates. See "Securing An Azure App Service with Let's Encrypt" by Scott Hanselman for more details.
Usage
Install this package into your project using NuGet (see details here).
The primary API usage is to call IServiceCollection.AddLettuceEncrypt
in the Startup
class ConfigureServices
method.
using Microsoft.Extensions.DependencyInjection;
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
services.AddLettuceEncrypt();
}
}
A few required options should be set, typically via the appsettings.json file.
// appsettings.json
{
"LettuceEncrypt": {
// Set this to automatically accept the terms of service of your certificate authority.
// If you don't set this in config, you will need to press "y" whenever the application starts
"AcceptTermsOfService": true,
// You must specify at least one domain name
"DomainNames": [ "example.com", "www.example.com" ],
// You must specify an email address to register with the certificate authority
"EmailAddress": "it-admin@example.com"
}
}
Additional options
Kestrel configuration
If your code is using the .UseKestrel()
method to configure IP addresses, ports, or HTTPS settings,
you will also need to call UseLettuceEncrypt
. This is required to make Lettuce Encrypt work.
Example: ConfigureHttpsDefaults
If calling ConfigureHttpsDefaults
, use UseLettuceEncrypt
like this:
webBuilder.UseKestrel(k =>
{
var appServices = k.ApplicationServices;
k.ConfigureHttpsDefaults(h =>
{
h.ClientCertificateMode = ClientCertificateMode.RequireCertificate;
h.UseLettuceEncrypt(appServices);
});
});
Example: Listen + UseHttps
If using Listen
+ UseHttps
to manually configure Kestrel's address binding, use UseLettuceEncrypt
like this:
webBuilder.UseKestrel(k =>
{
var appServices = k.ApplicationServices;
k.Listen(
IPAddress.Any, 443,
o => o.UseHttps(h =>
{
h.UseLettuceEncrypt(appServices);
}));
});
Customizing storage
Certificates are stored to the machine's X.509 store by default. Certificates can be stored in additional
locations by using extension methods after calling AddLettuceEncrypt()
in the Startup
class.
Multiple storage locations can be configured.
Save generated certificates and account information to a directory
This will save and load certificate files (PFX format) using the specified directory. It will also save your certificate authority account key into the same directory.
using LettuceEncrypt;
using Microsoft.Extensions.DependencyInjection;
public void ConfigureServices(IServiceCollection services)
{
services
.AddLettuceEncrypt()
.PersistDataToDirectory(new DirectoryInfo("C:/data/LettuceEncrypt/"), "Password123");
}
Save generated certificates to Azure Key Vault
Install LettuceEncrypt.Azure. This will save and load certificate files using an Azure Key Vault. It will also save your certificate authority account key as a secret in the same vault.
using LettuceEncrypt;
using Microsoft.Extensions.DependencyInjection;
public void ConfigureServices(IServiceCollection services)
{
services
.AddLettuceEncrypt()
.PersistCertificatesToAzureKeyVault();
}
// appsettings.json
{
"LettuceEncrypt": {
"AzureKeyVault": {
// Required - specify the name of your key vault
"AzureKeyVaultEndpoint": "https://myaccount.vault.azure.net/"
// Optional - specify the secret name used to store your account info (used for cert rewewals)
// If not specified, name defaults to "le-encrypt-${ACME server URL}"
"AccountKeySecretName": "my-lets-encrypt-account"
}
}
}
Customizing how the certs are saved and loaded
Create a class that implements ICertificateRepository
to customize how to save your certificates.
Create a class that implements ICertificateSource
to customize where pre-existing certificates are
found when the server starts.
using LettuceEncrypt;
using Microsoft.Extensions.DependencyInjection;
public void ConfigureServices(IServiceCollection services)
{
services.AddLettuceEncrypt();
services.AddSingleton<ICertificateRepository, MyCertRepo>();
services.AddSingleton<ICertificateSource, MyCertSource>();
}
class MyCertRepo : ICertificateRepository
{
public async Task SaveAsync(X509Certificate2 certificate, CancellationToken cancellationToken)
{
byte[] certData = certificate.Export(X509ContentType.Pfx, "optionallySetPfxPassword");
// save this data somehow
}
}
class MyCertSource : ICertificateSource
{
public async Task<IEnumerable<X509Certificate2>> GetCertificatesAsync(CancellationToken cancellationToken);
{
// find and return certificate objects. Return an empty enumerable if none are found
}
}
Customizing saving your account key
Your interactions with the certificate authority are encrypted with a private
key which is generated automatically on first-use. To ensure you can renew certificates
later using the same account, this account key is saved to disk by default.
You can customize where this account information is shared by adding your own implementation
of IAccountStore
.
using LettuceEncrypt;
using LettuceEncrypt.Accounts;
public void ConfigureServices(IServiceCollection services)
{
services.AddLettuceEncrypt();
services.AddSingleton<IAccountStore, MyAccountStore>();
}
class MyAccountStore: IAccountStore
{
public Task SaveAccountAsync(AccountModel account, CancellationToken cancellationToken)
{
// save the account object somewhere
}
// add #nullable enable if using c#, or remove the question mark for older versions of C#
public Task<AccountModel?> GetAccountAsync(CancellationToken cancellationToken)
{
// return null if there is no account and one will be created for you
}
}
Changing which challenge types are used
The ACME protocol supports multiple methods for proving you own a DNS name called "challenge types". If you wish to manually select which challenge types are used, set the "AllowedChallengeTypes" method. The default value is "Any", which means this library will exhaust all supported challenge types before giving up.
Current supported values:
Http01
- The HTTP-01 challenge, which uses a well-known URL on the server and a HTTP request/response.TlsAlpn01
- The TLS-ALPN-01 challenge, which uses an auto-generated, ephemeral certificate in the TLS handshake.Dns01
- The DNS-01 challenge, which uses TXT record under that domain name.Any
- (default) - use HTTP-01 and/or TLS-ALPN-01 DNS-01
Tip: if you wish to set multiple method types and are use the "appsettings.json" approach, provide a comma-seperated list.
{
"LettuceEncrypt": {
"AllowedChallengeTypes": "Http01, TlsAlpn01, Dns01"
}
}
When using DNS-01
When using the DNS-01 challenge a IDnsChallengeProvider
must be add and replace the NoOpDnsChallengeProvider
public class MyDnsChallengeProvider : IDnsChallengeProvider
{
private readonly ISomeExternalDnsClient _client;
public MyDnsChallengeProvider(ISomeExternalDnsClient client) => _client = client;
public Task AddTxtRecordAsync(string domainName, string txt, CancellationToken ct = default)
{
return _client.AddDnsTxtRecord(domainName, txt, ct);
}
public Task RemoveTxtRecordAsync(string domainName, string txt, CancellationToken ct = default)
{
return _client.RemoveDnsTxtRecord(domainName, txt, ct);
}
}
Testing in development
See the developer docs for details on how to test in a non-production environment.
Web Server Scenarios
I recommend also reading Microsoft's official documentation on hosting and deploying ASP.NET Core.
ASP.NET Core with Kestrel
✅ supported
In this scenario, ASP.NET Core is hosted by the Kestrel server (the default, in-process HTTP server) and that web server exposes its ports directly to the internet. This library will configure Kestrel with an auto-generated certificate.
ASP.NET Core with IIS
❌ NOT supported
In this scenario, ASP.NET Core is hosted by IIS and that web server exposes its ports directly to the internet. IIS does not support dynamically configuring HTTPS certificates, so this library cannot support this scenario, but you can still configure cert automation using a different tool. See "Using Let's Encrypt with IIS On Windows" for details.
Azure App Service uses this for ASP.NET Core 2.2 and newer, which is why this library cannot support that scenario.. Older versions of ASP.NET Core on Azure App Service run with IIS as the reverse proxy (see below), which is also an unsupported scenario.
ASP.NET Core with Kestrel Behind a TCP Load Balancer (aka SSL pass-thru)
✅ supported
In this scenario, ASP.NET Core is hosted by the Kestrel server (the default, in-process HTTP server) and that web server exposes its ports directly to a local network. A TCP load balancer such as nginx forwards traffic without decrypting it to the host running Kestrel. This library will configure Kestrel with an auto-generated certificate.
ASP.NET Core with Kestrel Behind a Reverse Proxy
❌ NOT supported
In this scenario, HTTPS traffic is decrypted by a different web server that is beyond the control of ASP.NET Core. This library cannot support this scenario because HTTPS certificates must be configured by the reverse proxy server.
This is commonly done by web hosting providers. For example, ☁️ Azure App Services (aka WebApps) often runs older versions of ASP.NET Core in a reverse proxy.
If you are running the reverse proxy, you can still get free HTTPS certificates, but you'll need to use a different method. Try Googling this.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. 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. |
-
net6.0
- Certes (>= 3.0.4)
- Fallenwood.McMaster.AspNetCore.Kestrel.Certificates (>= 1.0.0-beta.19)
-
net8.0
- Certes (>= 3.0.4)
- Fallenwood.McMaster.AspNetCore.Kestrel.Certificates (>= 1.0.0-beta.19)
NuGet packages (1)
Showing the top 1 NuGet packages that depend on Fallenwood.LettuceEncrypt:
Package | Downloads |
---|---|
Fallenwood.LettuceEncrypt.Azure
Provides API for configuring ASP.NET Core to automatically generate HTTPS certificates and store them in Azure Key Vault. See https://nuget.org/packages/Fallenwood.LettuceEncrypt for more details. |
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
1.4.0-alpha0-beta.19 | 150 | 7/30/2024 |
1.4.0-alpha0 | 43 | 7/30/2024 |
New features:
* Add Dynamic Confing Provider for DomainNames.
* Add LettuceEncrypt.LettuceEncryptOptionsProvider to dynamicly configure LettuceEncryptOptions.
Breaking Changes:
* In-memory configuration provider has higher priority than explicit options.
Other:
* Added support for .NET 8