LettuceEncrypt 1.1.2

Install-Package LettuceEncrypt -Version 1.1.2
dotnet add package LettuceEncrypt --version 1.1.2
<PackageReference Include="LettuceEncrypt" Version="1.1.2" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add LettuceEncrypt --version 1.1.2
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: LettuceEncrypt, 1.1.2"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install LettuceEncrypt as a Cake Addin
#addin nuget:?package=LettuceEncrypt&version=1.1.2

// Install LettuceEncrypt as a Cake Tool
#tool nuget:?package=LettuceEncrypt&version=1.1.2
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

<h1> <img src="./src/icon.png" width="42" height="42"/> LettuceEncrypt for ASP.NET Core </h1>

Build Status Code Coverage NuGet NuGet Downloads

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 ☕️. 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/natemcmaster/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][nuget-url]).

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 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.
  • Any - (default) - use HTTP-01 and/or TLS-ALPN-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"
    }
}

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

Diagram of Kestrel on the edge with Kestrel

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

Diagram of Kestrel on the edge with IIS

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

Diagram of TCP Load Balancer

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

Diagram of reverse proxy

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.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on LettuceEncrypt:

Package Downloads
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/LettuceEncrypt for more details.

Stormancer.LettuceEncrypt

Let's Encrypt plugin for Stormancer

Zen.Web.SelfHost

Package Description

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.1.2 104 10/13/2021
1.1.1 4,152 7/9/2021
1.1.0 1,495 6/13/2021
1.1.0-beta.81 661 5/2/2021
1.1.0-beta.73 7,721 7/9/2020
1.1.0-beta.60 496 6/7/2020
1.1.0-beta.19 223 1/17/2021
1.0.1 13,265 11/28/2020
1.0.0 12,543 5/26/2020
1.0.0-beta.6 255 5/21/2020

New features:
* Add API for controlling whether HTTP-01, TLS-ALPN-01, or both challenge types are used (#197)
* create abstraction for SNI certificates in Kestrel (#108)
* add API to configure LettuceEncrypt when also calling 'UseKestrel' to configure its HTTPS defaults or endpoints (#109)

Bug fixes:
* workaround bug in Windows SSL stream when generating temporary self-signed certs (#110)
* fix race condition  causing domain validation to valid sometimes. Run TLS-ALPN-01 first then HTTP-01 (if needed). Don't run in parallel (#198)
* Don't unset other HTTPS adapters which configure a OnAuthenticate callback (#199)

Other:
* Update package to target .NET Core 3.1 as 3.0 is no longer supported by Microsoft

Fixes in patch 1.1.1:
* Fix infinite loop waiting for verification of domain ownership
* Check for certificates that new renewal immediately on server startup instead of waiting 24 hours
* Optimize loading intermediate certificate change and reduce unnecessary warnings about invalid certs

Fixes in patch 1.1.2:
* Raise validation error if attempting to use wildcards