ENTERPRISE  This is an EJBCA Enterprise feature.

The Automatic Certificate Management Environment (ACME) is a protocol that a Certificate Authority (CA) and an applicant can use to automate the process of verification of the ownership of a domain (or other identifier) and certificate management.

ACME Reference

Each EJBCA release is bundled with an auto-generated ACME reference available on the URL https://localhost:8442/ejbca/doc/acme/ if deployed, or online on https://doc.primekey.com/ejbca/ejbca-operations/ejbca-ca-concept-guide/protocols/acme

Swagger UI

Swagger UI allows you to visualize and interact with the API’s resources. The Swagger UI playground is available in your browser on the URL https://localhost:8443/ejbca/swagger-ui (use port 8443 since ACME uses client certificate authentication).

You can switch between displaying ACME or the REST API using the Swagger UI Select a spec list.

Swagger UI

  • Swagger UI is only available if you build EJBCA in non-production mode, i.e. with ejbca.productionmode=false set in conf/ejbca.properties.
  • The Swagger UI for ACME will only be available if ACME is activated as a protocol, see Enabling ACME.

Supported Operations

EJBCAs ACME implementation currently complies with the final ACME standard IETF - RFC8555. All operations must be called with POST requests. For the directory operation there is a GET request offered and for the newNonce operation a GET and HEAD request as well.

OperationURLDescriptionRFC 8555 Reference
directory/ejbca/acme/directoryGet the directory object listing all ACME operation URLs and the ACME configuration meta data.7.1.1
newNonce/ejbca/acme/newNonceBefore any POST action is performed, the client needs to retrieve an anti-replay nonce from the server.7.2
newAccount/ejbca/acme/newAccountCreate a new ACME account, or retrieve an existing account, including the account URL and the account ID.

7.3

updateAccount/ejbca/acme/acct/{accountId}Update or deactivate an existing account. Change its contact information or agree to the ACME service terms of service.7.3.2
newOrder/ejbca/acme/newOrderCreate a new ACME order for one or multiple domains (or other identifiers). This is the first step to request certificate issuance.7.4
challenge/ejbca/acme/acct/{accountId}/chall/{challengeId}Tell the ACME server that it can validate your challenge response and retrieve the challenge object.7.5.1
newAuthz/ejbca/acme/newAuthz

Only if Pre-Authorization Allowed is enabled in the Alias configuration.

7.4.1
finalizeOrder/ejbca/acme/acct/{accountId}/orders/{orderId}/finalizeSend your Certificate Signing Request (CSR) and let the CA issue your certificate.7.1.3
revokeCert/ejbca/acme/revokeCertRevoke a certificate.7.6
keyChange/ejbca/acme/keyChangeReplace the key of an existing account.7.3.5
cert/ejbca/acme/cert/{certificateId}Download a certificate.7.4.2

URL Endpoints and Aliases

The ACME service is available on the following URLs.

Some ACME clients (like PJAC) may cut the URL query string (?configurationId=<alias_name>). Please use the URL style with the alias name specified in the URL path.

Default alias with client authentication

https://<server>:8443/ejbca/acme/directory

Default alias without client authentication

https://<server>:8442/ejbca/acme/directory

Custom alias <alias_name> with client authentication

https://<server>:8443/ejbca/acme/directory?configurationId=<alias_name>
or
https://<server>:8443/ejbca/acme/<alias_name>/directory

Custom alias <alias_name> without client authentication

https://<server>:8442/ejbca/acme/directory?configurationId=<alias_name>
or
https://<server>:8442/ejbca/acme/<alias_name>/directory

EJBCA Specifics

  • Approvals in EJBCA for enrollment and revocation cannot be used with ACME.
  • All ACME operations are performed over the peers protocol. Thus it is perfectly possible to use an external RA running EJBCA as an ACME proxy.
  • Validators for CAA checking etc. are configured as described in Validators Overview.
  • You need to set up separate aliases for each end entity profile/certificate profile and CA.

Configuration

Enabling ACME

The ACME protocol is by default disabled. To enable the service, go to CA UI > System Configuration > Protocol Configuration and select Enable for ACME.

Managing ACME Configurations

Much like other protocols in EJBCA, several different ACME configurations can be maintained at the same time using aliases.

To configure ACME, select ACME Configuration under the System Configuration menu. 

Managing ACME Aliases







Global Fields

The following fields are defined globally for all ACME operations.

FieldDescription
Default ACME ConfigurationThe configuration to use if the specified alias does not exist.
Replay Nonce Validity NumberDefines the validity in milliseconds of a generated replay nonce.

Alias Specific Fields

Example of ACME Alias configuration.

The following table lists ACME specific fields for each individual alias.

FieldDescription
End Entity ProfileThe end entity profile to use for end entities enrolled using this alias. The CA signing the certificate is the default CA of this end entity profile, and the certificate profile used for the certificate is the default certificate profile of this end entity profile.
Pre-Authorization AllowedPre-authorization, as defined in section 7.4.1 of RFC 8555.
Wildcard Certificate Issuance AllowedWhether this alias can be used to issue certificates with wildcard DNS names in their SANs. See section 7.1.3 of RFC 8555.
Site URLURL to a website describing this CA. Optional. See section 7.1.1 of RFC 8555.
Terms of Service URL

URL to your terms of service for ACME. Optional. See section 7.1.1 of RFC 8555.

Require client approval for Terms of Service changes

Specifies whether users must approve the new version if the Terms of Service URL is changed.

DNS ResolverA specified DNS resolver, used when processing dns01 challenges.
DNS PortPort used for DNS communications.
DNSSEC Trust AnchorThe ICANN trust anchor, configurable should it ever change.
Retry AfterValue used to indicate that client should try polling the authorization endpoint again after a while (in seconds). Default is 0 and this is used mainly for clients such as cert-manager which send post-as-get request while waiting for ACME server to prepare the challenge.

External Account Binding is an optional feature and will not be supported in this release! The corresponding field in the directory output (externalAccountRequired) is false by default and it is not changeable for now.

End Entity Profile Configuration

The following settings should be used for an end entity profile used with ACME.

FieldValue
UsernameAuto-generated
Password (or Enrollment Code)Leave empty
End Entity E-mailUse, Required, Modifiable
Subject DN Attributes
CN, Common nameRequired, Modifiable
Default Certificate Profile<The certificate profile to use>
Default CA<The CA signing the certificate>
Default TokenUser Generated
Other subject attributes
DNS NameModifiable

Authentication and Validation

EJBCA currently supports the two validation methods http01 and dns01, defined in section 8 of RFC 8555.

HTTP Challenge (http01)

If the client chooses to use the http01 challenge type, it intends to prove that it controls the domain requested in the certificate by provisioning a resource under the same domain name. As per RFC 8555, EJBCA will send out a challenge to the client, which the client will sign using its private key and provide on the domain in a known location for EJBCA to retrieve. EJBCA will then be able to use the public key provided in the original request to verify domain control. The HTTP connection for validation is done from the CA to the client, even if an external RA is used, since the CA does the validation.

DNS Challenge (dns01)

If the client chooses to use the dns01 challenge type, it instead obligates itself to supply a TXT record containing the same token response as described above. As per RFC 8555, DNSSEC is required for dns01 challenges. The DNS lookup for validation is done from the CA, even if an external RA is used, since the CA does the validation.

Compatibility with ACME Clients

EJBCA is compatible with the following ACME clients (taken from Letsencrypt's list of compatible ACME clients):

EJBCA ACME with Certbot 0.37.0 or 0.39.0

Certbot used to be Let's Encrypt's official client but is now maintained by the Electronic Frontier Foundation. It is one of the most used ACME clients, supporting issuance, renewal and revocation operations, which are all supported by EJBCA. For more information, refer to the Certbot Documentation.

For more information on integration, see our integration guide Using Certbot to Issue Certificates with ACME to an Apache Web Server.

Certbot by default uses Let's Encrypts servers. To specify an alternative server URL, use the --server option:

--server https://localhost:8442/ejbca/acme/directory
CODE

Note that you can also use the server option in cli.ini.

Example Scenarios

Prerequisites

The following examples assume that a Ubuntu machine with JBoss or Wildfly is used and that EJBCA is accessible under https://localhost:8442 public HTTPS, using Certbot 0.37.0. To get the Certbot latest release, use the certbot-auto installation command.

The following example assumes that EJBCA, Certbot and Apache are set up on the same host. If you for example run EJBCA on a separate VM, then the Apache virtual hosts must be accessible from that VM, for EJBCA to be able to access HTTP challenges under the specified domains.

$ wget https://dl.eff.org/certbot-auto
$ sudo mv certbot-auto /usr/local/bin/certbot-auto
$ sudo chown root /usr/local/bin/certbot-auto
$ sudo chmod 0755 /usr/local/bin/certbot-auto
$ sudo /usr/local/bin/certbot-auto –help
$ sudo /usr/local/bin/certbot-auto --install-only
BASH

Run the following command in the console to ensure that a connection to the ACME server is up and running:

$ curl -k https://localhost:8442/ejbca/acme/directory
BASH

The successful output of the above command should be as follows (showing the resources available in the EJBCA ACME server), otherwise the scenarios will fail:

{"newNonce":"https://localhost:8442/ejbca/acme/newNonce","newAccount":"https://localhost:8442/ejbca/acme/newAccount","newOrder":"https://localhost:8442/ejbca/acme/newOrder","revokeCert":"https://localhost:8442/ejbca/acme/revokeCert","keyChange":"https://localhost:8442/ejbca/acme/keyChange","meta":{"termsOfService":"https://example.com/acme/terms","website":"https://www.example.com/","caaIdentities":[],"externalAccountRequired":false}}
CODE

HTTP Validation Scenario

  1. Issue certificate for an identifier (example.com) using HTTP validation:

    Setup a local HTTP server (for example Apache with the default working directory /var/www/html). Add the following virtual host under /etc/apache2/sites-available/example.com.conf:

    <VirtualHost *:80>
      ServerName example.com
    
      DocumentRoot "/var/www/"
    
    </VirtualHost> 
    CODE

    Enable the site using the command:

    $ sudo a2ensite example.com 
    
    BASH

    Then run:

    $ sudo service apache2 reload
    BASH

    Next, restart Apache:

    $ sudo /etc/init.d/apache2 restart
    BASH

    Then add the following line to your /etc/hosts file:

    127.0.0.1       example.com
    CODE

    Create the directory structure of .well-known/acme-challenge inside /var/www/example/ and change its permissions to 755 recursively.

    mkdir -p .well-known/acme-challenge 
    
    chmod 755 -R .well-known/
    CODE
  2. Having Certbot installed on your machine, try the following command (EJBCA should be up and running with ACME enabled and with an ACME alias configured with appropriate end entity profile):

    $ sudo certbot --no-verify-ssl --server https://localhost:8442/ejbca/acme/directory certonly --webroot -w /var/www/ -d example.com --agree-tos --email test@example.com --no-eff-email --noninteractive
    BASH

    The command should run successfully and in the display a message similar to the following:

    IMPORTANT NOTES:
     - Congratulations! Your certificate and chain have been saved at:
     /etc/letsencrypt/live/example.com/fullchain.pem
     Your key file has been saved at:
     /etc/letsencrypt/live/example.com/privkey.pem
     Your cert will expire on 2020-08-21. To obtain a new or tweaked
     version of this certificate in the future, simply run certbot
     again. To non-interactively renew *all* of your certificates, run
     "certbot renew"
     - If you like Certbot, please consider supporting our work by:

    Go to EJBCA Admin Web and search for End Entities, there should be one with the status Generated and CN = example.com.

    The error message The client lacks sufficient authorization :: The client lacks sufficient authorization indicates a conflict between the new account creation and existing ACME accounts. To resolve, remove everything under /etc/letsencrypt/live, /etc/letsencrypt/accounts and /etc/letsencrypt/keys and try again.

  3. If you want to issue a certificate containing multiple domains (for instance, example.com and example.org), set up another Apache virtual host as follows:

    <VirtualHost *:80>
      ServerName "example.org"
      DocumentRoot "/var/www/"
    </VirtualHost>
    CODE


    Repeat the steps mentioned above to enable it and add it to your hosts.

    Next, issue the following command and ensure to remove the live, keys and account directories of certbot otherwise it will ask for expansion of the already existing certificate. Note that the domains specified using -d are comma separated.

    sudo certbot --no-verify-ssl --server https://localhost:8442/ejbca/acme/directory certonly --webroot -w /var/www/ -d example.com,example.org --agree-tos --email test@example.com --no-eff-email --noninteractive
    CODE


    This will result in a certificate which covers both the example.com and example.org domains. To verify, decode the produced certificate .pem file and observe that the SAN section includes two domains as two different dnsNames.

  4. To revoke the certificate issued in the step above, run the following command:

    $ sudo certbot --no-verify-ssl --server https://localhost:8442/ejbca/acme/directory revoke --cert-name example.com --reason keycompromise
    BASH


    If asked for deleting the just issued certificate, reply with Y. Alternatively use the option switch --no-delete-after-revoke and delete the certificates for the domain afterwards with the certbot delete command. The following success message must be shown:

    Congratulations! You have successfully revoked the certificate that was located at /etc/letsencrypt/live/example.com/fullchain.pem


    Go to EJBCA Admin Web and check the status for the corresponding End Entity certificate and make sure it is revoked.

  5. In order to issue a certificate for a wildcard domain do as follows:
    First you need to enable the wildcard certificate issuance via Acme Configuration alias page.
    Then run the same command as in step two providing a wildcard domain as identifier.

    $ sudo certbot --no-verify-ssl --server https://localhost:8442/ejbca/acme/directory certonly --webroot -w /var/www/html/ -d *.example.com
    BASH

    The rest of procedure should be same as above.

DNS Validation Scenario

  1. Issue certificate for an identifier (allow.klaan.nu) using Domain Name System Security Extensions (DNSSEC) validation:
    Make sure you have a DNS server setup which you can add TXT records to. In this example, dnsmasq is used, included in most Linux distributions.

    The EJBCA ACME server currently supports DNSSEC validation and this example uses allow.klaan.nu to be able to pass DNSSEC validation.

  2. To issue the certificate, run the following command in the command line:

    $ sudo certbot --no-verify-ssl --server https://localhost:8442/ejbca/acme/directory certonly --manual --preferred-challenges=dns -d allow.klaan.nu
    BASH

    The --manual flag is used to run Certbot interactively and allow preparing the DNS server with the DNS challenge offered by the ACME server.

    Agree to your IP being logged by replying Yes to the following: 

    Are you OK with your IP being logged?
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    (Y)es/(N)o:


    Certbot displays the TXT record challenge offered by the ACME server which have to be provisioned in the DNS server. Before pressing Enter, run the following command to provision the TXT record in dnsmasq:

    $ sudo dnsmasq --port="1453" --txt-record="_acme-challenge.allow.klaan.nu, pULO3RjCbzqjWH0JK2FQ5BDe-5SI2Eo2Vn1l_fmrtdk" --listen-address="127.0.0.1"  --interface="lo" --bind-interfaces
    BASH

    The port number used above is just an example. Note that the port number must equal the port set for the ACME Alias currently used by the EJBCA ACME server, configured in Admin Web>System Configuration>ACME Configuration. In addition, the DNS Resolver field needs to be set to localhost in the ACME Configuration Alias page, see Alias Specific Fields.

    After running the above command, press Enter in the Certbot command prompt to continue. A message similar to the following is displayed for a successful certificate issuance:

    IMPORTANT NOTES:
     - Congratulations! Your certificate and chain have been saved at:
       /etc/letsencrypt/live/allow.klaan.nu/fullchain.pem
       Your key file has been saved at:
       /etc/letsencrypt/live/allow.klaan.nu/privkey.pem
       Your cert will expire on 2020-08-21. To obtain a new or tweaked
       version of this certificate in the future, simply run certbot
       again. To non-interactively renew *all* of your certificates, run
       "certbot renew"
     - If you like Certbot, please consider supporting our work by:
    
       Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
       Donating to EFF:                    https://eff.org/donate-le
    
    

    Ensure that the certificate is issued in EJBCA by checking that the Admin Web End Entity Search page includes a row with CN equal to allow.klaan.nu and a valid certificate.

  3. To revoke the certificate issued in the previous step, run:

    $ sudo certbot --no-verify-ssl --server https://localhost:8442/ejbca/acme/directory revoke --cert-path /etc/letsencrypt/live/allow.klaan.nu/fullchain.pem
    BASH

    The following message displays if successful:

    Congratulations! You have successfully revoked the certificate that was located
    at /etc/letsencrypt/live/allow.klaan.nu/fullchain.pem

    Make sure that the certificate is revoked with the reason Unspecified in EJBCA by checking its status in the Admin Web End Entity Search page.

  4. To issue a certificate for a wildcard domain do as follows:
    First enable the wildcard certificate issuance via Acme Configuration alias page.
    Then issue the following (example) command.

    $ sudo certbot --no-verify-ssl --server https://localhost:8442/ejbca/acme/directory certonly --manual --preferred-challenges=dns -d *.allow.klaan.nu
    BASH

     The rest of the procedure is similar to the above.

EJBCA ACME with PJAC 3.0.1

Porunov Java ACME Client (PJAC) is an application based on acme4j, a Java ACME library implementation. To try out EJBCA with PJAC, refer to GitHub documentation on Example scenarios.

EJBCA is tested with the following PJAC flows:

  • Get a certificate for multiple domains
  • Renew a certificate for multiple domains
  • Get a wildcard certificate
  • Revoke certificate
  • Deactivate account
  • Pre-authorization (does not seem to be part of PJAC, but is supported by underlying acme4j)
  • HTTP01 and DNS01 challenge types

(warning) Note that you have to import the certification path of EJBCAs Management CA into the truststore of the concrete JVM installation, or to reference it as -D parameter 'javax.net.ssl.trustStore'. For self-signed certificates your are asked to trust it. Confirm with 'Yes'.:

$ sudo /usr/lib/jvm/jdk-11.0.1/bin/keytool -import -file /opt/ejbca/ejbca/p12/ManagementCA.cacert.pem -keystore /usr/lib/jvm/jdk-11.0.1/lib/security/cacerts -alias ManagementCA
BASH

(warning) Note that you need to configure PJAC to have the EJBCA instance as its ACME service, by adding an extra '-u' parameter to acme_client.jar command executions:

-u https://localhost:8442/ejbca/acme/directory
CODE

(warning) You may reuse these parts of the PJAC command with an alias:

$ alias acme-client="sudo /usr/lib/jvm/jdk-11.0.1/bin/java -Djavax.net.ssl.trustStore=$JAVA_HOME/lib/security/cacerts -Djavax.net.ssl.trustStorePassword=changeit -jar acme-client.jar -u https://localhost:8442/ejbca/acme/directory --log-level TRACE --with-agreement-update"
BASH

Configure the virtual hosts and local resolution like above with certbot.

Run some PJAC commands now to register a new account and to issue a certificate for two different domains, using your CMD alias.

1. Test your installation with the retrieval of the ACME configurations terms of service URL.

$ acme-client --command get-agreement-url
BASH

The response returned by PJAC must contain the URL like this {“agreement_url“:“https://example.com/acme/terms“, “status”:”ok”}.

Create a new account key pair.

$ sudo openssl genrsa -out /etc/pjac/account.key 
BASH

2. Create a new ACME account for this key pair:

vacme_client --command register -a /etc/pjac/account.key --email pjacuser@primekey.com 
BASH

3. Add some more email address to the accounts contact information:

$ acme_client --command add-email -a /etc/pjac/account.key --email pjacuser2@primekey.com 
BASH

The second hostname is stored in a SAN DNS name field, so you have to use openssl with an openssl.cfg configuration file with the following content.

[req]
distinguished_name = req_distinguished_name
req_extensions = v3_req
prompt = no
[req_distinguished_name]
C = acme-test-1.com
[v3_req]
keyUsage = keyEncipherment, dataEncipherment
subjectAltName = @alt_names
[alt_names]
DNS.1 = acme-test-2.com
BASH

Create a key pair and a CSR for the TSL certificate for the 2 domains to issue.

$ sudo openssl genrsa -out /etc/pjac/acme-test.key
$ sudo openssl req -new -key /etc/pjac/acme-test.key -subj "/CN=acme-test-1.com" -out /etc/pjac/acme-test.com.csr -config openssl.cfg
BASH

4. Now you can order a certificate for the two domains (i.e. with a HTTP01 challenge). Note, that you have to create the directories, if not existing.

$ acme-client --command order-certificate -a /etc/pjac/account.key -w /etc/pjac/workdir/ --cert-dir /var/acme_work_dir/cert --csr acme-test.com.csr --well-known-dir /var/www/html/.well-known/acme-challenge --one-dir-for-well-known –-challenge-type HTTP01
BASH

5. Verify the challenges.

$ acme-client --command verify-domains -a /etc/pjac/account.key -w /etc/pjac/workdir/ --cert-dir /var/acme_work_dir/cert --csr /etc/pjac/acme-test.com.csr –-challenge-type HTTP01
BASH

6. If the challenge responses were verified by the server, you may request your certificate.

$ acme-client --command generate-certificate -a /etc/pjac/account.key -w /etc/pjac/workdir/ --cert-dir /var/acme_work_dir/cert/ --csr /etc/pjac/acme-test.com.csr
BASH

7. Download the certificate.

$ acme-client --command download-certificates -a /etc/pjac/account.key -w /etc/pjac/workdir/ --cert-dir /var/acme_work_dir/cert
BASH

8. You may revoke the certificate for some reason later.

$ acme-client --command revoke-certificate -a /etc/pjac/account.key -w /etc/pjac/workdir/
BASH

EJBCA ACME with ACME Tiny

  1. Clone the repository:

    $ git clone https://github.com/diafygi/acme-tiny.git
    BASH
  2. Change EJBCA ACME URLs:

    -DEFAULT_CA = "https://acme-v02.api.letsencrypt.org" # DEPRECATED! USE DEFAULT_DIRECTORY_URL INSTEAD
    -DEFAULT_DIRECTORY_URL = "https://acme-v02.api.letsencrypt.org/directory"
    +
    +DEFAULT_CA = "https://{ejbca_url}:8442" # DEPRECATED! USE DEFAULT_DIRECTORY_URL INSTEAD
    +DEFAULT_DIRECTORY_URL = "https://{ejbca_url}:8442/ejbca/acme/directory"
    
    CODE
  3. Prepare input for ACME:

    # Generate private key
    openssl genrsa 4096 > account.key
    # Generate CSR
    openssl req -new -sha256 -key account.key -subj "/emailAddress=acme_test@primekey.com/CN=my.acme" > account.csr
    CODE
  4. Launch ACME Tiny (Tested with Python2):

    $ sudo python acme_tiny.py --account-key ./account.key --csr ./account.csr --acme-dir ./acme-dir/ --contact 'mailto:acme@primekey.com' > ./signed_chain.crt
    BASH

where --acme-dir ./acme-dir/ might be integrated and/or point to your current web server, for example Apache2 /var/www/html/.well-known/acme-challenge/.

Workflow Examples

The following lists ACME operations to perform in order to get a certificate. For newAccount and for revokeCert requests there MUST be a 'jwk' field, otherwise a 'kid' field.

getDirectory request

Returns the URLs for each ACME operation and the service meta data.

GET /acme/directory HTTP/1.1

{  
   "newNonce":"https://footrust.local:8443/ejbca/acme/newNonce",
   "newAccount":"https://footrust.local:8443/ejbca/acme/newAccount",
   "newOrder":"https://footrust.local:8443/ejbca/acme/newOrder",
   "newAuthz":"https://footrust.local:8443/ejbca/acme/newAuthz",
   "revokeCert":"https://footrust.local:8443/ejbca/acme/revokeCert",
   "keyChange":"https://footrust.local:8443/ejbca/acme/keyChange",
   "meta":{  
      "termsOfService":"https://footrust.com/acme/terms",
      "website":"https://footrust.com",
      "caaIdentities":[  
         "footrust.com"
      ],
      "externalAccountRequired":false
   }
}
CODE

newAccount request

Creates a new ACME account to EJBCA and returns it with the response. EJBCA uses a public key to verify the JWS (that is, the jwk element of the JWS header) to authenticate future requests from the account. EJBCA supports RSA and EC key types. If the account with this key already exists, it is returned with the response.

POST https://localhost:8442/ejbca/acme/newAccount HTTP/1.1
Content-Type: application/jose+json

{
  "protected": base64url({
    "alg": "ES256",
    "jwk": {...},
    "nonce": "6S8IqOGY7eL2lsGoTZYifg",
    "url": "https://example.com/acme/newAccount"
  }),
  "payload": base64url({
    "termsOfServiceAgreed": true,
    "contact": [
      "mailto:cert-admin@example.com",
      "tel:+12025551212"
    ]
  }),
  "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I"
}
CODE

newOrder request

Creates a new ACME order.

POST /acme/newOrder HTTP/1.1
Content-Type: application/jose+json

{
 "protected": base64url({
   "alg": "ES256",
   "kid": "https://example.com/acme/acct/evOfKhNU60wg",
   "nonce": "5XJ1L3lEkMG7tR6pA00clA",
   "url": "https://example.com/acme/new-order"
 }),
 "payload": base64url({
   "identifiers": [
	 { "type": "dns", "value": "www.example.org" },
	 { "type": "dns", "value": "example.org" }
   ],
   "notBefore": "2016-01-01T00:00:00Z",
   "notAfter": "2016-01-08T00:00:00Z"
 }),
 "signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g"
}
CODE

The newOrder response contains information about challenges. For more information, refer to the section 7.5.1 of RFC 8555.

newAuthz request

Request a pre-authorization.

POST /acme/newAuthz HTTP/1.1
Host: example.com
Content-Type: application/jose+json

{
  "protected": base64url({
    "alg": "ES256",
    "kid": "https://example.com/acme/acct/evOfKhNU60wg",
    "nonce": "uQpSjlRb4vQVCjVYAyyUWg",
    "url": "https://example.com/acme/newAuthz"
  }),
  "payload": base64url({
    "identifier": {
      "type": "dns",
      "value": "example.org"
    }
  }),
  "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps"
}
CODE

challenge request

Call EJBCA's ACME service verify the challenge response, that proves you possess control over the domain.

POST /acme/acct/{accountId}/chall/{challengeId} HTTP/1.1
Content-Type: application/jose+json

{
 "protected": base64url({
   "alg": "ES256",
   "kid": "https://example.com/acme/acct/evOfKhNU60wg",
   "nonce": "Q_s3MWoqT05TrdkM2MTDcw",
   "url": "https://example.com/acme/chall/prV_B7yEyA4"
 }),
 "payload": base64url({}),
 "signature": "9cbg5JO1Gf5YLjjz...SpkUfcdPai9uVYYQ"
}
CODE

finalizeOrder request

To generate the certificate.

POST /acme/acct/{accountId}/orders/{orderId}/finalize HTTP 1.1
Content-Type: application/jose+json

{
 "protected": base64url({
   "alg": "ES256",
   "kid": "https://example.com/acme/acct/evOfKhNU60wg",
   "nonce": "MSF2j2nawWHPxxkE3ZJtKQ",
   "url": "https://example.com/acme/order/TOlocE8rfgo/finalize"
 }),
 "payload": base64url({
   "csr": "MIIBPTCBxAIBADBFMQ...FS6aKdZeGsysoCo4H9P",
 }),
 "signature": "uOrUfIIk5RyQ...nw62Ay1cl6AB"
}
CODE

The response to the finalizeOrder call is the certificate.

Status Codes

HTTP Status CodeDescription
200Success
201Created
204No content
400Bad request
401Unauthorized
403Forbidden
404Not found
409Conflict
500Internal Server Error