FluffySpoon.AspNet.EncryptWeMust

First some shameless promotion for my other project. **I'm currently building the GitHub app [Pull Dog](https://dogger.io)**, which creates a Docker-based test environment for every pull request you open, and send a link to the environment right in the pull request itself, as a comment. # What is this? The simplest LetsEncrypt setup for ASP .NET Core. Almost no server configuration needed. `Install-Package FluffySpoon.AspNet.EncryptWeMust` **This project used to be called `FluffySpoon.AspNet.LetsEncrypt`, but due to a trademark claim from LetsEncrypt, we had to rename it. The name now follows Yoda Speak.** # Requirements - Kestrel (which is default) - ASP .NET Core 2.1+ - An always-on app-pool ## Getting an always-on app pool This is required because the renewal job runs on a background thread and polls once every hour to see if the certificate needs renewal (this is a very cheap operation). It can be enabled using __just one__ the following techniques: - Enabling Always On if using Azure App Service. - Setting `StartMode` of the app pool to `AlwaysRunning` if using IIS. - Hosting your ASP .NET Core application as a Windows Service. # Usage example If you want to try it yourself, you can also browse the sample project code here: https://github.com/ffMathy/FluffySpoon.AspNet.EncryptWeMust/tree/master/src/FluffySpoon.AspNet.EncryptWeMust.Sample ## Configure the services Add the following code to your `Startup` class' `ConfigureServices` method with real values instead of the sample values: _Note that you can set either `TimeUntilExpiryBeforeRenewal`, `TimeAfterIssueDateBeforeRenewal` or both, but at least one of them has to be specified._ ```csharp //the following line adds the automatic renewal service. services.AddFluffySpoonLetsEncrypt(new LetsEncryptOptions() { Email = "some-email@github.com", //LetsEncrypt will send you an e-mail here when the certificate is about to expire UseStaging = false, //switch to true for testing Domains = new[] { DomainToUse }, TimeUntilExpiryBeforeRenewal = TimeSpan.FromDays(30), //renew automatically 30 days before expiry TimeAfterIssueDateBeforeRenewal = TimeSpan.FromDays(7), //renew automatically 7 days after the last certificate was issued CertificateSigningRequest = new CsrInfo() //these are your certificate details { CountryName = "Denmark", Locality = "DK", Organization = "Fluffy Spoon", OrganizationUnit = "Hat department", State = "DK" } }); //the following line tells the library to persist the certificate to a file, so that if the server restarts, the certificate can be re-used without generating a new one. services.AddFluffySpoonLetsEncryptFileCertificatePersistence(); //the following line tells the library to persist challenges in-memory. challenges are the "/.well-known" URL codes that LetsEncrypt will call. services.AddFluffySpoonLetsEncryptMemoryChallengePersistence(); ``` ## Inject the middleware Inject the middleware in the `Startup` class' `Configure` method as such: ```csharp public void Configure() { app.UseFluffySpoonLetsEncrypt(); } ``` ## Set default bindings Call UseUrls with http://* and https://* in Program.cs ```csharp public static IHostBuilder CreateHostBuilder(string[] args) => Host.CreateDefaultBuilder(args) .ConfigureWebHostDefaults(webBuilder => { webBuilder.UseUrls(new string[] { "http://*", "https://*" }); webBuilder.UseStartup<Startup>(); }); ``` Tada! Your application now supports SSL via LetsEncrypt, even from the first HTTPS request. It will even renew your certificate automatically in the background. # Optional: Configuring persistence Persistence tells the middleware how to persist and retrieve the certificate, so that if the server restarts, the certificate can be re-used without generating a new one. A certificate has a _key_ to distinguish between certificates, since there is both an account certificate and a site certificate that needs to be stored. ## File persistence ```csharp services.AddFluffySpoonLetsEncryptFileCertificatePersistence(); services.AddFluffySpoonLetsEncryptFileChallengePersistence(); ``` ## Custom persistence ```csharp services.AddFluffySpoonLetsEncryptCertificatePersistence(/* your own ILetsEncryptPersistence implementation */); services.AddFluffySpoonLetsEncryptChallengePersistence(/* your own ILetsEncryptPersistence implementation */); //you can also customize persistence via delegates. services.AddFluffySpoonLetsEncryptCertificatePersistence( async (key, bytes) => File.WriteAllBytes("certificate_" + key, bytes), async (key) => File.ReadAllBytes("certificate_" + key, bytes)); //the same can be done for challenges, with different arguments. services.AddFluffySpoonLetsEncryptChallengePersistence( async (challenges) => ... /* Do something to serialize the collection of challenges and store it */, async () => ... /* Retrieve the stored collection of challenges */, async (challenges) => ... /* Delete the specified challenges */); ``` ## Entity Framework persistence Requires the NuGet package `FluffySpoon.AspNet.EncryptWeMust.EntityFramework`. ```csharp // Certificate and Challenge in this example are database model classes that have been configured with the database context. class Certificate { [Key] public string Key { get; set; } public byte[] Bytes { get; set; } } public class Challenge { [Key] public string Token { get; set; } public string Response { get; set; } public int Type { get; set; } public string Domains { get; set; } } //we only have to instruct how to add the certificate - `databaseContext.SaveChangesAsync()` is automatically called. services.AddFluffySpoonLetsEncryptEntityFrameworkCertificatePersistence<DatabaseContext>( async (databaseContext, key, bytes) => { var existingCertificate = databaseContext.Certificates.SingleOrDefault(x => x.Key == key); if (existingCertificate != null) { existingCertificate.Bytes = bytes; } else { databaseContext.Certificates.Add(new Certificate() { Key = key, Bytes = bytes }); } }, async (databaseContext, key) => databaseContext .Certificates .SingleOrDefault(x => x.Key == key) ?.Bytes); //the same can be done for challenges services.AddFluffySpoonLetsEncryptEntityFrameworkChallengePersistence<DatabaseContext>( async (databaseContext, challenges) => databaseContext .Challenges .AddRange( challenges.Select(x => new Challenge() { Token = x.Token, Response = x.Response, Type = (int)x.Type, Domains = String.Join(",", x.Domains) })), async (databaseContext) => databaseContext .Challenges .Select(x => new ChallengeDto() { Token = x.Token, Response = x.Response, Type = (ChallengeType)x.Type, Domains = x.Domains.Split(',', StringSplitOptions.RemoveEmptyEntries) }), async (databaseContext, challenges) => databaseContext .Challenges .RemoveRange( databaseContext .Challenges .Where(x => challenges.Any(y => y.Token == x.Token)) )); ``` ## Distributed cache (Redis etc) persistence Requires: - The NuGet package `FluffySpoon.AspNet.EncryptWeMust.DistributedCache`. - A configured distributed cache in ASP .NET Core using the `services.AddDistributedRedisCache()` or similar. ```csharp services.AddFluffySpoonLetsEncryptDistributedCertificatePersistence(expiry: TimeSpan.FromDays(30)); services.AddFluffySpoonLetsEncryptDistributedChallengePersistence(expiry: TimeSpan.FromHours(1)); ``` # Azure App Service Using this project when running as an Azure App Service requires a few things. Firstly the App Service Plan needs to have the "Custom domains / SSL" feature (currently B1 for testing, S1 for production are the lowest supported). Secondly you should use the `AzureAppServiceSslBindingCertificatePersistenceStrategy` strategy: ```csharp services.AddFluffySpoonLetsEncryptAzureAppServiceSslBindingCertificatePersistence( new AzureOptions