Migration Guide

This document will help you migrate your code to the latest acme4j version.

Migration to Version 2.5

  • The GET compatibility mode has been removed. It also means that the postasget=false parameter is ignored from now on. If you need it to connect to your ACME server, do not update to this version until your ACME server has been fixed to support ACME draft 15.

Migration to Version 2.4

  • There was a major change in ACME draft 15. If you use acme4j in a common way, it will transparently take care of everything in the background, so you won’t even notice the change.

However, if you connect to a different ACME server than Boulder (Let’s Encrypt) or Pebble, you may now get strange errors from the server if it does not support the POST-as-GET requests of draft 15 yet. In that case, you can add a postasget=false parameter to the ACME server URI (e. g. "https://localhost:15000/dir?postasget=false"). Note that this is only a temporary workaround. It will be removed in a future version. Ask the server’s CA to add support for ACME draft 15.

  • The AcmeProvider.connect() method now gets the ACME server URI as parameter. It allows to add query parameters to the server URI that change the behavior of the resulting connection. If you have implemented your own AcmeProvider, just change the method’s signature to Connection connect(URI serverUri), and ignore the parameter value.

Migration to Version 2.3

  • Authorization.getDomain(), Order.getDomains() and Problem.getDomain() are deprecated now, and will be removed in version 2.4. If you use these methods, use getIdentifier() (or getIdentifiers()) to get an Identifier object, then invoke Identifier.getDomain() to get the domain name.

Migration to Version 2.1

  • This version adds JSR 305 annotations. If you use a null-safe language like Kotlin, or tools like SpotBugs, your code may fail to compile because of detected possible null pointer dereferences and unclosed streams. These are potential bugs that need to be resolved.

  • In acme4j’s JSON class, all as...() getters now expect a value to be present. For optional values, use JSON.Value.optional() or JSON.Value.map(). This class is rarely used outside of acme4j itself, so you usually won’t need to change anything.

Migration to Version 2.0

acme4j 2.0 fully supports the ACMEv2 protocol. Sadly, the ACMEv2 protocol is a major change.

There is no easy recipe to migrate your code to acme4j 2.0. I recommend to have a look at the example, and read this documentation. Altogether, it shouldn’t be too much work to update your code, though.

“Malformed account ID in KeyID header”

If you try to use your old ACME v1 account location URL in ACME v2, you will get a “Malformed account ID in KeyID header” error. The easiest way to fix this is to register a new account with your existing account key pair. You will get your migrated account location URL in return.