Creating a Session

Central part of the communication is a Session object, which contains the URI of the target ACME server, and your account key pair. The ACME server identifies your account by your public key, and verifies that your requests are signed with a matching private key. Your private key is never transferred to the ACME server!

The first step is to create a Session instance. The Session tracks the communication with your account at the ACME server. If you want to access multiple accounts, you will need a separate Session instance for each of them.

KeyPair keyPair = ... // your key pair
URI acmeServerUri = ... // uri of the ACME server

Session session = new Session(acmeServerUri, keyPair);

The Session constructor expects the URI of the ACME server’s directory service, as it is documented by the CA. For example, this is how to connect to the Let’s Encrypt staging server:

Session session
    = new Session("https://acme-staging.api.letsencrypt.org/directory", keyPair);

However, such an URI is hard to remember and might even change in the future. Also, Java accepts the certificate used by the Let’s Encrypt server since JDK 8u101, calls to their servers are likely to throw a certificate exception on older versions.

For this reason, special ACME URIs should be preferred:

Session session = new Session("acme://letsencrypt.org/staging", keyPair);

Instead of a generic provider, this call uses a special Let’s Encrypt provider that also accepts the Let’s Encrypt certificate.

Now that you have a Session object, you can use it to bind ACME resource objects. For example, this is the way to get a Registration object to an existing registration:

URL accountLocationUrl = ... // your account's URL, as returned by Registration.getLocation()

Registration registration = Registration.bind(session, accountLocationUrl);

You can create any of the resource objects Registration, Authorization, Challenge and Certificate like that, as long as you know the corresponding resource URL. To get the resource URL, use the getLocation() method.