ACME

ENTERPRISE

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 another identifier) and certificate management.

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.

URL Endpoints and Aliases

The ACME service is available on the following URLs.

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

If the user adds or removes an alias, it is set as the default ACME alias, if the operation results in exactly one alias.

An alias must consist of 1 to 250 alphanumeric non-blank characters case-sensitive including minus '-' and underscore'_'.

EJBCA Specifics

• Approvals in EJBCA for updating an end entity or certificate revocation cannot be used with ACME. Only approvals for ACME account management are supported.
• 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.
• End entities are managed in RA mode, which means end entities are created or reset (status = NEW) before a certificate is enrolled. This implicates that the 'Finish User' function available in the CA settings does not impact certificate enrollment with ACME (see CA Fields). Batch generation (clear text pwd storage) must be enabled in the end entity profile.
• Optional EJBCA ACME resources are available with client authentication enforced.

ACME Client Specifics

Each ACME client like Certbot or acme.sh might require their unique restriction to enroll certificates. Additionally, you must ensure that the certificate request posted by the ACME client fulfills the CA and profile restrictions. That is, enroll a certificate for several identifiers, additional subject DN attributes, certificate validity, or restrictions on the key specification used.

• Subject-DN attributes and subject-AN DNS entries are configured in the end entity profiles. For more information, see End Entity Profiles Fields and ACME#End Entity Profile Configuration.
• Key specification and certificate validity (usually < 1 year, or 6 months with Certbot 1.18) are configured in the certificate profiles, see Certificate Profile Fields.

Configuration

End Entity Profile Configuration

Besides requirements depending on your ACME client or individual requirements of your certificate request, the following settings should be used for an end entity profile used with ACME.

A certificate enrolled with ACME for one identifier only, must have at least one additional DNS or IP address SAN field.

Certificate Profile Configuration

Beside your ACME client used or individual requirements of your certificate request, the following settings should be used for a certificate profile used with ACME.

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 Alias 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.

Before an ACME alias can be used it must be edited and stored, even if its configuration remains unchanged.

Global Fields

The following fields are defined globally for all ACME operations.

ACME Alias Configuration

The following displays an ACME Alias configuration with username selection by the subject DN CN attribute and any type of DNS identifier.

The following table lists ACME specific fields for each alias in more detail.

ACME with Client Authentication

If Require client certificate is enabled, an ACME client requires a valid client certificate for HTTPs client authentication and sufficient access rules for certificate enrollment or revocation and other functions available with ACME. If the client certificate is revoked, requests to ACME resources will fail with the user message 'This ACME endpoint requires client certificate authentication'.

ACME over peers with client certificate authentication must not require the client certificate to be stored on the RA (set web.reqcertindb to false in web.properties).

Grant this set of access rules to the client certificate used for ACME.

•  /ca_functionality/create_certificate/
•  /ra_functionality/create_end_entity/
•  /ra_functionality/edit_end_entity/
•  /ra_functionality/view_end_entity/
•  /ra_functionality/revoke_end_entity/
•  /ca/${Name of CA}/
•  /endentityprofilesrules/${Name of EEP}/create_end_entity/
•  /endentityprofilesrules/${Name of EEP}/edit_end_entity/
•  /endentityprofilesrules/${Name of EEP}/view_end_entity/
•  /endentityprofilesrules/${Name of EEP}/revoke_end_entity/

Managing ACME External Account Bindings (EAB)

If Require External Account Binding is disabled, EAB requests nested in the ACME newAccount request are not considered. Otherwise, an ACME newAccount request without a nested EAB request will fail with an HTTP status code 400 (Bad Request) and the ACME error externalAccountRequired, if the client does not send a valid EAB with the newAccount request.

EJBCA supports the ACME compliant EAB with symmetric key MAC protected EAB requests. Additionally, EJBCA supports EAB with asymmetric private key signature protected EAB requests.

Combine ACME EAB with General Account Binding

The ACME EAB with symmetric key supports the combination with general external account bindings, see External Account Bindings.

The base64Url encoded Key Identifier of the ACME EAB must match one of the external account binding IDs, available in the EAB namespace configured in the relevant certificate profile. It does not matter if the ACME account was registered with this key identifier or if the value was stored after the registration.

ACME EAB with Symmetric Key Configuration

RFC8555 compliant ACME EAB

Key Identifier, MAC Algorithm and Insert base64Url Key must be shared with the ACME account holders in order to request a newAccount resource with a valid EAB request. For information on the message format, see ACME#newAccount request with RFC8555 compliant EAB.

ACME EAB with asymmetric private/public key configuration.

Asymmetric key signature protected EAB

Public Key or Certificate Fingerprint, Signature Algorithm (in case of public key) and Insert PEM Pulbic Key or Certificate must be shared with the ACME account holders in order to request a newAccount resource with a valid EAB request. The EAB request must be signed either with the certificate's signature algorithm or in the case of a public key, the one given by the user. For more information on the message format, see ACME#newAccount request with EAB with asymmetric key signature.

Identifiers and Challenge Validation

EJBCA currently supports the validation of domain and IP identifiers.

Domain identifiers can be validated either using the http-01 or dns-01 challenge as defined in section 8 of RFC 8555.  IPv4 or IPv6 identifiers can be validated with http-01 challenge only as defined in section 5 of RFC 8738 (JDK8). IPv6 identifier challenge validation requires a running application server with IPv6 enabled (-Djava.net.preferIPv6Addresses=true, Wildfly14 can be operated with IPv4 or IPv6 only).

HTTP Challenge (http01)

If the client chooses to use the http-01 challenge type, it intends to prove that it controls the domain or IP requested in the certificate by provisioning a resource under the same domain name or IP and port 80, i.e. http://example.org/.well-known/acme-challenge.

DNS Challenge (dns01)

If the client chooses to use the dns-01 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.

Approvals

Approvals can be used with ACME account management.

Approvals for the newAccount Resource

If approvals are used for the newAccount resource, requests to this resource return an HTTP 500 (Internal Server Error) response including an ACME problem message of type urn:ietf:params:acme:error:serverInternal indicating the state of the created approval request and its request ID. For example, A request to register your ACME account has been sent for approval. RequestID=123456789 after the first ACME resource request has been posted. Further requests return responses in the same matter indicating the state of the approval request either with state PENDING, REJECT, or EXPIRED. If the approval has been accepted, a request to the newAccount resource creates the account and returns the HTTP 201 (Created) as expected. If an approval has expired, it is no longer possible to register the keys for this account and you must generate new keys.

Approvals for the keyChange Resource

If approvals are used for the keyChange resource, requests to this resource return an HTTP 500 (Internal Server Error) response including an ACME problem message of type urn:ietf:params:acme:error:serverInternal indicating the state of the created approval request and its request ID, see example in ACME#Approvals for the newAccount Resource. If an approval request has expired, it is renewed automatically if the keyChange resource is requested.

Terms of Service 

When an ACME account is initially registered using the newAccount resource, the account holder must agree to ACME service Terms of Service. If 'Require client approval for changes of Terms of Service' is enabled and the Terms of Service have changed, requesting ACME resources except the newAccount resource will fail. To agree to the new ACME service Terms of Service, clients must either register a new account using the newAccount resource (with new keys) or agree to the new Terms of Service using the updateAccount resource (see ACME#examples). Therefore Agree to new Terms of Service allowed must be enabled.

Compatibility with ACME Clients

EJBCA is compatible with the following ACME clients (listed in Letsencrypt's list of compatible ACME clients). For information on installation and use, see the respective ACME client section:

• Certbot
• acme4j
• acme.sh

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.

• The 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 ACME#Enabling ACME.

Request 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 metadata.

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
   }
}

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({
    "contact": [
      "mailto:cert-admin@example.com"
    ],
    "termsOfServiceAgreed": true
  }),
  "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I"
}

newAccount request with RFC8555 compliant EAB 

Creates a new ACME account to EJBCA and returns it with the response.

The nested EAB request is signed using a symmetric key and HMAC algorithm shared by the CA.

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({
    "contact": [
      "mailto:cert-admin@example.com",
      "tel:+12025551212"
    ],
	"termsOfServiceAgreed": true,
	"externalAccountBinding": {
         "protected": base64url({
           "alg": "HS256",
           "kid": /* key identifier from CA */,
           "url": "https://example.com/acme/newAccount"
         }),
         "payload": base64url(/* same as in "jwk" above */),
         "signature": /* MAC using MAC key from CA */
       }
  }),
  "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I"
}

newAccount request with  EAB with asymmetric key signature

Creates a new ACME account to EJBCA and returns it with the response.

The nested EAB request is signed by the same JWK that signed the outer message. Compared to the standard EAB request (see above), this EAB requests payload contains a map including the account key to be registered. Additionally, this map contains the public key or certificate fingerprint shared by the CA and the signature over the account key by a private key shared with the CA and the agreed signature algorithm. 

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({
    "contact": [
      "mailto:cert-admin@example.com",
      "tel:+12025551212"
    ],
	"termsOfServiceAgreed": true,
	"externalAccountBinding": {
 	"protected": base64url({
        "alg": "HS256",
        "url": "https://example.com/acme/newAccount"
      }),
      "payload": base64url({
        "key": / * same as in "jwk" above * /,
        "cf":  / * certificate or public key fingerprint shared by the CA * /,
        "aks": / * signature of the account key using the signature algorithm 
                   and private key corresponding to the public key sent to the ACME CA * /,
      }),
      "signature": / * MAC using same MAC key that signed the outer JWS message. * /
  }),
  "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I"
}

updateAccount request

Updates an ACME accounts contact information.

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

{
  "protected": base64url({
    "alg": "ES256",
    "kid": "https://example.com/acme/acct/evOfKhNU60wg",
    "nonce": "6S8IqOGY7eL2lsGoTZYifg",
    "url": "https://example.com/acme/acct/evOfKhNU60wg"
  }),
  "payload": base64url({
    "contact": [
      "mailto:cert-admin@example.com",
    ]
  }),
  "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I"
}

updateAccount request and agree to new Terms of Service

Updates an ACME agreement to the new Terms of Service if they have changed. This is a non-RFC compliant function. To use this newAccount request Require client approval for changes of Terms of Service and Agree to new Terms of Service allowed must be enabled.

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

{
  "protected": base64url({
    "alg": "ES256",
    "kid": "https://example.com/acme/acct/evOfKhNU60wg",
    "nonce": "6S8IqOGY7eL2lsGoTZYifg",
    "url": "https://example.com/acme/acct/evOfKhNU60wg"
  }),
    "termsOfServiceAgreed": true
  }),
  "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I"
}

updateAccount request and account deactivation

Deactivates an ACME account (not reversible).

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

{
  "protected": base64url({
    "alg": "ES256",
    "kid": "https://example.com/acme/acct/evOfKhNU60wg",
    "nonce": "ntuJWWSic4WVNSqeUmshgg",
    "url": "https://example.com/acme/acct/evOfKhNU60wg"
  }),
  "payload": base64url({
    "status": "deactivated"
  }),
  "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I"
}

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"
}

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

newAuthz request

Request a pre-authorization for an identifier (one request per identifier).

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"
}

challenge request

Call EJBCA's ACME service to 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"
}

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"
}

The response to the finalizeOrder call is the certificate.

HTTP Status Codes