Egov.Extensions.Configuration 10.0.4

Egov.Extensions.Configuration

A .NET library that provides helpers for certificate loading and configuring IOptions<SystemCertificateOptions> in ASP.NET Core 10.0+ applications. It serves as a shared foundation for certificate management in services built on the eGov platform.

Table of Contents

• Features
• Prerequisites
• Installation
• Configuration
• Usage
  • Dependency Injection (Recommended)
  • CertificateLoader Directly
  • CertificateConverter (TypeConverter)
• Supported Certificate Formats
• Error Handling
• Testing
• Contributing
• Code of Conduct
• AI Assistance
• License

Features

• Load public certificates from CER/CRT files
• Load private certificates from PFX/PKCS#12 files
• Load certificates from Kubernetes TLS secrets (tls.crt / tls.key)
• Load full certificate chains including intermediate certificates
• Register certificates via ASP.NET Core Dependency Injection
• TypeConverter support for binding certificates directly from configuration strings

Prerequisites

• .NET 10.0 or later
• A valid certificate file (PFX, CER, or PEM format)
• Certificate password if the certificate is password-protected
• For Kubernetes deployments: certificates mounted as TLS secrets with tls.crt and tls.key files

Installation

Install the package from NuGet:

dotnet add package Egov.Extensions.Configuration

Or via the Package Manager Console:

Install-Package Egov.Extensions.Configuration

Configuration

Add the following section to your appsettings.json:

{
  "Certificate": {
    "Path": "Files/Certificates/your-certificate.pfx",
    "Password": "your-certificate-password"
  }
}

Path can be:

• A path to a PFX file (requires Password if encrypted)
• A path to a CER/CRT file (public certificate only)
• A path to a directory containing tls.crt and tls.key files (Kubernetes mounted secret)

Password is optional and only required for encrypted PFX files or encrypted PEM private keys.

Usage

Using Dependency Injection (Recommended)

Register the certificate in Program.cs:

builder.Services.AddSystemCertificate(builder.Configuration.GetSection("Certificate"));

Or configure it inline:

builder.Services.AddSystemCertificate(options =>
{
    options.Path = "Files/Certificates/your-certificate.pfx";
    options.Password = "your-certificate-password";
});

Then inject IOptions<SystemCertificateOptions> into your services:

public class MyService
{
    private readonly SystemCertificateOptions _certificateOptions;

    public MyService(IOptions<SystemCertificateOptions> certificateOptions)
    {
        _certificateOptions = certificateOptions.Value;
    }

    public void UseCertificate()
    {
        var certificate = _certificateOptions.Certificate;
        // Use the certificate...
    }
}

The SystemCertificateOptions also exposes IntermediateCertificates when the loaded certificate chain contains intermediate certificates.

Using CertificateLoader Directly

You can use the CertificateLoader static class without dependency injection.

Load a public certificate (CER/CRT):

var certificate = CertificateLoader.Public("path/to/certificate.cer");

Load a private certificate (PFX):

var certificate = CertificateLoader.Private("path/to/certificate.pfx", "password");

Load from a Kubernetes mounted secret:

var certificate = CertificateLoader.Private("/etc/ssl/certs/my-secret", null);

Load a full chain (certificate + intermediates):

var certificate = CertificateLoader.PrivateChain(
    "path/to/certificate.pfx",
    "password",
    out X509Certificate2Collection? intermediates);

Using CertificateConverter

CertificateConverter is a TypeConverter that allows binding an X509Certificate2 directly from a configuration string.

Register it once at application startup:

CertificateConverter.Register();

After registration, configuration strings are automatically converted:

• "path/to/cert.cer" → loads a public certificate
• "path/to/cert.pfx|password" → loads a private certificate (path and password separated by |)

Supported Certificate Formats

Error Handling

Testing

The solution includes a dedicated test project Egov.Extensions.Configuration.Tests built with xUnit v3.

Test coverage

Test certificates

The test project ships self-signed test certificates under TestCertificates/:

These files are automatically copied to the build output directory by the project file and are not intended for production use.

Running the tests

dotnet test src/Egov.Extensions.Configuration.Tests

Or from the solution root:

dotnet test

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines on how to get started.

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

AI Assistance

This repository contains an AGENTS.md file with instructions and context for AI coding agents to assist in development, ensuring consistency in code style and project structure.

License

This project is licensed under the MIT License.