Over a million developers have joined DZone.

Building a Let’s Encrypt ACME V2 Client

DZone 's Guide to

Building a Let’s Encrypt ACME V2 Client

The release of Let’s Encrypt ACME V2 is close. Read on to get a quick overview of what the latest update to this popular security tool consists of.

· Security Zone ·
Free Resource

The Let’s Encrypt ACME v2 staging endpoint is live, with a planned release date of February 27. This is a welcome event, primarily because it is going to bring wildcard certificates support to Let’s Encrypt.

That is something that is quite interesting for us, so I sat down and built an ACME v2 client for C#. You can find the C# ACME v2 Let’s Encrypt client here; you’ll note that this is a gist containing a single file and, indeed, this is all you need, with the only dependency being JSON.Net.

Here is how you use this code for certificate generation:

var client = new LetsEncryptClient(LetsEncryptClient.StagingV2);
await client.Init("your-email@example.com", CancellationToken.None);
var tos = client.GetTermsOfServiceUri(); // user should agree to this

// start a new order for the *.example.net wildcard domain
Dictionary<string,string> challenges = await client.NewOrder(new[]

// do the DNS challenge
foreach(var challenge in challenges)
   await UpdateDnsServer(host: "_acme-challenge." + challenge.Key, token: challenge.Value, recordType: "TXT");

// Now that the DNS is updated, let Let's Encrypt know that it can validate them
await client.CompleteChallenges();

// get the certificate for the successful order
var cert = await client.GetCertificate();
//combine public cert with the private key for a full pfx
var pfx = cert.Cert.CopyWithPrivateKey(cert.PrivateKey);
File.WriteAllBytes("wildcard.example.net.pfx", pfx.Export(X509ContentType.Pfx));

Note that the code itself is geared toward our own use case (generating the certs as part of a setup process) and it only handles DNS challenges. This is partly why it is not a project but a gist, because it is just to share what we have done with others, not to take it upon ourselves to build a full-blown client.

I have to say that I like the V2 protocol much better, it seems much more intuitive to use and easier to work with. I particularly liked the fact that I can resume working on an order after a while, which means that failure modes such as failing to propagate a DNS update can now be much more easily recoverable. It also means that trying to run the same order twice for some reason doesn’t generate a new order, but resume the existing one, which is quite nice, given the rate limits imposed by Let’s Encrypt.

Note that the code is also making assumptions, such as caching details for you behind the scenes and not bothering with other parts of the API that are not important for our needs (modifying an account or revoking a certificate).

security ,let's encrypt ,certificate ,api security ,database security

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}