[doublerebel]

Yes, the API documentation is lacking especially with what we've gotten used to from Swagger markup and Stripe's API doc style. I have scoured for such an easy breakdown and found none. As a result I actually just implemented a new, clear, client for LetsEncrypt and have been documenting as I go.

It's made me think we should have a Swagger or API Blueprint of the spec on github that everyone can keep up to date. What do you think?

[pfg]

Are you referring to the server-side API the client is communicating with, or the internal API the client exposes?

The former is documented in the ACME specification[1], currently being worked on by the IETF. There are many low-level ACME libraries for basically every language[2], and a pretty decent guide on writing your own client as well[3].

[1]: https://ietf-wg-acme.github.io/acme/

[2]: https://github.com/letsencrypt/letsencrypt/wiki/Links#librar...

[3]: https://github.com/alexpeattie/letsencrypt-fromscratch

[simoncion]

Just gonna mention that the IETF RFC viewer [0] puts you one click away from a diff between the current and previous rev of a document [1] which can be quite handy when implementing a WIP protocol. For non-draft documents, you also get a link to the RFC's Errata page at the top of the page.

[0] https://tools.ietf.org/html/draft-ietf-acme-acme-02

[1] https://tools.ietf.org/rfcdiff?url2=draft-ietf-acme-acme-02....

[doublerebel]

Thank you very much for these links. 3) is the closest to what I'm looking for, and really good! but is still an implementation and not a spec. 1) is fine for a spec for an internet committee who has to delve into every detail for standardization. But if a client can be written in 150 lines of code, there should be a much shorter version of the spec (only a couple pages) in a standard format. I should be able to easily write a client from a 3-page spec without looking at all the implementations.

All due respect to the client authors, but only a few clients are good. Many are very poorly written, which I do not trust for security. I believe the cause is not having a clear, short, standard modern spec.

[simoncion]

> But if a client can be written in 150 lines of code, there should be a much shorter version of the spec (only a couple pages) in a standard format. I should be able to easily write a client from a 3-page spec without looking at all the implementations.

Right, but even though the protocol is simple, there are pretty much always subtleties and potential ambiguities that need to be resolved by the spec so that one can write good implementations.

> I believe the [problem] is not having a clear, short, standard modern spec.

The IETF ACME draft spec is (like many IETF specs) clear, short, standard, and modern. The entire document is only 50 pages (fewer if you reduce the font size), and (from skimming the ToC) the last ~10 of those pages are largely optional material for someone who's just reading to implement the protocol. That document shouldn't take you more than an hour to read and digest.

If you've never actually read an IETF spec they can be intimidating, but -if you're a programmer, network guy, or backend web dev- you really, REALLY owe it to yourself to learn how to read them:

* Use the IETF's HTML RFC viewer rather than the plain text viewer.

* Until you become familiar with the way IETF standards documents are written, don't skim! They're generally information-dense documents that do NOT repeat themselves.

* Start from the beginning of the document and read through the end.

* If the spec references another document, and then starts to talk about things from that document that you don't understand and can't figure out, go read the relevant parts of the referenced document.

* If the spec starts presuming knowledge of things that you're sure it hasn't mentioned yet, backtrack a bit... you probably overlooked something.

* The ASCII-art diagrams present in some specs aren't there for fun; they're important information.

In regards to shorter documents, I'm not sure what you're looking for... just a listing of the HTTP conversations and their payloads?

[doublerebel]

My point is, the clients are generally pretty bad despite the IETF spec. Lots of edge cases ignored, poor security practices. I understand the intention but the effect is that the clients are just as opaque as the spec but often more incorrect. Who would try to launch a startup API for wide use without a Stripe-style spec these days?

Thanks for the advice, but it's not that I don't understand how to read it, it's that I can tell other devs don't understand it despite the good intentions of the authors.

Plenty of good clients are written for plenty of other tools, based on a much more straightforward call-and-response API spec. For example, the Hashicorp tools have a simple spec and proper clients in many languages.

[pfg]

The spec contains sample payloads for pretty much every resource. In fact, you can build a functional client for http-01 just by looking at the examples.

On top of that, if you're using a programming language that's at least close to mainstream, there's a very good chance someone has already written a library which handles most of the nitty-gritty details of ACME. As an example, this is all the code you need with the acme-client ruby gem in order to solve a http-01 challenge and get a cert (slightly abbreviated):

    require 'acme/client'
    client = Acme::Client.new(private_key: private_key, endpoint: endpoint)
    registration = client.register(contact: 'mailto:[e-mail]')
    registration.agree_terms
    authorization = client.authorize(domain: 'example.org')
    # serve challenge.filename with content challenge.file_content
    challenge.request_verification
    # loop/sleep until challenge.verify_status == 'valid'
    csr = Acme::Client::CertificateRequest.new(names: ['example.org'])
    certificate = client.new_certificate(csr)
    # certificate.to_pem contains your signed cert. done!

[nickpsecurity]

Great write-up and advice! :)