Usage

• General usage notes
• Running the application
• Rate limits
• Commands
• Options

General usage notes

With PJAC you can execute each step in the ACME protocol separately.

To generate a certificate, the following steps have to be taken:

1. The CA verifies your ownership of the domains you request a certificate for:

   1. The CA issues challenges for each domain the certificate is requested for;
   2. the CA verifies those challenges;
   3. if verification succeeds the CA sets the status of the domains for a specific certificate order to "valid".
   4. CA set a status "valid" to certificate order.

   The status "authorized" will be valid for a limited period of time. As long as the status is "valid", a certificate can be generated or downloaded for a cpecific certificate request. As soon as the status "valid" has expired, the new certificate order have to be generated again (new challenges must be requested and verified).

2. The CA creates a certificate which you can download.

PJAC implements this procedure as follows:

1. Domain ownership authorization:

   1. PJAC has separate commands to order a certificate (generate challenges): order-certificate and download-challenges;
   2. verify-domains asks the CA to check the authorization for the domains and, if necessary, renew it.

   You can perform each action in the process individually.

2. Certificate creation:
   PJAC has separate commands to request generation of a new certificate and to download previously created certificates: generate-certificate and download-certificates.

Running the application

You run the application with the Java launcher: java -jar acme_client.jar

Required parameters are:

1. a command;
2. required option(s) for the command.

Syntax

java -jar acme_client.jar <--command value> <--option value <...>>  
  [--option value [...]]

‼️ WARNING
If no server is specified, PJAC uses Let's Encrypt's production server by default:
https://acme-v02.api.letsencrypt.org/directory
To use another server, e.g. Let's Encrypt's test server, you need to explicitly specify it.

Let's Encrypt's production server uses rate limits to ensure fair usage. To avoid running up against rate limits it's highly recommended to test PJAC and your scripts against their staging server (test server):
https://acme-staging-v02.api.letsencrypt.org/directory

ℹ️ Note for Windows users: Java allows to use either forward slashes (/), back slashes (\) or double back slashes (\\) to separate directories in pathnames. Option values that contain spaces need to be enclosed in double-quotes (").
If you quote pathnames and use single back slashes, do not use a trailing backslash, e.g. --log-dir "C:\Logs\Acme Client\" will produce an error whereas --log-dir "C:/Logs/Acme Client/" and --log-dir "C:\\Logs\\Acme Client\\" will do fine.
This issue can't be fixed as it follows from how Java parses the command line.

Return values

When finished, the application returns a JSON object which contains either "status":"ok" or "status":"error", where sometimes additional information is provided. Detailed information about operations and errors is written to the log file.

Logging

Operations and errors are logged to the file acme.log. By default, the log is placed in
/var/log/acme/ (Unix) or
<drive-where-jar-is-located>:\var\log\acme (Windows).

Rate limits

CA's enforce rate limits for issued certificates and certain actions performed against their server. Because PJAC is designed to execute each step in the certificate issuing process separately, you have to take care to avoid hitting those limits.

For instance, at the time of writing this guide Let's Encrypt's production server limits generation of authorizations to up to 20 authorizations per second. The limit on pending (unverified) authorizations is up to 300 pending authorizations. Make sure that you don't generate too many authorizations at once and that you don't generate more authorizations than the limit allows before verifying them. Failed validations are currently limited to 5 failures per account, per hostname, per hour.

Regarding certificates, Let's Encrypt uses i.a. a main limit of 20 certificates per registered domain per week and a limit of 100 domain names per certificate.

Note that these limits may vary between CA's and are subject to change whenever the CA deems it necessary. Not all limits are covered here, see your CA's documentation for an overview of all applicable rate limits. For Let's Encrypt, current rate limits can be found here.

Commands

See the command reference for an overview of the available commands.

Options

If an optional option-parameter is omitted, the default value is used.

The options --server-url, --log-dir, --log-level and --with-agreement-update can be used with all commands.

The options --help and --version can be used without specifying a command, e.g.
java -jar acme_client.jar --help.

See the option reference for an overview of the available options.