Eigenverft.NetLib.Security.Certificates 1.0.0.5

Eigenverft.NetLib.Security.Certificates

Create self-signed X.509 certificates and load PFX files with an explicit, policy-controlled recovery behavior.

✨ At a glance

📦 Installation

dotnet add package Eigenverft.NetLib.Security.Certificates

🚀 Quick start

Load a managed certificate and generate a replacement only when the PFX is missing or expired:

using System;
using System.IO;
using System.Security.Cryptography.X509Certificates;
using Eigenverft.NetLib.Security.Certificates;

string password = Environment.GetEnvironmentVariable("APP_PFX_PASSWORD")
    ?? throw new InvalidOperationException("APP_PFX_PASSWORD is required.");

ManagedCertificateResult managed = ManagedCertificateFile.LoadOrCreate(
    new ManagedCertificateFileOptions
    {
        FilePath = Path.Combine(AppContext.BaseDirectory, "certs", "worker.pfx"),
        Password = password,
        RecoveryMode = CertificateRecoveryMode.ReplaceExpired,
        Replacement = new SelfSignedCertificateOptions
        {
            Subject = new CertificateSubject { CommonName = "worker.example" },
            Purpose = CertificatePurpose.TlsServer,
            DnsNames = new[] { "worker.example" },
        },
    });

using X509Certificate2 certificate = managed.Certificate;
Console.WriteLine($"{managed.Action}; persisted: {managed.Persisted}");

ManagedCertificateResult.Certificate is caller-owned and must be disposed. Use SelfSignedCertificateFactory.Create(...) directly when the application does not need a managed-file lifecycle.

🔐 Certificate and recovery behavior

SelfSignedCertificateFactory supports TLS server/client, code-signing, and email-protection purposes. Profiles include RSA 2048/3072 with SHA-256 and ECDSA P-256/SHA-256 or P-384/SHA-384. TLS server certificates require at least one DNS or IP subject alternative name.

PreserveExisting is the default recovery mode: a generated certificate is returned in memory, and the configured PFX path is not created or replaced. ReplaceExpired creates a missing PFX and replaces only an existing, successfully imported expired PFX. ReplaceAnyUnusable can overwrite existing files that fail import, password, read, or access checks, so it must not be used casually with externally managed credentials. None disables recovery and requires an existing, currently valid PFX with a private key.

Self-signed certificates are not automatically trusted by clients. Protect the PFX path and password using the application's deployment controls; this library does not configure filesystem ACLs or establish a certificate trust chain.

🔗 Related packages

The WebLib Kestrel.Sni package consumes these certificate helpers for configuration-driven SNI certificates; this package does not depend on Kestrel or ASP.NET Core. Hosting.DirectoryLayout offers a conventional AppCerts path, but certificate loading accepts an explicit file path. Machine binding and Data Protection are separate value/key-ring mechanisms: neither is applied automatically to PFX files by this package.

🎯 Target frameworks

• net8.0
• net10.0

🔗 Project links

• Source project
• Solution documentation
• Repository

📄 License

MIT