ACME Provider¶
Basically, it is possible to connect to any kind of ACME server just by connecting to the URL of its directory resource:
Session session = new Session("https://acme-v02.api.letsencrypt.org/directory");
ACME providers are "plug-ins" to acme4j that are specialized on a single CA. For example, the Let's Encrypt provider offers URIs that are much easier to remember. The example above would look like this:
Session session = new Session("acme://letsencrypt.org");
Writing your own Provider¶
Every CA that provides an ACME server should also have an own AcmeProvider
, and if it is just for the sake of a pretty acme:
URI.
However, it is also possible to adapt the behavior of wide parts of acme4j to special characteristics of the CA, just by overriding methods and extending classes.
A client provider implements the AcmeProvider
interface, but usually it is easier to extend AbstractAcmeProvider
and implement only these two methods:
accepts(URI)
checks if the client provider is accepting the provided URI. Usually it would be an URI likeacme://example.com
. Note that thehttp
andhttps
schemes are reserved for the generic provider and cannot be used by other providers.resolve(URI)
parses the URI and returns the corresponding URL of the directory service.
The AcmeProvider
implementation needs to be registered with Java's ServiceLoader
. In the META-INF/services
path of your project, create a file org.shredzone.acme4j.provider.AcmeProvider
and write the fully qualified class name of your implementation into that file. If you use Java modules, there must also be a provides
section in your module-info.java
, e.g.:
provides org.shredzone.acme4j.provider.AcmeProvider
with org.example.acme.provider.MyAcmeProvider;
When acme4j tries to connect to an acme URI, it first invokes the accepts(URI)
method of all registered AcmeProvider
s. Only one of the providers must return true
for a successful connection. acme4j then invokes the resolve(URI)
method of that provider, and connects to the directory URL that is returned.
The connection fails if no or more than one AcmeProvider
implementation accepts the acme URI.
Certificate Pinning¶
The standard Java mechanisms are used to verify the HTTPS certificate provided by the ACME server. To pin the certificate, or use a self-signed certificate, override the createHttpConnector()
method of AbstractAcmeProvider
and return a subclassed HttpConnector
class that modifies the HttpURLConnection
as necessary.
Individual Challenges¶
If your ACME server provides challenges that are not specified in the ACME protocol, there should be an own Challenge
implementation for each of your challenge, by extending the Challenge
class.
In your AcmeProvider
implementation, override the createChallenge(Login, JSON)
method so it returns a new instance of your Challenge
implementation when your individual challenge type is requested. All other types should be delegated to the super method.
Amended Directory Service¶
To override single entries of an ACME server's directory, or to use a static directory, override the directory(Session, URI)
method, and return a JSON
of all available resources and their respective URL.
Adding your Provider to acme4j¶
After you completed your provider code, you can send in a pull request and apply for inclusion in the acme4j code base.
These preconditions must be met:
- Your provider's source code must be published under the terms of Apache License 2.0.
- The source code of your ACME server must be publicly available under an OSI compliant license.
- To avoid name conflicts, the
acme:
URI used must have the official domain name of your service as domain part. - You have the permission of all trademark holders involved, to use their trademarks in the source codes, package names, and the acme URI.
The acme4j development team reserves the right to reject your pull request, without giving any reason.
If you cannot meet these preconditions (or if your pull request was rejected), you can publish a JAR package of your acme4j provider yourself. Due to the plug-in nature of acme4j providers, it is sufficient to have that package in the Java classpath at runtime. There is no need to publish the source code.