Module org.shredzone.acme4j
Package org.shredzone.acme4j

Class AccountBuilder

java.lang.Object
org.shredzone.acme4j.AccountBuilder
public class AccountBuilder extends Object
A builder for registering a new account with the CA.

You need to create a new key pair and set it via useKeyPair(KeyPair). Your account will be identified by the public part of that key pair, so make sure to store it safely! There is no automatic way to regain access to your account if the key pair is lost.

Depending on the CA you register with, you might need to give additional information.

It is not possible to modify an existing account with the AccountBuilder. To modify an existing account, use Account.modify() and Account.changeKey(KeyPair).

  • Constructor Details

  • Method Details

    • addContact

      public AccountBuilder addContact(URI contact)
      Add a contact URI to the list of contacts.

      A contact URI may be e.g. an email address or a phone number. It depends on the CA what kind of contact URIs are accepted, and how many must be provided as minimum.

      Parameters:
      contact - Contact URI
      Returns:
      itself

    • addContact

      public AccountBuilder addContact(String contact)
      Add a contact address to the list of contacts.

      This is a convenience call for addContact(URI).

      Parameters:
      contact - Contact URI as string
      Returns:
      itself
      Throws:
      IllegalArgumentException - if there is a syntax error in the URI string

    • addEmail

      public AccountBuilder addEmail(String email)
      Add an email address to the list of contacts.

      This is a convenience call for addContact(String) that doesn't require to prepend the "mailto" scheme to an email address.

      Parameters:
      email - Contact email without "mailto" scheme (e.g. test@gmail.com)
      Returns:
      itself
      Throws:
      IllegalArgumentException - if there is a syntax error in the URI string

    • agreeToTermsOfService

      public AccountBuilder agreeToTermsOfService()
      Documents that the user has agreed to the terms of service.

      If the CA requires the user to agree to the terms of service, it is your responsibility to present them to the user, and actively ask for their agreement. A link to the terms of service is provided via session.getMetadata().getTermsOfService().

      Returns:
      itself

    • onlyExisting

      public AccountBuilder onlyExisting()
      Signals that only an existing account should be returned. The server will not create a new account if the key is not known.

      If you have lost your account's location URL, but still have your account's key pair, you can register your account again with the same key, and use onlyExisting() to make sure that your existing account is returned. If your key is unknown to the server, an error is thrown once the account is to be created.

      Returns:
      itself

    • useKeyPair

      public AccountBuilder useKeyPair(KeyPair keyPair)
      Sets the KeyPair to be used for this account.

      Only the public key of the pair is sent to the server for registration. acme4j will never send the private key part.

      Make sure to store your key pair safely after registration! There is no automatic way to regain access to your account if the key pair is lost.

      Parameters:
      keyPair - Account's KeyPair
      Returns:
      itself

    • withKeyIdentifier

      public AccountBuilder withKeyIdentifier(String kid, SecretKey macKey)
      Sets a Key Identifier and MAC key provided by the CA. Use this if your CA requires an individual account identification (e.g. your customer number) and a shared secret for registration. See the documentation of your CA about how to retrieve the key identifier and MAC key.
      Parameters:
      kid - Key Identifier
      macKey - MAC key
      Returns:
      itself
      See Also:

    • withKeyIdentifier

      public AccountBuilder withKeyIdentifier(String kid, String encodedMacKey)
      Sets a Key Identifier and MAC key provided by the CA. Use this if your CA requires an individual account identification (e.g. your customer number) and a shared secret for registration. See the documentation of your CA about how to retrieve the key identifier and MAC key.

      This is a convenience call of withKeyIdentifier(String, SecretKey) that accepts a base64url encoded MAC key, so both parameters can be passed in as strings.

      Parameters:
      kid - Key Identifier
      encodedMacKey - Base64url encoded MAC key.
      Returns:
      itself
      See Also:

    • withMacAlgorithm

      public AccountBuilder withMacAlgorithm(String macAlgorithm)
      Sets the MAC key algorithm that is provided by the CA. To be used in combination with key identifier. By default, the algorithm is deduced from the size of the MAC key. If a different size is needed, it can be set using this method.
      Parameters:
      macAlgorithm - the algorithm to be set in the alg field, e.g. "HS512".
      Returns:
      itself
      Since:
      3.1.0

    • create

      public Account create(Session session) throws AcmeException
      Creates a new account.

      Use this method to finally create your account with the given parameters. Do not use the AccountBuilder after invoking this method.

      Parameters:
      session - Session to be used for registration
      Returns:
      Account referring to the new account
      Throws:
      AcmeException
      See Also:

    • createLogin

      public Login createLogin(Session session) throws AcmeException
      Creates a new account.

      This method is identical to create(Session), but returns a Login that is ready to be used.

      Parameters:
      session - Session to be used for registration
      Returns:
      Login referring to the new account
      Throws:
      AcmeException