v3.4.0

Important Changes

Until now, order finalization (order.execute()) was started immediately after the domain authorization process was completed. This is working fine for most CAs, but might fail for some CAs that take a while for the order to become READY for finalization. For this reason, I recommend to generally wait for the order status to become READY before invoking order.execute(). If you wait for state changes synchronously, you can use the new order.waitUntilReady() method for that. The example has been updated accordingly.

Waiting for status changes was expected to be implemented by you. There was a waitForCompletion() method in the example client that showed how to wait synchronously. With acme4j v3.4.0, there are now new methods waitForCompletion() and waitUntilReady() that do the heavy lifting for you. You can replace your own waiting code with these new methods if you like to. The new methods wait synchronously, blocking the current thread for several seconds or even minutes. If you have implemented an asynchronous wait, you should prefer to use your own code.

For further information, please see the migration guide and the example client.

Changelog

• Added waitForCompletion() and waitUntilReady() methods, which will synchronously wait for a status change. They replace the waitForCompletion() boilerplate method in the example implementation, and will make simple acme4j implementations simpler and less bugprone.
• Deprecate update() and AcmeRetryAfterException. Use fetch() instead.
• Update to draft-ietf-acme-ari-04. No changes to the code are required.

v3.3.1

• Added chapter about errors and Problem objects.
• OrderBuilder.replaces() set autoRenewal to true, which makes no sense in this context. Fixes #158, thanks to @rcc13 for reporting.

v3.3.0

• Added support for subdomain validation (RFC 9444)
• AcmeProtocolException was thrown when a rate limit was reached while fetching a nonce. Now either AcmeRetryAfterException or a generic AcmeException is thrown, depending on the error returned by the server.
• Project could not be built with Java 22, fixed (#157, thanks to @tugalsan for reporting)
• Integration tests against the latest docker image versions of pebble and challtestsrv

I also decided to discontinue acme4j v2, because the codebase diverged a lot now, and I don't want to spend my limited resources on maintenance. Please migrate your code to acme4j v3. For most clients, it is less work than it might look like.

v3.2.1

• Use ENGLISH locale for uppercase/lowercase conversion (fixes #156, thanks to @emirhannaneli)

This is a bugfix release. Update is only necessary if your system's default locale is set to Turkish.

3.2.0

• Documentation has been completely restructured and reviewed. The chapters are now oriented on the different steps, and should help to understand better how acme4j is working.
• Added acme://ssl.com URI for SSL.com. (Thanks to @fergadis, @ifindthanh, @thanhsmvn for the contribution.)
• Added acme://zerossl.com protocol provider for ZeroSSL.
• Simplified the handling of Retry-After headers. Catching AcmeRetryAfterException is not necessary anymore.
• CSR generator now supports domain names with more than 64 characters. The CSR's CN field is now left empty by default. (Thanks to @mcpherrinm for the contribution.)
• Updated ARI support to the latest draft-ietf-acme-ari-03. There is a breaking change in the protocol! If you use ARI and your CA still uses draft 01, do not update to this version!
• For generic ACME URIs, query parameters are now forwarded to the server. (Fixes #152)

No changes to your source code are required, unless you are using ARI.

Please read the Migration Guide for further information and caveats.

ZeroSSL makes use of EAB and the Retry-After header. The example has been changed accordingly. It now shows how to do EAB and how to properly handle the Retry-After header.

v3.1.1

This is a maintenance release with updated dependencies. There are no changes to acme4j itself.

Bouncy Castle is updated to version 1.77, which fixes a vulnerability (CVE-2023-33201). acme4j-client was not affected by this CVE, as the X509 certificates from the CA are only passed through. acme4j-smime however is validating certificates, so it could have been affected. If you use the acme4j-smime module, I recommend to update to this release.

Fixes #142.

3.1.0

• External account binding now permits to set individual MAC algorithms (AccountBuilder.withMacAlgorithm()) and usage of HMAC keys of arbitrary length. Thanks to @aarcloudera and @Radranic.
• The draft-ietf-acme-ari-01 implementation was missing a method 'Certificate.markAsReplaced()`. It is added now.
• All classes and methods related to draft-ietf-acme-ari-01 are now marked as @draft. As the draft evolves, they can change without prior notice. SemVer does not apply to parts that are marked as @draft. This is a preparation for draft-ietf-acme-ari-02, which will introduce major and breaking changes.

In the future, I will generally handle all draft implementations like that, as I don't want to do a major version bump of acme4j for every breaking change in a draft.

3.0.0

This is a major update!

Still the migration to v3.0.0 should be easy for most of you. See the migration guide for further information.

• acme4j now adheres to Semantic Versioning.
• The acme4j-utils module has been merged into acme4j-client. You can just remove the dependency on acme4j-utils from your project. This also means that BouncyCastle is now a hard requirement for acm4j. The separation of acme4j-client and acme4j-utils has become a blocker for new features though, so this step had to be taken.
• Requires Java 11. (For Java 8, you can still use acme4j v2, however it will only receive security bugfixes.)
• New method Certificate.findCertificate(String issuer) helps to find a certificate from the given issuer.
• Added support for draft-ietf-acme-ari-01 protocol.
• Reduced return of null values where possible. Methods that could have returned null in v2, will now return an Optional (or throw an exception if more appropriate). Collections may be empty, but are never null.
• PebbleAcmeProvider now accepts a port without having to set a host. Thanks to @mloesch for the contribution!
• A new Order.execute(KeyPair) method takes care for creating a CSR for you. You won't need to do that anymore. See the acme4j-example for how it works.
• New AcmeNotSupportedException is thrown when the ACME server does not support a certain feature.
• HTTP accepts gzip compression. It can be turned off in the NetworkSettings or via org.shredzone.acme4j.gzip_compression system property.
• Uses the java.net.http client now.
• Documentation has been reviewed and extended.
• All deprecated methods have been removed.

The change to v3.0.0 has been blocking acme4j for much too long. I am happy that it is published now, and I can focus on adding new features again.

v2.16

• S/MIME module now also supports RFC-7508 style header protection. Thanks to @augjoh for help!
• EmailProcessor.smimeMessage() is now deprecated, see the migration guide. It only affects the acme4j-smime module and is quickly resolved.

Note that the S/MIME module is still experimental. I appreciate your feedback!

There is an official acme4j Mastodon feed for release announcements and other acme4j related stuff: @[email protected]. Thanks to foojay for providing the instance.

v2.15

• S/MIME module now also supports the S/MIME validation of incoming challenge e-mails. There was a minor breaking API change for that, see the migration guide. It only affects the acme4j-smime module and is quickly resolved.

Note that the S/MIME module is still experimental. I appreciate your feedback!

Next I am planning an acme4j v3.0.0 release with the following major changes:

• acme4j-utils will be merged with acme4j-client, which means that BouncyCastle will be a hard requirement starting with v3.0.0.
• Starting with v3.0.0, acme4j will adhere to semantic versioning.
• acme4j will now require the second to current Java LTS version. This means that starting with v3.0.0, Java 11 or higher will be required. With the prospect release of Java 21 in September 2023, Java 17 will become the minimum version, and so on.

acme4j v2 will still be maintained for a while, but will only experience security updates.

For the upcoming v3.0.0, I also appreciate your input and feedback. Thank you!