Account and Login¶

If it is the first time you interact with the CA, you will need to register an account first.

Your account requires a key pair. The public key is used to identify your account, while the private key is used to sign the requests to the ACME server.

You can use external tools like openssl or standard Java methods to create the key pair. A more convenient way is to use the KeyPairUtils class. This call generates a RSA key pair with a 2048 bit key:

KeyPair accountKeyPair = KeyPairUtils.createKeyPair(2048);

You can also create an elliptic curve key pair:

KeyPair accountKeyPair = KeyPairUtils.createECKeyPair("secp256r1");

The key pair can be saved to a PEM file using KeyPairUtils.writeKeyPair(), and read back later using KeyPairUtils.readKeyPair().

Creating an Account¶

The AccountBuilder will take care for creating a new account. Instantiate a builder, optionally add some contact information, agree to the terms of service, set the key pair, then invoke create():

Account account = new AccountBuilder()
        .addContact("mailto:acme@example.com")
        .agreeToTermsOfService()
        .useKeyPair(keyPair)
        .create(session);

URL accountLocationUrl = account.getLocation();

If the account was successfully created, you will get an Account object in return. Invoking its getLocation() method will return the location URL of your account.

It is recommended to store the location URL along with your key pair. While this is not strictly necessary, it will make it much easier to log into the account later. Unlike your key pair, the location does not need security precautions. The location can easily be recovered if lost.

External Account Binding¶

At some CAs, you need to create a customer account on their website first, and associate it with your ACME account and keypair later. The CA indicates that this process is required if session.getMetadata().isExternalAccountRequired() returns true.

In this case, your CA provides you a Key Identifier (or KID) and a MAC Key (or HMAC Key). You can pass these credentials to the builder using the withKeyIdentifier() method:

String kid = ... // Key Identifier
SecretKey macKey = ... // MAC Key

Account account = new AccountBuilder()
        .agreeToTermsOfService()
        .withKeyIdentifier(kid, macKey)
        .useKeyPair(keyPair)
        .create(session);

URL accountLocationUrl = account.getLocation();

For your convenience, you can also pass a base64 encoded MAC Key as String.

Login¶

After creating an account, you need to login into it. You get a Login object by providing your account information to the session:

KeyPair accountKeyPair = ... // account's key pair
URL accountLocationUrl = ... // account's URL

Login login = session.login(accountLocationUrl, accountKeyPair);

Creating a Login object is very cheap. You can always create and dispose them as needed. There is no need to cache or pool them.

Login on Creation¶

If it is more convenient, you can also get a ready to use Login object from the AccountBuilder when creating a new account:

Login login = new AccountBuilder()
        .addContact("mailto:acme@example.com")
        .agreeToTermsOfService()
        .useKeyPair(keyPair)
        .createLogin(session);

URL accountLocationUrl = login.getAccountLocation();

Login without Account URL¶

As mentioned above, you will need your account key pair and the account URL for logging in. If you do not know the URL, you can log into your account by creating a new account with the same key pair. The CA will detect that an account with that key is already present, and return the existing one instead.

To avoid that an actual new account is created by accident, you can use the AccountBuilder.onlyExisting() method:

Login login = new AccountBuilder()
        .onlyExisting()         // Do not create a new account
        .agreeToTermsOfService()
        .useKeyPair(keyPair)
        .createLogin(session);

URL accountLocationUrl = login.getAccountLocation();

It will return a Login object just from your keypair, or throw an error if the key was not known to the server.

Remember that there is no way to log into your account without the key pair!

Updating the Contacts¶

At some point, you may want to update your account. For example your contact address might have changed. To do so, invoke Account.modify(), perform the changes, and invoke commit() to make them permanent.

The following example adds another email address.

Account account = login.getAccount();

account.modify()
      .addContact("mailto:acme2@example.com")
      .commit();

You can also get the list of contacts via getContacts(), and modify or remove contact URIs there. However, some CAs do not allow to remove all contacts.

Changing the Account Key¶

It is recommended to change the account key from time to time, e.g if you suspect that your key has been compromised, or if a staff member with knowledge of the key has left the company.

To change the key pair that is associated with your account, you can use the Account.changeKey() method:

KeyPair newKeyPair = ... // new KeyPair to be used

Account account = login.getAccount();
account.changeKey(newKeyPair);

After a successful change, all subsequent calls related to this account must use the new key pair. The key is automatically updated on the Login that was bound to this Account instance, so it can be used further. Other existing Login instances to the account need to be recreated.

The old key pair can be disposed of after that. However, better keep a backup of the old key pair until the key change was proven to be successful, by making a subsequent call with the new key pair. Otherwise you might lock yourself out from your account if the key change should have failed silently, for whatever reason.

Account Deactivation¶

You can deactivate your account if you don't need it any more:

account.deactivate();

Depending on the CA, the related authorizations may be automatically deactivated as well. If you want to be on the safe side, you can deactivate all authorizations manually, using Authorization.deactivate().

The issued certificates may still be valid until expiration or explicit revocation. If you want to make sure the certificates are invalidated as well, revoke them prior to deactivation of your account.