FluentCertificates.Builder 0.12.0

There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package FluentCertificates.Builder --version 0.12.0
                    
NuGet\Install-Package FluentCertificates.Builder -Version 0.12.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="FluentCertificates.Builder" Version="0.12.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="FluentCertificates.Builder" Version="0.12.0" />
                    
Directory.Packages.props
<PackageReference Include="FluentCertificates.Builder" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add FluentCertificates.Builder --version 0.12.0
                    
#r "nuget: FluentCertificates.Builder, 0.12.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#addin nuget:?package=FluentCertificates.Builder&version=0.12.0
                    
Install FluentCertificates.Builder as a Cake Addin
#tool nuget:?package=FluentCertificates.Builder&version=0.12.0
                    
Install FluentCertificates.Builder as a Cake Tool

📖 FluentCertificates Overview

⚠️ Note: while version numbers are v0.x.y, this software is under initial development and there there may be breaking-changes in its API between minor versions. ⚠️

NuGet Build & Publish GitHub license

FluentCertificates is a library using the Immutable Fluent Builder pattern for easily creating, finding, and exporting certificates. It makes it simple to generate your own certificate chains or just stand-alone self-signed certificates.

NuGet Packages

This project is published in several NuGet packages:

Documentation is incomplete. More examples can be found in the project's unit tests.

CertificateBuilder Examples

CertificateBuilder requires the FluentCertificates.Builder package and is found under the FluentCertificates namespace.

Minimum Example

The absolute minimum needed to create a certificate, whether it's useful or not.

using var cert = new CertificateBuilder().Create();

Create a Certificate Signing Request

For signing, exporting and passing to a 3rd party CA.

//A public & private keypair must be created first, outside of the CertificateBuilder, otherwise you'd have no way to retrieve the private-key used for the new CertificateSigningRequest object
using var keys = RSA.Create();

//Creating a CertificateSigningRequest
var csr = new CertificateBuilder()
    .SetUsage(CertificateUsage.Server)
    .SetSubject(b => b.SetCommonName("*.fake.domain"))
    .SetSubjectAlternativeNames(x => x.AddDnsNames("*.fake.domain", "fake.domain"))
    .SetKeyPair(keys)
    .CreateCertificateSigningRequest();

//The CertificateRequest object is accessible here:
var certRequest = csr.CertificateRequest;

//CSR can be exported to a string
Console.WriteLine(csr.ToPemString());

//Or to a file or StringWriter instance
csr.ExportAsPem("csr.pem");

Build a Self-Signed Web Server Certificate

Using the fluent style:

using var webCert = new CertificateBuilder()
    .SetFriendlyName("Example self-signed web-server certificate")
    .SetUsage(CertificateUsage.Server)
    .SetSubject(b => b.SetCommonName("*.fake.domain"))
    .SetSubjectAlternativeNames(x => x.AddDnsNames("*.fake.domain", "fake.domain"))
    .SetNotAfter(DateTimeOffset.UtcNow.AddMonths(1))
    .Create();

Or alternatively using object initializers (other examples will use fluent style from now on though):

var builder = new CertificateBuilder() {
    FriendlyName = "Example self-signed web-server certificate",
    Usage = CertificateUsage.Server,
    Subject = new X500NameBuilder().SetCommonName("*.fake.domain"),
    SubjectAlternativeNames = new GeneralNameListBuilder().AddDnsNames("*.fake.domain", "fake.domain"),
    NotAfter = DateTimeOffset.UtcNow.AddMonths(1)
};
using var webCert = builder.Create();

Build a Certificate Authority (CA)

//A CA's expiry date must be later than that of any certificates it will issue
using var issuer = new CertificateBuilder()
    .SetFriendlyName("Example root CA")
    .SetUsage(CertificateUsage.CA)
    .SetSubject(b => b.SetCommonName("Example root CA"))
    .SetNotAfter(DateTimeOffset.UtcNow.AddYears(100))
    .Create();

Build a Client-Auth Certificate Signed by a CA

//Note: the 'issuer' certificate used must have a private-key attached in order to sign this new certificate
using var clientAuthCert = new CertificateBuilder()
    .SetFriendlyName("Example client-auth certificate")
    .SetUsage(CertificateUsage.Client)
    .SetSubject(b => b.SetCommonName("User: Michael"))
    .SetNotAfter(DateTimeOffset.UtcNow.AddYears(1))
    .SetIssuer(issuer)
    .Create();

Advanced: Certificate with Customized Extensions

using var customCert = new CertificateBuilder()
    .SetFriendlyName("Example certificate with customized extensions")
    .SetSubject(b => b.SetCommonName("Example certificate with customized extensions"))
    .AddExtension(new X509BasicConstraintsExtension(false, false, 0, true))
    .AddExtension(new X509KeyUsageExtension(X509KeyUsageFlags.DigitalSignature | X509KeyUsageFlags.KeyEncipherment | X509KeyUsageFlags.DataEncipherment, true))
    .AddExtension(new X509EnhancedKeyUsageExtension(new OidCollection { new Oid(Oids.AnyExtendedKeyUsage) }, false))
    .SetIssuer(issuer)
    .Create();

Advanced: Certificates with Custom Name Constraints and CRL Distribution Points

//Permit the CA cert to issue certificates for specific names and IP addresses
var permittedNames = new GeneralNameListBuilder()
    .AddDnsName(".mydomain.local")
    .AddEmailAddress("@mydomain.local")
    .AddIPAddress(ipAddress: "192.168.0.0", subnetMask: "255.255.255.0")
    .Create();

using var issuer = new CertificateBuilder()
    .SetFriendlyName("Example constrained root CA")
    .SetUsage(CertificateUsage.CA)
    .SetSubject(b => b.SetCommonName("Example constrained root CA"))
    .SetNotAfter(DateTimeOffset.UtcNow.AddMonths(1))
    .SetPathLength(1)
    .AddExtension(new X509NameConstraintExtension(permittedNames, null))
    .Create();

using var webCert = new CertificateBuilder()
    .SetFriendlyName("Example certificate with a CRL distribution point")
    .SetUsage(CertificateUsage.Server)
    .SetIssuer(issuer)
    .SetSubject(b => b.SetCommonName("*.mydomain.local"))
    .SetSubjectAlternativeNames(x => x.AddDnsName("*.mydomain.local"))
    //Extension specifies CRL URLs
    .AddExtension(CertificateRevocationListBuilder.BuildCrlDistributionPointExtension([$"http://crl.mydomain.local/"]))
    .Create();

CertificateFinder Examples

CertificateFinder requires the FluentCertificates.Finder package and is found under the FluentCertificates namespace.

The CertificateFinder class allows you to configure, add, and query certificate sources (stores and directories) in a fluent and immutable manner. It supports LINQ queries for flexible certificate searching.

Find a Specific Certificate by Thumbprint

The "common stores" include the CurrentUser and LocalMachine certificate stores, such as "My", "Root", "CA", etc. You can also add custom directories or other X509 stores to search for certificates.

const string thumbprint = "622A2B8374D9BBE3969B91EDBC8F5152783AFC78";

var cert = new CertificateFinder()
    .AddCommonStores()
    .FirstOrDefault(x => x.Certificate.Thumbprint.Equals(thumbprint, StringComparison.OrdinalIgnoreCase));

Find a Valid Certificate with Matching Subject, Giving Preference to Included Private Keys

var subject = new X500NameBuilder()
    .SetOrganization("My Org")
    .SetCountry("AU")
    .SetCommonName("fake.domain");

var cert = new CertificateFinder()
    .AddCommonStores()
    .Select(x => x.Certificate)
    .Where(x => x.IsValidNow())
    .OrderBy(x => !x.HasPrivateKey) //Ensure certs with private keys are listed before those without
    .FirstOrDefault(x => subject.EquivalentTo(x.SubjectName, false));

X500NameBuilder Examples

X500NameBuilder requires the FluentCertificates.Builder package and is found under the FluentCertificates namespace.

TODO: document this; see unit tests for more examples


X509Certificate2 Extension Methods

These extension methods require the FluentCertificates.Builder package and are found under the FluentCertificates namespace.

TODO: document these; see unit tests for more examples

Extension-Method Description
BuildChain
ExportAsCert
ExportAsPkcs12
ExportAsPkcs7
ExportAsPem
ToPemString
ToBase64String
GetPrivateKey
GetSignatureData
GetToBeSignedData
IsValidNow
IsValid
IsSelfSigned
IsIssuedBy

X509Chain Extension Methods

These extension methods require the FluentCertificates.Builder package and are found under the FluentCertificates namespace.

TODO: document these

Extension-Method Description
ToCollection
ToEnumerable
ExportAsPkcs7
ExportAsPkcs12
ExportAsPem
ToPemString

X509Certificate2Collection Extension Methods

These extension methods require the FluentCertificates.Builder package and are found under the FluentCertificates namespace.

TODO: document these

Extension-Method Description
ToEnumerable
ExportAsPkcs7
ExportAsPkcs12
ExportAsPem
ToPemString

IEnumerable<X509Certificate2> Extension Methods

These extension methods require the FluentCertificates.Builder package and are found under the FluentCertificates namespace.

TODO: document these

Extension-Method Description
ToCollection
FilterPrivateKeys
ExportAsPkcs7
ExportAsPkcs12
ExportAsPem
ToPemString

AsymmetricAlgorithm Extension Methods

These extension methods require the FluentCertificates.Builder package and are found under the FluentCertificates namespace.

TODO: document these

Extension-Method Description
ToPrivateKeyPemString
ToPublicKeyPemString
ExportAsPrivateKeyPem
ExportAsPublicKeyPem

CertificateRequest Extension Methods

These extension methods require the FluentCertificates.Builder package and are found under the FluentCertificates namespace.

Extension-Method Description
ToPemString() Exports the CertificateRequest to a PEM string.
ExportAsPem(string path) Exports the CertificateRequest to the specified PEM file.
ExportAsPem(TextWriter writer) Exports the CertificateRequest in PEM format to the given TextWriter.
ConvertToBouncyCastle() Converts the CertificateRequest to a BouncyCastle Pkcs10CertificationRequest

X509Extension Extension Methods

These extension methods require the FluentCertificates.Builder package and are found under the FluentCertificates namespace.

Extension-Method Description
dnExtension.ConvertToBouncyCastle() Converts a DotNet X509Extension to a BouncyCastle X509Extension.
bcExtension.ConvertToDotNet(string oid) Converts a BouncyCastle X509Extension to a DotNet X509Extension. A DotNet X509Extension includes an OID, but a BouncyCastle one doesn't, therefore one must be supplied in the parameters here.
bcExtension.ConvertToDotNet(DerObjectIdentifier oid) Converts a BouncyCastle X509Extension to a DotNet X509Extension. A DotNet X509Extension includes an OID, but a BouncyCastle one doesn't, therefore one must be supplied in the parameters here.
Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on FluentCertificates.Builder:

Package Downloads
FluentCertificates

FluentCertificates is a library using the Immutable Fluent Builder pattern for easily creating, finding/querying and exporting certificates.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
0.12.1-ci0005 9 6/4/2025
0.12.1-ci0004 9 6/4/2025
0.12.1-ci0002 9 6/4/2025
0.12.1-ci0001 34 6/3/2025
0.12.0 51 6/3/2025
0.11.1-ci0007 54 6/3/2025
0.11.0 137 5/30/2025
0.10.1-ci0019 130 5/29/2025
0.10.1-ci0018 128 5/29/2025
0.10.1-ci0017 133 5/29/2025
0.10.1-ci0016 136 5/29/2025
0.10.1-ci0010 128 5/29/2025
0.10.1-ci0008 129 5/28/2025
0.10.1-ci0001 105 11/29/2024
0.10.0 1,236 11/28/2024
0.9.2-ci0009 89 11/28/2024
0.9.2-ci0008 94 11/28/2024
0.9.2-ci0006 90 11/27/2024
0.9.2-ci0004 91 11/27/2024
0.9.2-ci0002 134 2/19/2024
0.9.1 4,367 8/11/2023
0.9.1-ci0017 200 8/11/2023
0.9.1-ci0007 215 8/11/2023
0.9.1-ci0006 210 8/11/2023
0.9.0 253 8/10/2023
0.8.1-ci0031 219 8/10/2023
0.8.1-ci0028 187 8/2/2023
0.8.1-ci0027 206 8/2/2023
0.8.1-ci0025 174 8/2/2023
0.8.1-ci0020 208 8/1/2023
0.8.1-ci0018 191 8/1/2023
0.8.1-ci0016 187 8/1/2023
0.8.0 2,359 7/7/2022
0.7.2-ci0010 249 7/7/2022
0.7.2-ci0002 272 7/6/2022
0.7.2-ci0001 253 7/6/2022
0.7.1 721 6/24/2022
0.7.1-ci0001 244 6/24/2022
0.7.0 715 6/24/2022
0.6.1-ci0002 260 6/24/2022
0.6.1-ci0001 241 6/24/2022
0.6.0 722 6/23/2022
0.5.5-ci0009 234 6/23/2022
0.5.5-ci0008 204 6/23/2022
0.5.5-ci0007 243 6/23/2022
0.5.5-ci0006 251 6/23/2022
0.5.5-ci0005 222 6/23/2022
0.5.5-ci0004 245 6/21/2022
0.5.4 692 6/20/2022
0.5.4-ci0002 254 6/20/2022
0.5.3 693 6/20/2022
0.5.3-ci0005 245 6/20/2022
0.5.3-ci0004 228 6/20/2022
0.5.3-ci0003 213 6/20/2022
0.5.2 739 6/18/2022
0.5.2-ci0001 245 6/18/2022
0.5.1 712 6/17/2022
0.5.1-ci0001 219 6/17/2022
0.5.0 669 6/17/2022
0.4.2-ci0022 237 6/17/2022
0.4.2-ci0021 228 6/17/2022
0.4.2-ci0020 210 6/17/2022
0.4.2-ci0018 214 6/17/2022
0.4.2-ci0014 227 6/16/2022
0.4.2-ci0013 237 6/16/2022
0.4.2-ci0012 250 6/16/2022
0.4.2-ci0011 236 6/16/2022
0.4.2-ci0010 216 6/16/2022
0.4.2-ci0009 226 6/16/2022
0.4.2-ci0007 253 6/16/2022
0.4.2-ci0003 251 6/15/2022
0.4.2-ci0002 261 6/15/2022
0.4.2-ci0001 265 6/10/2022
0.4.1 704 6/10/2022
0.4.1-ci0008 245 6/10/2022
0.4.1-ci0007 251 6/10/2022
0.4.1-ci0006 246 6/10/2022
0.4.1-ci0005 234 6/10/2022
0.4.1-ci0004 222 6/10/2022
0.4.1-ci0003 258 6/10/2022
0.4.1-ci0002 218 6/8/2022
0.4.1-ci0001 257 6/8/2022
0.4.0 707 6/2/2022
0.3.3-ci0001 238 6/2/2022
0.3.2 709 6/2/2022
0.3.2-ci0002 249 5/31/2022
0.3.2-ci.1 147 5/30/2022