Can we Write an OpenAPI (Swagger) Spec for ACME?

Client dev
#1

So this has been an interesting one I have been chipping away at

How can we represent the ACME protocol as a Swagger Doc.

The key challenge seems to be the use of JWS where the "model" would be at JWS token. I.e. the same thing over and over again.

   {
     "protected": base64url({
       "alg": "ES256",
       "kid": "https://example.com/acme/acct/evOfKhNU60wg",
       "nonce": "ax5RnthDqp_Yf4_HZnFLmA",
       "url": "https://example.com/acme/acct/evOfKhNU60wg"
     }),
     "payload": base64url({
       "contact": [
         "mailto:certificates@example.org",
         "mailto:admin@example.org"
       ]
     }),
     "signature": "hDXzvcj8T6fbFbmn...rDzXzzvzpRy64N0o"
   }

Humans are too great at reading base64 payloads.

So my though is to create a OAS3 models for each payload and references it in the documents.

The responses are pretty well defined so are easy to represent.

The key question is would that provide value and should we try to pursue this?

The quick look around the forums suggests it's in the too hard basket?

image
image2531×918 155 KB

image
image2536×920 158 KB

4 Likes
#2

We use OpenAPI for my company's internal docs. ACMEv2 is at least partially covered in there by us. If a public project were to exist then I think we'd be interested in participating in it.

While the RFC is nice and all, I think having a more structurally-defined spec is beneficial to make sure the spec, and its implementation, are well understood.

2 Likes
#3

I couldn't agree with you more. I know firsthand the damage and frustration of spec interpretation.

1 Like
#4

Keeping this moving, @ahaw021, is there a repo you know of that contains a good attempt at the OpenAPI spec for ACMEv2? Or, are you able to put the stuff you've worked on so far in a suitable location with an appropriate license?

2 Likes
#5

@stevekerrison -- will do mate.

Probably a couple more days.

2 Likes