A majority of code in this project has been copied from Microsoft's open-source dotnet Git repository under the MIT license. It back-fills core .NET functionality which FluentCertificates relies on, but are missing in earlier versions of .NET.
$ dotnet add package FluentCertificates.Polyfills⚠️ Note: while version numbers are v0.x.y, this software is under initial development and there'll be breaking-changes in its API from version to version.
FluentCertificates is a library using the Immutable Fluent Builder pattern for easily creating, finding and exporting certificates. Makes it simple to generate your own certificate chains, or just stand-alone self-signed certificates.
This project is published in several NuGet packages:
CertificateBuilder for building certificates and also includes a bunch of convenient extension-methods. Examples belowCertificateFinder for finding certificates across a collection of X509Stores. Examples belowUnfortunately documentation is incomplete. You may find more examples within the project's unit tests.
CertificateBuilder examplesCertificateBuilder requires the FluentCertificates.Builder package and is found under the FluentCertificates namespace.
using var cert = new CertificateBuilder().Create();CertificateSigningRequest 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"))
.SetDnsNames("*.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");//Using a fluent style
using var cert = new CertificateBuilder()
.SetUsage(CertificateUsage.Server)
.SetFriendlyName("Example self-signed web-server certificate")
.SetSubject(b => b.SetCommonName("*.fake.domain"))
.SetDnsNames("*.fake.domain", "fake.domain")
.SetNotAfter(DateTimeOffset.UtcNow.AddMonths(1))
.Create();
//And just to demonstrate using object initializers (I'll use fluent style from now on though)
using var builder = new CertificateBuilder() {
Usage = CertificateUsage.Server,
FriendlyName = "Example self-signed web-server certificate",
Subject = new X500NameBuilder().SetCommonName("*.fake.domain"),
DnsNames = new[] { "*.fake.domain", "fake.domain" },
NotAfter = DateTimeOffset.UtcNow.AddMonths(1)
};
var cert = builder.Create();//A CA's expiry date must be later than that of any certificates it will issue
using var issuer = new CertificateBuilder()
.SetUsage(CertificateUsage.CA)
.SetFriendlyName("Example root CA")
.SetSubject(b => b.SetCommonName("Example root CA"))
.SetNotAfter(DateTimeOffset.UtcNow.AddYears(100))
.Create();//Note: the 'issuer' certificate used must have a private-key attached in order to sign this new certificate
using var cert = new CertificateBuilder()
.SetUsage(CertificateUsage.Client)
.SetFriendlyName("Example client-auth certificate")
.SetSubject(b => b.SetCommonName("User: Michael"))
.SetNotAfter(DateTimeOffset.UtcNow.AddYears(1))
.SetIssuer(issuer)
.Create();using var cert = 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(KeyPurposeID.AnyExtendedKeyUsage.Id) }, false))
.SetIssuer(issuer)
.Create();CertificateFinder examplesCertificateFinder requires the FluentCertificates.Finder package and is found under the FluentCertificates namespace.
TODO: document this
X500NameBuilder examplesX500NameBuilder requires the FluentCertificates.Builder package and is found under the FluentCertificates namespace.
TODO: document this; see unit tests for more examples
X509Certificate2 extension-methodsThese 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-methodsThese 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-methodsThese 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-methodsThese 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-methodsThese 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-methodsThese 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-methodsThese 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. |