### Example LettuceEncrypt Trace Log Output

Source: https://github.com/natemcmaster/lettuceencrypt/wiki/Diagnosing-issues

This is an example of the detailed log output you might see from LettuceEncrypt when trace logging is enabled. It demonstrates the type of information captured, such as using an existing account for certificate renewal. This output is crucial for diagnosing specific issues.

```log
info: LettuceEncrypt.Internal.AcmeCertificateLoader[0]
      Using existing account for mailto:it-admin@example.com
```

--------------------------------

### Configure LettuceEncrypt with Azure KeyVault and Custom Credentials

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/test/Integration/README.md

This C# code configures LettuceEncrypt to use Azure KeyVault with custom credentials for certificate management. It extends the previous example by allowing the explicit setting of credentials, which is useful when default Azure credentials are not sufficient. Ensure 'Azure.Identity' is installed and consult its documentation for credential setup.

```csharp
public void ConfigureServices(IServiceCollection services)
{
    services.AddLettuceEncrypt()
        .AddAzureKeyVaultCertificateSource(o =>
        {
            o.Credentials = new SomeCredentials();
            o.AzureKeyVaultEndpoint = "https://[url].vault.azure.net/";
        })
        .PersistCertificatesToAzureKeyVault();
}
```

--------------------------------

### Implement IAccountStore for ACME Account Persistence

Source: https://context7.com/natemcmaster/lettuceencrypt/llms.txt

Provides an example of implementing IAccountStore to persist ACME account information in Redis. This is essential for maintaining account identity across application restarts.

```csharp
public class RedisAccountStore : IAccountStore {
    private readonly IRedisClient _redis;
    public RedisAccountStore(IRedisClient redis) => _redis = redis;
    public async Task SaveAccountAsync(AccountModel account, CancellationToken cancellationToken) {
        var json = JsonSerializer.Serialize(new { account.Id, account.EmailAddresses, PrivateKey = Convert.ToBase64String(account.PrivateKey) });
        await _redis.SetAsync("acme:account", json);
    }
    public async Task<AccountModel?> GetAccountAsync(CancellationToken cancellationToken) {
        var json = await _redis.GetAsync("acme:account");
        if (string.IsNullOrEmpty(json)) return null;
        var data = JsonSerializer.Deserialize<AccountData>(json);
        return new AccountModel { Id = data.Id, EmailAddresses = data.EmailAddresses, PrivateKey = Convert.FromBase64String(data.PrivateKey) };
    }
}
```

--------------------------------

### Persist Certificates to Azure Key Vault in C#

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/README.md

Integrates LettuceEncrypt with Azure Key Vault for storing generated certificates and account keys. This requires installing the LettuceEncrypt.Azure NuGet package and configuring the Azure Key Vault endpoint and optionally a secret name for account information.

```csharp
using LettuceEncrypt;
using Microsoft.Extensions.DependencyInjection;

public void ConfigureServices(IServiceCollection services)
{
    services
        .AddLettuceEncrypt()
        .PersistCertificatesToAzureKeyVault();
}
```

```json
// 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"
        }
    }
}
```

--------------------------------

### Configure Kestrel with Listen and UseHttps in C#

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/README.md

Demonstrates how to manually configure Kestrel's address binding using Listen and UseHttps, integrating LettuceEncrypt for HTTPS certificate management. This approach is useful when you need fine-grained control over Kestrel's server configuration.

```csharp
webBuilder.UseKestrel(k =>
{
    var appServices = k.ApplicationServices;
    k.Listen(
        IPAddress.Any, 443,
        o => o.UseHttps(h =>
        {
            h.UseLettuceEncrypt(appServices);
        }));
});
```

--------------------------------

### Implement ICertificateRepository for Custom Storage

Source: https://context7.com/natemcmaster/lettuceencrypt/llms.txt

Demonstrates how to implement the ICertificateRepository interface to save X.509 certificates to a database. It includes the repository class and the necessary dependency injection registration.

```csharp
public class DatabaseCertificateRepository : ICertificateRepository {
    private readonly IDbContext _dbContext;
    public DatabaseCertificateRepository(IDbContext dbContext) => _dbContext = dbContext;
    public async Task SaveAsync(X509Certificate2 certificate, CancellationToken cancellationToken) {
        await _dbContext.Certificates.UpsertAsync(new CertificateEntity {
            Thumbprint = certificate.Thumbprint,
            DomainName = certificate.GetNameInfo(X509NameType.DnsName, false),
            PfxData = certificate.Export(X509ContentType.Pfx, "optional-password"),
            ExpiresAt = certificate.NotAfter
        }, cancellationToken);
    }
}

public void ConfigureServices(IServiceCollection services) {
    services.AddLettuceEncrypt();
    services.AddSingleton<ICertificateRepository, DatabaseCertificateRepository>();
}
```

--------------------------------

### Configure Custom Certificate Authority with ICertificateAuthorityConfiguration

Source: https://context7.com/natemcmaster/lettuceencrypt/llms.txt

Shows how to implement ICertificateAuthorityConfiguration to point LettuceEncrypt to a non-default ACME provider like ZeroSSL. Includes the configuration class and registration in the service collection.

```csharp
public class ZeroSSLConfiguration : ICertificateAuthorityConfiguration {
    public Uri AcmeDirectoryUri => new Uri("https://acme.zerossl.com/v2/DV90");
    public string[] IssuerCertificates => new[] { "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" };
}

public class Startup {
    public void ConfigureServices(IServiceCollection services) {
        services.AddLettuceEncrypt(options => {
            options.AcceptTermsOfService = true;
            options.DomainNames = new[] { "example.com" };
            options.EabCredentials = new EabCredentials { EabKeyId = "kid", EabKey = "key", EabKeyAlg = "HS256" };
        });
        services.AddSingleton<ICertificateAuthorityConfiguration, ZeroSSLConfiguration>();
    }
}
```

--------------------------------

### Implement ICertificateSource for Loading Certificates

Source: https://context7.com/natemcmaster/lettuceencrypt/llms.txt

Shows how to implement the ICertificateSource interface to load existing certificates from a database upon application startup. This ensures previously issued certificates are available for use.

```csharp
public class DatabaseCertificateSource : ICertificateSource {
    private readonly IDbContext _dbContext;
    public DatabaseCertificateSource(IDbContext dbContext) => _dbContext = dbContext;
    public async Task<IEnumerable<X509Certificate2>> GetCertificatesAsync(CancellationToken cancellationToken) {
        var entities = await _dbContext.Certificates.Where(c => c.ExpiresAt > DateTime.UtcNow).ToListAsync(cancellationToken);
        return entities.Select(e => new X509Certificate2(e.PfxData, "optional-password", X509KeyStorageFlags.MachineKeySet | X509KeyStorageFlags.PersistKeySet));
    }
}

public void ConfigureServices(IServiceCollection services) {
    services.AddLettuceEncrypt();
    services.AddSingleton<ICertificateSource, DatabaseCertificateSource>();
}
```

--------------------------------

### Register LettuceEncrypt Services in ASP.NET Core

Source: https://context7.com/natemcmaster/lettuceencrypt/llms.txt

Demonstrates how to register LettuceEncrypt services using dependency injection. This can be done with basic registration relying on configuration or with inline options for fine-grained control over certificate generation parameters.

```csharp
using Microsoft.Extensions.DependencyInjection;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        // Basic registration - uses configuration from appsettings.json
        services.AddLettuceEncrypt();
    }
}

// With inline configuration
public class StartupWithOptions
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddLettuceEncrypt(options =>
        {
            options.AcceptTermsOfService = true;
            options.DomainNames = new[] { "example.com", "www.example.com" };
            options.EmailAddress = "admin@example.com";
            options.UseStagingServer = false; // Use production Let's Encrypt
            options.RenewDaysInAdvance = TimeSpan.FromDays(30);
            options.RenewalCheckPeriod = TimeSpan.FromDays(1);
            options.KeyAlgorithm = KeyAlgorithm.ES256; // ECDSA P-256
            options.AllowedChallengeTypes = ChallengeType.Http01 | ChallengeType.TlsAlpn01;
        });
    }
}
```

--------------------------------

### Configure LettuceEncrypt with ngrok Staging

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/test/Integration/README.md

This C# code configures LettuceEncrypt to use the Let's Encrypt staging environment for testing purposes. It specifies the domain names to be used and enables the staging server to avoid production rate limits. Ensure 'AcceptTermsOfService' and 'EmailAddress' are set appropriately.

```csharp
services.AddLettuceEncrypt(o =>
{
    o.DomainNames = new[] { "TMP.ngrok.io" };
    o.UseStagingServer = true; // <--- use staging

    o.AcceptTermsOfService = true;
    o.EmailAddress = "admin@example.com";
});
```

--------------------------------

### UseLettuceEncrypt with Kestrel Manual Configuration

Source: https://context7.com/natemcmaster/lettuceencrypt/llms.txt

Demonstrates how to integrate LettuceEncrypt into Kestrel's HTTPS configuration when manually setting up Kestrel. This is necessary when using ConfigureHttpsDefaults or Listen with UseHttps. It shows two options: configuring HttpsDefaults with client certificate requirements and manual address/port binding.

```csharp
using System.Net;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Server.Kestrel.Https;

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();

                // Option 1: ConfigureHttpsDefaults with client certificate requirement
                webBuilder.UseKestrel(kestrel =>
                {
                    var appServices = kestrel.ApplicationServices;
                    kestrel.ConfigureHttpsDefaults(https =>
                    {
                        https.ClientCertificateMode = ClientCertificateMode.RequireCertificate;
                        https.UseLettuceEncrypt(appServices);
                    });
                });

                // Option 2: Manual address/port binding
                webBuilder.PreferHostingUrls(false);
                webBuilder.UseKestrel(kestrel =>
                {
                    var appServices = kestrel.ApplicationServices;
                    kestrel.Listen(IPAddress.Any, 443, listenOptions =>
                    {
                        listenOptions.UseHttps(https =>
                        {
                            https.UseLettuceEncrypt(appServices);
                        });
                    });
                });
            });
}
```

--------------------------------

### Implement Custom DNS-01 Challenge Provider

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/README.md

Shows how to implement the IDnsChallengeProvider interface to handle DNS TXT record creation and removal. This is required when using the DNS-01 challenge type.

```csharp
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);
    }
}
```

--------------------------------

### Implement Custom Account Store in C#

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/README.md

Allows customization of how the account key, used for interacting with the certificate authority, is saved and retrieved. By implementing the `IAccountStore` interface, developers can manage account persistence in custom locations or systems.

```csharp
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
    }
}
```

--------------------------------

### Configure LettuceEncrypt Options - JSON

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/README.md

This JSON configuration demonstrates the essential options required for LettuceEncrypt. It includes accepting terms of service, specifying domain names for the certificate, and providing an email address for registration with the certificate authority.

```json
// 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"
    }
}
```

--------------------------------

### Configure LettuceEncrypt via appsettings.json

Source: https://context7.com/natemcmaster/lettuceencrypt/llms.txt

Shows how to configure LettuceEncrypt settings using the standard ASP.NET Core configuration system, specifically within the 'LettuceEncrypt' section of appsettings.json. This method allows for centralized management of certificate-related options.

```jsonc
// appsettings.json
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "LettuceEncrypt": "Trace"
    }
  },
  "LettuceEncrypt": {
    // Required: Accept the terms of service from the certificate authority
    "AcceptTermsOfService": true,

    // Required: At least one domain name for the certificate
    "DomainNames": [ "example.com", "www.example.com" ],

    // Required: Email address for certificate authority registration
    "EmailAddress": "admin@example.com",

    // Optional: Use staging server (defaults to true in Development environment)
    "UseStagingServer": false,

    // Optional: Challenge types - Http01, TlsAlpn01, Dns01, Any (default)
    "AllowedChallengeTypes": "Http01, TlsAlpn01",

    // Optional: Key algorithm - RS256, ES256 (default), ES384, ES512
    "KeyAlgorithm": "ES256",

    // Optional: External Account Binding credentials
    "EabCredentials": {
      "EabKeyId": "your-key-id",
      "EabKey": "your-key",
      "EabKeyAlg": "HS256"
    }
  }
}
```

--------------------------------

### Implement Custom Certificate Repository and Source in C#

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/README.md

Provides a framework for customizing how certificates are saved and loaded by implementing the `ICertificateRepository` and `ICertificateSource` interfaces. This allows for integration with various storage solutions beyond the default options.

```csharp
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
    }
}
```

--------------------------------

### Configure LettuceEncrypt in ASP.NET Core Minimal API

Source: https://context7.com/natemcmaster/lettuceencrypt/llms.txt

This snippet demonstrates how to register LettuceEncrypt services in a .NET 6+ Minimal API. It includes configuring certificate persistence to a directory and setting up the application to use HTTPS.

```csharp
using LettuceEncrypt;

var builder = WebApplication.CreateBuilder(args);

// Add LettuceEncrypt services
builder.Services.AddLettuceEncrypt()
    .PersistDataToDirectory(
        new DirectoryInfo("/var/ssl/certs"),
        pfxPassword: builder.Configuration["CertPassword"]
    );

var app = builder.Build();

app.UseHttpsRedirection();

app.MapGet("/", () => "Hello, HTTPS World!");
app.MapGet("/health", () => Results.Ok(new { Status = "Healthy" }));

app.Run();
```

```jsonc
{
  "Urls": "http://*:80;https://*:443",
  "CertPassword": "secure-password-from-keyvault",
  "LettuceEncrypt": {
    "AcceptTermsOfService": true,
    "DomainNames": [ "api.example.com" ],
    "EmailAddress": "devops@example.com",
    "UseStagingServer": false,
    "AllowedChallengeTypes": "Http01, TlsAlpn01",
    "RenewDaysInAdvance": "30.00:00:00",
    "RenewalCheckPeriod": "1.00:00:00"
  }
}
```

--------------------------------

### LettuceEncrypt Options Configuration via appsettings.json

Source: https://context7.com/natemcmaster/lettuceencrypt/llms.txt

Configure LettuceEncrypt options through the standard ASP.NET Core configuration system using the 'LettuceEncrypt' section in appsettings.json.

```APIDOC
## LettuceEncrypt Options Configuration via appsettings.json

### Description
Configure LettuceEncrypt options through the standard ASP.NET Core configuration system. The configuration section name is "LettuceEncrypt".

### Method
Configuration via `appsettings.json`

### Endpoint
N/A (Configuration file)

### Parameters
#### LettuceEncrypt Section:
- **AcceptTermsOfService** (bool) - Required - Must be `true` to accept the terms of service from the certificate authority.
- **DomainNames** (string[]) - Required - An array of domain names for which the certificate will be issued.
- **EmailAddress** (string) - Required - The email address for registration with the certificate authority.
- **UseStagingServer** (bool) - Optional - Whether to use the staging environment of the certificate authority. Defaults to `true` in the Development environment.
- **AllowedChallengeTypes** (string) - Optional - Comma-separated string of allowed ACME challenge types (e.g., "Http01", "TlsAlpn01", "Dns01"). Defaults to "Any".
- **KeyAlgorithm** (string) - Optional - The key algorithm to use for the certificate (e.g., "RS256", "ES256", "ES384", "ES512"). Defaults to "ES256".
- **EabCredentials** (object) - Optional - Credentials for External Account Binding.
  - **EabKeyId** (string) - Required if `EabCredentials` is used - The External Account Binding Key ID.
  - **EabKey** (string) - Required if `EabCredentials` is used - The External Account Binding Key.
  - **EabKeyAlg** (string) - Required if `EabCredentials` is used - The algorithm for the External Account Binding Key (e.g., "HS256").

### Request Example
```json
// appsettings.json
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "LettuceEncrypt": "Trace"
    }
  },
  "LettuceEncrypt": {
    "AcceptTermsOfService": true,
    "DomainNames": [ "example.com", "www.example.com" ],
    "EmailAddress": "admin@example.com",
    "UseStagingServer": false,
    "AllowedChallengeTypes": "Http01,TlsAlpn01",
    "KeyAlgorithm": "ES256",
    "EabCredentials": {
      "EabKeyId": "your-key-id",
      "EabKey": "your-key",
      "EabKeyAlg": "HS256"
    }
  }
}
```

### Response
N/A (Configuration file)

#### Response Example
N/A
```

--------------------------------

### Implement IDnsChallengeProvider for DNS-01 Validation

Source: https://context7.com/natemcmaster/lettuceencrypt/llms.txt

Demonstrates how to implement the IDnsChallengeProvider interface to handle DNS-01 challenges. This includes creating a provider class to add and remove TXT records and registering it in the dependency injection container.

```csharp
public class CloudflareDnsChallengeProvider : IDnsChallengeProvider
{
    private readonly ICloudflareClient _cloudflare;
    private readonly ILogger<CloudflareDnsChallengeProvider> _logger;
    public CloudflareDnsChallengeProvider(ICloudflareClient cloudflare, ILogger<CloudflareDnsChallengeProvider> logger) {
        _cloudflare = cloudflare;
        _logger = logger;
    }
    public async Task<DnsTxtRecordContext> AddTxtRecordAsync(string domainName, string txt, CancellationToken ct = default) {
        var recordId = await _cloudflare.CreateDnsTxtRecordAsync(domainName, txt, ttl: 60, ct);
        return new DnsTxtRecordContext(domainName, txt) { RecordId = recordId };
    }
    public async Task RemoveTxtRecordAsync(DnsTxtRecordContext context, CancellationToken ct = default) {
        await _cloudflare.DeleteDnsTxtRecordAsync(((CloudflareDnsTxtRecordContext)context).RecordId, ct);
    }
}

public class Startup {
    public void ConfigureServices(IServiceCollection services) {
        services.AddLettuceEncrypt(options => options.AllowedChallengeTypes = ChallengeType.Dns01);
        services.AddSingleton<IDnsChallengeProvider, CloudflareDnsChallengeProvider>();
    }
}
```

--------------------------------

### Integrate LettuceEncrypt with Kestrel - C#

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/README.md

This C# code illustrates how to integrate LettuceEncrypt with Kestrel when using the UseKestrel() method for configuration. It specifically shows how to call UseLettuceEncrypt within the ConfigureHttpsDefaults lambda, ensuring LettuceEncrypt is applied to HTTPS settings.

```csharp
webBuilder.UseKestrel(k =>
{
    var appServices = k.ApplicationServices;
    k.ConfigureHttpsDefaults(h =>
    {
        h.ClientCertificateMode = ClientCertificateMode.RequireCertificate;
        h.UseLettuceEncrypt(appServices);
    });
});
```

--------------------------------

### Key Algorithms

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/src/LettuceEncrypt/PublicAPI.Shipped.txt

Enumerates the supported key algorithms for certificate generation.

```APIDOC
## KeyAlgorithm

### Description
Specifies the key algorithm for generating cryptographic keys.

### Values
- **RS256** (0)
- **ES256** (1)
- **ES384** (2)
- **ES512** (3)
```

--------------------------------

### Enable LettuceEncrypt Trace Logging in appsettings.json

Source: https://github.com/natemcmaster/lettuceencrypt/wiki/Diagnosing-issues

This configuration snippet shows how to enable trace-level logging for LettuceEncrypt within an ASP.NET Core application's appsettings.json file. This increases the verbosity of logs, providing more detailed information for debugging. Ensure the 'LettuceEncrypt' logger is set to 'Trace' to capture all relevant events.

```json
{
  "Logging": {
    "LogLevel": {
      "LettuceEncrypt": "Trace"
    }
  }
}
```

--------------------------------

### LettuceEncrypt Options and Service Builder

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/src/LettuceEncrypt/PublicAPI.Shipped.txt

Configuration options for LettuceEncrypt and the service builder interface.

```APIDOC
## LettuceEncryptOptions

### Description
Configuration options for LettuceEncrypt.

### Properties
- **AcceptTermsOfService** (bool) - Whether to accept the terms of service.
- **AdditionalIssuers** (string[]) - Additional issuers to consider.
- **AllowedChallengeTypes** (ChallengeType) - The allowed challenge types.
- **DomainNames** (string[]) - The domain names for which to obtain certificates.
- **EabCredentials** (EabCredentials) - EAB credentials for account binding.
- **EmailAddress** (string) - The email address for account registration.
- **FallbackCertificate** (X509Certificate2?) - A fallback certificate to use.
- **KeyAlgorithm** (KeyAlgorithm) - The key algorithm to use for new keys.

## ILettuceEncryptServiceBuilder

### Description
Builder interface for configuring LettuceEncrypt services.

### Properties
- **Services** (IServiceCollection) - The service collection to add LettuceEncrypt services to.
```

--------------------------------

### Configure Allowed ACME Challenge Types

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/README.md

Demonstrates how to specify allowed challenge types in appsettings.json. The value can be a single type or a comma-separated list.

```json
{
    "LettuceEncrypt": {
        "AllowedChallengeTypes": "Http01, TlsAlpn01, Dns01"
    }
}
```

--------------------------------

### PersistCertificatesToAzureKeyVault Extension Methods

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/src/LettuceEncrypt.Azure/PublicAPI.Shipped.txt

Extension methods for `ILettuceEncryptServiceBuilder` to enable certificate persistence to Azure Key Vault.

```APIDOC
## PersistCertificatesToAzureKeyVault

### Description
Extension methods to configure LettuceEncrypt to save certificates to Azure Key Vault.

### Method 1: Default Configuration

#### Method
`static PersistCertificatesToAzureKeyVault(this LettuceEncrypt.ILettuceEncryptServiceBuilder! builder)`

#### Description
Configures LettuceEncrypt to use Azure Key Vault for certificate persistence with default settings.

### Method 2: Custom Configuration

#### Method
`static PersistCertificatesToAzureKeyVault(this LettuceEncrypt.ILettuceEncryptServiceBuilder! builder, System.Action<LettuceEncrypt.Azure.AzureKeyVaultLettuceEncryptOptions!>! configure)`

#### Description
Configures LettuceEncrypt to use Azure Key Vault for certificate persistence with custom settings provided via a configuration action.

#### Parameters
##### configure (System.Action<LettuceEncrypt.Azure.AzureKeyVaultLettuceEncryptOptions!>)
- **Required** - An action that configures the `AzureKeyVaultLettuceEncryptOptions`.
```

--------------------------------

### Persist Certificate Data to a Directory in C#

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/README.md

Configures LettuceEncrypt to persist generated certificates (PFX format) and account information to a specified directory. This method allows for local storage and retrieval of sensitive certificate data and account keys, secured with a password.

```csharp
using LettuceEncrypt;
using Microsoft.Extensions.DependencyInjection;

public void ConfigureServices(IServiceCollection services)
{
    services
        .AddLettuceEncrypt()
        .PersistDataToDirectory(new DirectoryInfo("C:/data/LettuceEncrypt/"), "Password123");
}
```

--------------------------------

### PersistDataToDirectory

Source: https://context7.com/natemcmaster/lettuceencrypt/llms.txt

Configures the application to save generated certificates and account data to a local file system directory.

```APIDOC
## PersistDataToDirectory

### Description
Enables persistence of PFX certificates and account data to a specified directory.

### Parameters
- **directory** (DirectoryInfo) - Required - The target directory for storage.
- **pfxPassword** (string) - Optional - Password for the PFX files; set to null for password-less files.

### Request Example
services.AddLettuceEncrypt().PersistDataToDirectory(new DirectoryInfo("/path/to/certs"), pfxPassword: "password");
```

--------------------------------

### UseLettuceEncrypt with Kestrel

Source: https://context7.com/natemcmaster/lettuceencrypt/llms.txt

Configures Kestrel to use LettuceEncrypt for automatic certificate management within the host builder.

```APIDOC
## UseLettuceEncrypt

### Description
Integrates LettuceEncrypt into Kestrel's HTTPS pipeline to automate certificate provisioning.

### Method
C# Extension Method

### Parameters
- **appServices** (IServiceProvider) - Required - The application service provider used to resolve LettuceEncrypt services.

### Request Example
webBuilder.UseKestrel(kestrel => { kestrel.ConfigureHttpsDefaults(https => { https.UseLettuceEncrypt(appServices); }); });
```

--------------------------------

### Configure LettuceEncrypt with Azure KeyVault

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/test/Integration/README.md

This C# code snippet demonstrates how to configure LettuceEncrypt to use Azure KeyVault for storing and retrieving SSL certificates. It requires specifying the Azure Key Vault endpoint. The 'PersistCertificatesToAzureKeyVault()' method ensures certificates are saved to the vault.

```csharp
public void ConfigureServices(IServiceCollection services)
{
    services.AddLettuceEncrypt()
        .AddAzureKeyVaultCertificateSource(o =>
        {
            o.AzureKeyVaultEndpoint = "https://[url].vault.azure.net/";
        })
        .PersistCertificatesToAzureKeyVault();
}
```

--------------------------------

### AddLettuceEncrypt

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/src/LettuceEncrypt/PublicAPI.Shipped.txt

Registers the LettuceEncrypt services in the dependency injection container.

```APIDOC
## AddLettuceEncrypt

### Description
Registers the necessary services for LettuceEncrypt into the IServiceCollection.

### Method
Extension Method

### Endpoint
Microsoft.Extensions.DependencyInjection.LettuceEncryptServiceCollectionExtensions.AddLettuceEncrypt

### Parameters
#### Request Body
- **services** (IServiceCollection) - Required - The service collection to add to.
- **configure** (Action<LettuceEncryptOptions>) - Optional - Configuration delegate for LettuceEncryptOptions.

### Response
Returns an ILettuceEncryptServiceBuilder instance for further configuration.
```

--------------------------------

### IDnsChallengeProvider Implementation

Source: https://context7.com/natemcmaster/lettuceencrypt/llms.txt

Defines the interface for handling DNS-01 challenges, allowing integration with external DNS providers to automate domain validation.

```APIDOC
## IDnsChallengeProvider Interface

### Description
Implement this interface to provide custom logic for adding and removing DNS TXT records required for ACME DNS-01 challenges.

### Methods
- **AddTxtRecordAsync(string domainName, string txt, CancellationToken ct)**: Adds a TXT record to the DNS provider.
- **RemoveTxtRecordAsync(DnsTxtRecordContext context, CancellationToken ct)**: Removes the previously added TXT record.

### Registration
```csharp
services.AddSingleton<IDnsChallengeProvider, YourCustomDnsProvider>();
```
```

--------------------------------

### Add LettuceEncrypt Service - ASP.NET Core

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/README.md

This snippet shows how to register LettuceEncrypt services within an ASP.NET Core application's ConfigureServices method. It requires the Microsoft.Extensions.DependencyInjection namespace and enables the core functionality of LettuceEncrypt.

```csharp
using Microsoft.Extensions.DependencyInjection;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddLettuceEncrypt();
    }
}
```

--------------------------------

### Certificate Repository and Source

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/src/LettuceEncrypt/PublicAPI.Shipped.txt

Interfaces for saving and retrieving certificates.

```APIDOC
## ICertificateRepository

### Description
Interface for persisting certificates.

### Methods
- **SaveAsync(X509Certificate2 certificate, CancellationToken cancellationToken)**: Saves a certificate asynchronously.

## ICertificateSource

### Description
Interface for retrieving certificates.

### Methods
- **GetCertificatesAsync(CancellationToken cancellationToken)**: Retrieves certificates asynchronously.
```

--------------------------------

### AzureKeyVaultLettuceEncryptOptions Configuration

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/src/LettuceEncrypt.Azure/PublicAPI.Shipped.txt

Configuration options for persisting certificates to Azure Key Vault.

```APIDOC
## AzureKeyVaultLettuceEncryptOptions

### Description
Provides configuration settings for storing certificates in Azure Key Vault.

### Properties
- **Credentials** (Azure.Core.TokenCredential?) - The credentials to authenticate with Azure Key Vault. Optional.
- **AzureKeyVaultEndpoint** (string!) - The URL endpoint of the Azure Key Vault.
- **AccountKeySecretName** (string?) - The name of the secret in Azure Key Vault where the account key is stored. Optional.
```

--------------------------------

### UseLettuceEncrypt

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/src/LettuceEncrypt/PublicAPI.Shipped.txt

Configures Kestrel to use LettuceEncrypt for HTTPS certificate management.

```APIDOC
## UseLettuceEncrypt

### Description
Configures the Kestrel HttpsConnectionAdapterOptions to use LettuceEncrypt for automatic certificate management.

### Method
Extension Method

### Endpoint
Microsoft.AspNetCore.Hosting.LettuceEncryptKestrelHttpsOptionsExtensions.UseLettuceEncrypt

### Parameters
#### Request Body
- **httpsOptions** (HttpsConnectionAdapterOptions) - Required - The Kestrel HTTPS options.
- **applicationServices** (IServiceProvider) - Required - The application service provider.

### Response
Returns the modified HttpsConnectionAdapterOptions.
```

--------------------------------

### Persist LettuceEncrypt Data to Local Directory

Source: https://context7.com/natemcmaster/lettuceencrypt/llms.txt

Configures LettuceEncrypt to save generated certificates (PFX format) and account information to a specified directory on the file system. This ensures certificate persistence across application restarts. It supports both password-protected and password-less PFX files.

```csharp
using LettuceEncrypt;
using Microsoft.Extensions.DependencyInjection;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services
            .AddLettuceEncrypt()
            .PersistDataToDirectory(
                new DirectoryInfo("/var/ssl/certs"),
                pfxPassword: "SecurePassword123!"
            );

        // Password-less PFX files
        services
            .AddLettuceEncrypt()
            .PersistDataToDirectory(
                new DirectoryInfo("C:/data/LettuceEncrypt/"),
                pfxPassword: null
            );
    }
}
```

--------------------------------

### ICertificateAuthorityConfiguration Implementation

Source: https://context7.com/natemcmaster/lettuceencrypt/llms.txt

Defines the interface for configuring custom ACME-compatible Certificate Authorities, enabling the use of providers other than Let's Encrypt.

```APIDOC
## ICertificateAuthorityConfiguration Interface

### Description
Implement this interface to specify the ACME directory URI and issuer certificates for a custom Certificate Authority.

### Properties
- **AcmeDirectoryUri (Uri)**: The base URL for the ACME directory of the CA.
- **IssuerCertificates (string[])**: Optional array of issuer certificates for chain verification.

### Registration
```csharp
services.AddSingleton<ICertificateAuthorityConfiguration, YourCustomCAConfiguration>();
```
```

--------------------------------

### PersistDataToDirectory

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/src/LettuceEncrypt/PublicAPI.Shipped.txt

Configures the storage provider to save certificates to a specific directory.

```APIDOC
## PersistDataToDirectory

### Description
Configures the LettuceEncrypt service to persist certificate data to a specified directory on the file system.

### Method
Extension Method

### Endpoint
LettuceEncrypt.FileSystemStorageExtensions.PersistDataToDirectory

### Parameters
#### Request Body
- **builder** (ILettuceEncryptServiceBuilder) - Required - The service builder.
- **directory** (DirectoryInfo) - Required - The target directory for storage.
- **pfxPassword** (string) - Optional - Password for PFX files.

### Response
Returns the ILettuceEncryptServiceBuilder.
```

--------------------------------

### AddLettuceEncrypt - Service Registration

Source: https://context7.com/natemcmaster/lettuceencrypt/llms.txt

Registers LettuceEncrypt services with the dependency injection container. This is the primary entry point for enabling automatic HTTPS certificate generation. It can be configured with default settings or custom options.

```APIDOC
## AddLettuceEncrypt - Service Registration

### Description
Registers the LettuceEncrypt services with the dependency injection container. This is the primary entry point for enabling automatic HTTPS certificate generation. By default, it uses Let's Encrypt as the certificate authority.

### Method
`services.AddLettuceEncrypt()`

### Parameters
None

### Request Example
```csharp
using Microsoft.Extensions.DependencyInjection;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        // Basic registration - uses configuration from appsettings.json
        services.AddLettuceEncrypt();
    }
}
```

## AddLettuceEncrypt with Options

### Description
Configures LettuceEncrypt with specific options during service registration.

### Method
`services.AddLettuceEncrypt(options => { ... })`

### Parameters
- **options** (LettuceEncryptOptions) - An object to configure various settings like domain names, email, staging server usage, renewal periods, key algorithm, and challenge types.

### Request Example
```csharp
using Microsoft.Extensions.DependencyInjection;

public class StartupWithOptions
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddLettuceEncrypt(options =>
        {
            options.AcceptTermsOfService = true;
            options.DomainNames = new[] { "example.com", "www.example.com" };
            options.EmailAddress = "admin@example.com";
            options.UseStagingServer = false; // Use production Let's Encrypt
            options.RenewDaysInAdvance = TimeSpan.FromDays(30);
            options.RenewalCheckPeriod = TimeSpan.FromDays(1);
            options.KeyAlgorithm = KeyAlgorithm.ES256; // ECDSA P-256
            options.AllowedChallengeTypes = ChallengeType.Http01 | ChallengeType.TlsAlpn01;
        });
    }
}
```
```

--------------------------------

### Kestrel HTTPS Options Extension

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/src/Kestrel.Certificates/PublicAPI.Shipped.txt

Provides an extension method to configure Kestrel HTTPS options with a custom server certificate selector.

```APIDOC
## Microsoft.AspNetCore.Hosting.KestrelHttpsOptionsExtensions.UseServerCertificateSelector

### Description
An extension method for `HttpsConnectionAdapterOptions` that allows setting a custom `IServerCertificateSelector`.

### Method
`UseServerCertificateSelector(this HttpsConnectionAdapterOptions httpsOptions, IServerCertificateSelector certificateSelector)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```csharp
// Assuming 'httpsOptions' is an instance of HttpsConnectionAdapterOptions
// and 'myCertificateSelector' is an instance of IServerCertificateSelector
httpsOptions.UseServerCertificateSelector(myCertificateSelector);
```

### Response
#### Success Response (200)
- **HttpsConnectionAdapterOptions**: The modified `HttpsConnectionAdapterOptions` object.

#### Response Example
```json
// No direct JSON response, modifies the options object in place.
```

### Error Handling
- Throws `ArgumentNullException` if `httpsOptions` or `certificateSelector` is null.
```

--------------------------------

### Certificate Authority Configuration and Credentials

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/src/LettuceEncrypt/PublicAPI.Shipped.txt

Defines the configuration for certificate authorities and reusable EAB credentials.

```APIDOC
## ICertificateAuthorityConfiguration

### Description
Configuration for a certificate authority (CA).

### Properties
- **AcmeDirectoryUri** (Uri) - The ACME directory endpoint URI.
- **IssuerCertificates** (string[]) - Certificates used to issue new certificates.

## EabCredentials

### Description
Credentials for External Account Binding (EAB).

### Properties
- **EabKey** (string?) - The EAB key.
- **EabKeyAlg** (string?) - The algorithm used for the EAB key.
- **EabKeyId** (string?) - The ID of the EAB key.
```

--------------------------------

### Persist LettuceEncrypt Certificates to Azure Key Vault

Source: https://context7.com/natemcmaster/lettuceencrypt/llms.txt

Integrates LettuceEncrypt with Azure Key Vault to store certificates and account information. This requires the LettuceEncrypt.Azure NuGet package. It can be configured using appsettings.json or directly within the code, allowing for custom endpoints and credentials.

```csharp
using LettuceEncrypt;
using LettuceEncrypt.Azure;
using Microsoft.Extensions.DependencyInjection;
using Azure.Identity;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        // Basic usage - configuration from appsettings.json
        services
            .AddLettuceEncrypt()
            .PersistCertificatesToAzureKeyVault();

        // With inline configuration
        services
            .AddLettuceEncrypt()
            .PersistCertificatesToAzureKeyVault(options =>
            {
                options.AzureKeyVaultEndpoint = "https://mykeyvault.vault.azure.net/";
                options.AccountKeySecretName = "lets-encrypt-account";
                options.Credentials = new DefaultAzureCredential();
            });
    }
}
```

```json
// appsettings.json for Azure Key Vault
{
  "LettuceEncrypt": {
    "AcceptTermsOfService": true,
    "DomainNames": [ "example.com" ],
    "EmailAddress": "admin@example.com",
    "AzureKeyVault": {
      "AzureKeyVaultEndpoint": "https://mykeyvault.vault.azure.net/",
      "AccountKeySecretName": "le-encrypt-account"
    }
  }
}
```

--------------------------------

### PersistCertificatesToAzureKeyVault

Source: https://context7.com/natemcmaster/lettuceencrypt/llms.txt

Configures the application to store certificates and account information in Azure Key Vault.

```APIDOC
## PersistCertificatesToAzureKeyVault

### Description
Offloads certificate storage to Azure Key Vault for improved security and centralized management.

### Parameters
- **options** (Action<AzureKeyVaultOptions>) - Optional - Configuration delegate for Key Vault endpoint and credentials.

### Request Example
services.AddLettuceEncrypt().PersistCertificatesToAzureKeyVault(options => { options.AzureKeyVaultEndpoint = "https://vault.url"; });
```

--------------------------------

### IServerCertificateSelector Interface

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/src/Kestrel.Certificates/PublicAPI.Shipped.txt

Defines a contract for selecting an X.509 certificate based on the connection context and domain name.

```APIDOC
## McMaster.AspNetCore.Kestrel.Certificates.IServerCertificateSelector

### Description
An interface for selecting an appropriate server certificate.

### Method
`Select(ConnectionContext context, string? domainName)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **X509Certificate2?**: The selected server certificate, or null if no suitable certificate is found.

#### Response Example
```json
null
```

### Error Handling
- Returns null if no certificate can be selected for the given domain name.
```

--------------------------------

### Account Management

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/src/LettuceEncrypt/PublicAPI.Shipped.txt

Defines the AccountModel and the IAccountStore interface for managing account information.

```APIDOC
## AccountModel

### Description
Represents an account within the LettuceEncrypt system, storing email addresses, account ID, and private key.

### Properties
- **EmailAddresses** (string[]) - Gets or sets the email addresses associated with the account.
- **Id** (int) - Gets or sets the unique identifier for the account.
- **PrivateKey** (byte[]) - Gets or sets the private key for the account.

## IAccountStore

### Description
Interface for storing and retrieving account information.

### Methods
- **GetAccountAsync(CancellationToken cancellationToken)**: Retrieves the account information asynchronously.
- **SaveAccountAsync(AccountModel account, CancellationToken cancellationToken)**: Saves the account information asynchronously.
```

--------------------------------

### ACME Challenge Types and Providers

Source: https://github.com/natemcmaster/lettuceencrypt/blob/main/src/LettuceEncrypt/PublicAPI.Shipped.txt

Details the available ACME challenge types and the interface for DNS challenge providers.

```APIDOC
## ChallengeType

### Description
Enumerates the types of challenges supported by ACME.

### Values
- **Any** (65535)
- **Http01** (1)
- **TlsAlpn01** (2)
- **Dns01** (4)

## DnsTxtRecordContext

### Description
Contextual information for a DNS TXT record used in challenges.

### Properties
- **DomainName** (string) - The domain name for the TXT record.
- **Txt** (string) - The TXT record value.

## IDnsChallengeProvider

### Description
Interface for providers that can manage DNS TXT records for challenges.

### Methods
- **AddTxtRecordAsync(string domainName, string txt, CancellationToken ct = default)**: Adds a TXT record to the DNS.
- **RemoveTxtRecordAsync(DnsTxtRecordContext context, CancellationToken ct = default)**: Removes a TXT record from the DNS.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.