Let's Encrypt ACME V2 API Documentation

Help
1

Hi all, is there any documentation available for Let’s Encrypt ACME V2 API: https://acme-v02.api.letsencrypt.org/directory.

I’m building a custom solution for SSL Certificates Management. I experimented with multiple libraries available for .NET but none seems complete to V2.

I found Certes to be very promising but it hangs most of the time…

I also found ayende’s Let’s Encrypt ACME V2 client but I’m getting unexpected errors and the client seems incomplete to me.

is there anywhere I could find the documentation for Let’s Encrypt ACME V2 APIs? Thanks for any help!

1 Like
2

The API is documented in the ACME draft: https://tools.ietf.org/html/draft-ietf-acme-acme-09 . There are newer drafts but I believe that 09 best reflects the current state of the v2 API (correct me if I’m wrong).

There are some divergences to the draft in the actual Let’s Encrypt API, which are documented here: https://github.com/letsencrypt/boulder/blob/master/docs/acme-divergences.md

Between those two and referring to the code of (well-written) existing clients, you can piece together how to build a client.

1 Like
3

thanks @_az for replying. I’ve gone through the draft but it is too much here and there and it doesn’t seem easy to understand. I’m looking for some aggregated documentation. W3C drafts have never been easy for me!

4

I don’t think there’s an “ACME for dummies” out there, though it’s an interesting idea for a blog post I guess. You probably have to read/understand most of the draft to build a functional ACME client, especially because of the relatively uncommon and complex way that requests are authenticated. It’s not a typical web API.

I’d double down on reading the code of an existing v2 client, even if it’s not in C#.

Edit: https://github.com/PKISharp/ACMESharpCore seems to be a renewed effort to build a .NET Core ACME v2 client, maybe you can focus your contributions there?

3 Likes
5

thanks for the links @_az , gonna explore https://github.com/PKISharp/ACMESharpCore.

1 Like
6

I think the differences between draft-09 and the current (-12) are fairly cosmetic and shouldn't introduce new divergences between our implementation and the draft specification.

As a quick note: These divergences are specific to the ACME v1 API. The only two divergences for the ACME v2 API are noted at the end of the announcement post: ACME v2 Production Environment & Wildcards

Specifically:

  1. There's no pre-authorization
  2. There's no order "ready" state (soon to be fixed)
  3. There's no "orders" field on account objects.

(I should update the acme-divergences.md doc in the Boulder repo to make this clearer. Apologies!)

You're correct that we don't have a lot of "higher level" documentation about ACME. It would be great to improve that in the future.

You might find an article I wrote in the Internet Protocol Journal (http://ipj.dreamhosters.com/wp-content/uploads/2017/08/ipj20-2.pdf - Page 2 onward) about ACME back in ~June of last year somewhat helpful in this regard. Unforuntately there were fairly significant protocol changes after this was written (The order finalization process is significantly different) and so it too is not a definitive resource.

I expect much of this will be easier in the future once we've moved beyond ACME being a draft standard into it being a final RFC. It's a bit like building on sand right now :slight_smile:

3 Likes
7

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.