acme-not-a-joke

What's new in acme-not-a-joke 0.2.0.0

2026-10-23T08:00:00Z

What’s new in acme-not-a-joke 0.2.0.0

Three packages were published on Hackage on 2026-10-23:

acme-not-a-joke 0.2.0.0, the ACME client, first release since 0.1.0.0;
acme-not-a-joke-wai 0.1.0.0, which answers HTTP-01 and TLS-ALPN-01 challenges from a wai/warp-tls server and hands it fresh certificates without a restart;
acme-not-a-joke-warp 0.1.0.0, automatic HTTPS for warp in the spirit of Caddy: certificates obtained when the program starts, stored on disk, and renewed before they expire.

The name still is a joke, the library still is not. The introduction listed things the author would like to change “with low appetite”: revocations, algorithms other than RS256, keyChange, account deactivation, getting rid of wreq. They are all in this release. This article goes over each addition briefly; the snippets target the Let’s Encrypt staging environment and assume a jwk account key (see the introduction).

Breaking changes first

ACME errors are now values. wreq is replaced with http-client, the post* calls, getNonce and fetchDirectory return an Either AcmeError a where they returned a Maybe a (or threw), and readProblem gives the RFC 7807 problem document the server sent. Only network-level failures are still raised, as HttpException. DanceStep gained the AcmeFailure and Authorizing constructors, and AcmeSingle now carries a list of pendingAuthorizations.

Right dir <- fetchDirectory (directory staging_letsencryptv2)
Right nonce <- getNonce dir.newNonce
created <- postCreateAccount jwk dir.newAccount nonce (createAccount contacts)
either (\err -> print (readProblem err)) print created

The full list is in the CHANGELOG. Release 0.2.0.0 also ships the PKI helpers prepared for an unreleased 0.1.1.0 (loadOrCreateJWKFile, loadOrCreateRSAKeyPEM, createCSR, loadCertificateChain, …), so openssl no longer is required.

TLS-ALPN-01: certificates without port 80

pull request 8 adds TLS-ALPN-01 challenges (RFC 8737): the ACME server opens a TLS connection to port 443 asking for the acme-tls/1 protocol, and the HTTPS server presents a self-signed challenge certificate to that connection only. The core library has runAcmeDance_tlsalpn01 and createTLSALPN01Certificate; acme-not-a-joke-wai has a TlsAlpn01Store, withTlsAlpn01 to wrap the warp-tls settings, and runAcmeDance_tlsalpn01_wai. The challenge is answered over TLS 1.3 only, the default of warp-tls.

With acme-not-a-joke-warp, it is two settings:

import Acme.NotAJoke.LetsEncrypt (letsencryptv2)
import Acme.NotAJoke.Warp
import Data.List.NonEmpty (NonEmpty (..))

main :: IO ()
main = do
  let cfg = defaultAutoHttps letsencryptv2 ("example.dicioccio.fr" :| []) ["mailto:certmaster@dicioccio.fr"] "state"
  runAutoHttps cfg{challengeMethod = TlsAlpn01, serveHttp = False} myApplication

Wildcards and multi-name orders over DNS-01

pull request 9 makes the dance validate every authorization of an order instead of the first one. An order can thus mix *.example.com with example.com. The dance emits one Authorizing step then one Validation step per authorization, and asks the server to check the challenges after the last one. dns01RecordName gives where the TXT record goes (_acme-challenge.example.com for both names: add the records, do not replace them).

Right key <- loadOrCreateRSAKeyPEM "staging-wildcard/key.pem"
Right csr <- createCSR key ("example.dicioccio.fr" :| ["*.example.dicioccio.fr"])

let o = createOrder (Nothing, Nothing) [ OrderIdentifier DNSOrder "example.dicioccio.fr", OrderIdentifier DNSOrder "*.example.dicioccio.fr" ]
current <- newIORef Nothing
let handle step = case step of
      Authorizing authz -> writeIORef current (Just (dns01RecordName (authIdentifier authz)))
      Validation (_, _, ValidationProof txt) -> do
        Just name <- readIORef current
        addTxtRecord name txt -- your DNS provider, then wait for propagation
      WaitingForValidation n -> threadDelay (n * 1000000)
      Done _ cert -> storeCert "staging-wildcard/certificate.pem" cert
      _ -> pure ()
runAcmeDance_dns01 (AcmeDancer staging_letsencryptv2 jwk (fetchAccount ["mailto:certmaster@dicioccio.fr"]) csr o handle)

The library does not talk to DNS providers: addTxtRecord is yours to write.

Revoking a certificate

pull request 10 adds Acme.NotAJoke.Api.Revocation (RFC 8555 section 7.6), with an optional RevocationReason. Sign the request with the account key, or with the key of the certificate when the account key is lost.

Right (cert : _) <- loadCertificateChain "staging-example/certificate.pem"
let rev = revocation (Just Superseded) cert

-- with the account key
revokeCertificate staging_letsencryptv2 jwk (fetchAccount ["mailto:certmaster@dicioccio.fr"]) rev

-- or with the key of the certificate
Right key <- loadRSAKeyPEM "staging-example/key.pem"
revokeCertificateWithCertKey staging_letsencryptv2 (jwkFromRSAKey key) rev

Changing the account key

pull request 11 adds account key rollover (RFC 8555 section 7.3.5) in Acme.NotAJoke.Api.KeyChange, and changeAccountKey to fetch the directory, nonce and account and send it. Once it succeeds, the old key no longer works: write the new one down first.

Just oldJwk <- loadJWKFile "staging/key.jwk"
newJwk <- genJWKrsa4096
writeJWKFile newJwk "staging/key.new.jwk"

changeAccountKey staging_letsencryptv2 oldJwk newJwk (fetchAccount ["mailto:certmaster@dicioccio.fr"])

Deactivating an account

pull request 12 adds deactivateAccount (RFC 8555 section 7.3.6), and postDeactivateAccount for when you already know the KID of the account. This cannot be undone.

deactivateAccount staging_letsencryptv2 jwk (fetchAccount ["mailto:certmaster@dicioccio.fr"])

JWS algorithms beyond RS256

pull request 13 lets the account key choose the algorithm: RS256 for RSA keys, ES256/ES384/ES512 for EC keys and EdDSA for Ed25519 keys (see acmeJWSAlg). setAcmeJWSAlg pins another algorithm in the JWK, e.g. PS256 with an RSA key. Let’s Encrypt accepts RS256, ES256 and ES384.

-- a smaller and faster account key, signing with ES256
jwk <- genJWKecP256
writeJWKFile jwk "staging/key.jwk"

The key of the certificate itself still is an RSA key.

Documentation

pull request 14 rewrote the READMEs and Haddock: how a certificate is obtained step by step, who initiates which request, which files are written where, and the type-family pattern behind Account "account-fetch" and friends. The READMEs of acme-not-a-joke, acme-not-a-joke-wai and acme-not-a-joke-warp are the place to start.

Getting it

build-depends:
    acme-not-a-joke ^>=0.2.0.0
  , acme-not-a-joke-warp ^>=0.1.0.0

The packages are on Hackage (acme-not-a-joke, acme-not-a-joke-wai, acme-not-a-joke-warp) and the code is on GitHub at lucasdicioccio/acme-not-a-joke.

Introducing acme-not-a-joke

2026-10-03T08:00:00Z

Introducing acme-not-a-joke

acme-not-a-joke is a Haskell library of primitives to perform ACME certifications, as specified by RFC 8555. ACME is the protocol spoken by providers such as Let’s Encrypt: a client proves that it controls a domain name and gets a TLS certificate for it in return.

About the name

acme- packages on Hackage typically are “joke” packages. This library implements the ACME protocol in earnest, hence the name: the acme prefix is not the marker of a joke here.

Status

The library is incomplete and subject to changes, but the happy path works.

Update: release 0.2.0.0 covers every item of the lists below; see what’s new in 0.2.0.0. The snippets of this article are written for 0.2.0.0.

Things the author would like to change, with low appetite:

support more features (especially, revocations);
allow to tweak algorithms (it works for RS256 only);
better helpers to create, load and write various PKI-related formats;
no longer use wreq (it reports non-200 responses with an exception).

The todo list also has: some more documentation, keyChange, and deactivating an account.

Design

The library uses a type-family pattern to specify which fields are available for an ACME resource in the various API calls and states. For instance, an Account in the "account-create" message has no “orders” field. The state is a type-level string, so types read like Account "account-fetch" or Order "order-create".

The modules are organised as follows:

Acme.NotAJoke.Api.* holds one module per ACME resource or concept, among which Directory, Nonce, Account, Order, Authorization, Challenge, Validation, CSR, Certificate and JWS;
Acme.NotAJoke.Client has the calls to an ACME server;
Acme.NotAJoke.Dancer chains these calls into a whole “dance”, from an order to a certificate;
Acme.NotAJoke.KeyManagement and Acme.NotAJoke.CertManagement have helpers to load and store keys, certificate signing requests and certificates;
Acme.NotAJoke.LetsEncrypt has the base URLs of Let’s Encrypt, for production and for staging.

A first certificate

The examples below are meant for GHCi and target the Let’s Encrypt staging environment, with the account key stored as a JWK in staging/key.jwk.

First, generate a key and a certificate signing request with the script shipped in the repository:

bash scripts/gen-csr.sh staging example dicioccio.fr

Then, create a new account:

import Acme.NotAJoke.Api.Account
import Acme.NotAJoke.Api.Directory
import Acme.NotAJoke.Api.Endpoint
import Acme.NotAJoke.Api.Nonce
import Acme.NotAJoke.KeyManagement
import Acme.NotAJoke.LetsEncrypt

Right jwk <- loadOrCreateJWKFile "staging/key.jwk"
let contacts = ["mailto:certmaster@dicioccio.fr"]

Right leDir <- fetchDirectory (directory staging_letsencryptv2)
Right nonce0 <- getNonce leDir.newNonce
created <- postCreateAccount jwk leDir.newAccount nonce0 (createAccount contacts)
either (\err -> print (readProblem err)) print created

Finally, create a new certificate:

import Acme.NotAJoke.CertManagement
import Acme.NotAJoke.Client
import Acme.NotAJoke.Dancer
import Acme.NotAJoke.KeyManagement
import Acme.NotAJoke.Api.Directory
import Acme.NotAJoke.Api.CSR
import Acme.NotAJoke.Api.Order
import Acme.NotAJoke.LetsEncrypt
import Data.Maybe

jwk <- fromJust <$> loadJWKFile "staging/key.jwk"
der <- loadDER "staging-example/certificate.csr.der"

let o = createOrder (Nothing, Nothing) [ OrderIdentifier DNSOrder "example.dicioccio.fr" ]
runAcmeDance_dns01 (AcmeDancer staging_letsencryptv2 jwk (fetchAccount ["mailto:certmaster@dicioccio.fr"]) (CSR der) o (ghciDance "staging-example/certificate.pem"))

runAcmeDance_dns01 runs the whole exchange with a DNS-01 challenge. The last field of the AcmeDancer is a handler called at each step of the dance. ghciDance is a handler meant for GHCi: it prints each step, and when the validation proof is known it prints it and waits for you to press ENTER, which leaves you the time to publish the proof in the DNS. Once the certificate is fetched, it stores it at the given path.

Where to go next

The code and its README are on GitHub at lucasdicioccio/acme-not-a-joke.