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

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 new ACME Terms of Service if they have changed.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 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'_'.


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

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.

FieldValue
UsernameLeave empty
Password (or Enrollment Code)Leave empty
Batch generation (clear text pwd storage)Enable if you reset the end entity for certificate enrollment. If you do not generate RANDOM with the RA name generate scheme, you must enable this option.
End Entity E-mailUse, Not 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
SAN DNS Name or IP addressNot required, Modifiable. Add as many DNS or IP identifiers as you require for your certificates.

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.

FieldValue
Available Key AlgorithmsChoose allowed key algorithms
Available ECDSA curvesChoose allowed ECDSA key algorithms
Available Bit LengthsChoose desired key length in case of RSA keys
Validity or end date of the certificateValidity. I.e. 6mo, 1y or 395d.
Extended Key UsageServer Authentication
ApprovalsClear. Ensure to not select any Approvals as EJBCA supports approvals for ACME account management only.
Available CAs<The CA signing the certificate>
Single Active Certificate ConstraintRevokes all previously enrolled certificates of an end entity enrolled with this or another certificate profile with this option enabled. Only relevant if the end entity name is not generated randomly using the RA name generation scheme.

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.

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

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.

FieldDescription
RA Name Generation Scheme

DN: Will take a part of the request DN, and use it as the username (use the list to choose which parts). Several DN attributes can be specified to have a fall-back. For example: UID;SN;CN. First, try UID. If it does not exist try SN, etc.
RANDOM (default): Uses the generated 43 character long ACME order ID.
FIXED: Enter the DN attributes manually as a semicolon-delimited String (e.g. CN;UID;SN), instead of adding the values using the Add button when the DN optionn is selected.
USERNAME: Use the entire request DN as username. It is possible to use a constant username, as long as no DN attribute is specified, i.e. myUser.

Enable Batch generation in the end entity profile, if you don't use RANDOM usernames (see End Entity Profile Configuration).

RA Name Generation PrefixSpecify a prefix to the generated username. '${RANDOM}' can be used to have 12 random chars as prefix.
RA Name Generation PostfixSpecify a postfix to the generated username. '${RANDOM}' can be used to have 12 random chars as postfix.
End Entity Profile

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

(warning) Keep in mind that ACME identifiers (i.e. DNS name, IP number) to be included in the certificate are included in its SAN if specified in CSRs SAN (normal case). At least one identifier is written into the subject DN (i.e. certbot only uses SANs in the CSR). Multiple identifiers are written into the subject DN, if the CSRs subject DN contains multiple CNs.

Pre-Authorization AllowedPre-authorization, as defined in section 7.4.1 of RFC 8555. The ACME client may authorize the certificates identifiers before order creation.
Wildcard Certificate Issuance AllowedWhether this alias can be used to issue certificates with wildcard DNS names in their SANs. Refer to section 7.1.3 of RFC 8555.
Wildcard Certificate with http-01 Challenge AllowedIf disabled, no http-01 challenge for identifiers with a wildcard (i.e. *.primekey.com) is generated. Only active if 'Wildcard Certificate Issuance Allowed' is enabled. Default: enabled.
DNS identifier challenge typesSelect Any type to create all challenge types. If only a certain challenge type is required, select for example the http-01, dns-01 or tls-alpn-01 challenge only.
Site URLURL to a website describing this CA. Optional. Refer to section 7.1.1 of RFC 8555.
Terms of Service URL

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

Changes of Terms of Service URLURL to advise how to handle changes of your terms of service for ACME. Refer to section 7.3.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. Default: enabled.

Agree to new Terms of Service allowedSpecifies whether users are allowed to agree to new Terms of Service after they have changed. ACME clients must request the updateAccount resource with termsOfServiceAgreed set to true. If not allowed, clients have to request a new account (including new keys). Only active if Require client approval for changes of Terms of Service is enabled. Default: enabled.
DNS ResolverA specified DNS resolver, used when processing dns-01 and tls-alpn-01 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.
Authorized Redirect PortsList of authorized ports for client side redirects for the http-01 challenge validation for DNS identifiers. Default is 22,25,80,443. Leave empty for no restrictions.
Order ValidityThe time span within the challenges for the orders identifiers have to be completed. Format is human readable validity with second precision, i.e. 10d 12h or 30s 30m 1h. The format string is normalized when the form data is stored. Default value is 1h.
Require approval for account registrationApproval profile to be applied for ACME account registration, see Approvals. Default: None.
Require approval for account key changeApproval profile to be applied for ACME account key change, see Approvals. Default: None.
Require client certificateThe ACME client must authenticate using a valid client certificate and authorization to view, create and edit end entities as well as access the signing CA, and to enroll certificates.
Preferred Root CA subject DNIf there are cross-certificate chains present for the designated CA, then this setting can be used to mandate a single cross-certificate chain for all clients requesting through this configuration. It has a default value of "default" and to remove any such restriction, delete the value and save the configuration. When it has a default value, finalizeOrder contains the link to the chain with the default CA certificate chain, and link headers in the cert response contain links to alternate chains as mentioned in section 7.4.2 of RFC 8555. If a chain is mandated, finalizeOrder contains the link to the chain with configured cross chain and the cert response does not include any links for alternate certificate chains.
Require External Account BindingExternal Account Binding (EAB), as defined in section 7.4.3 of RFC 8555.

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

Initial ACME EAB with symmetric key configuration.

RFC8555 compliant ACME EAB

FieldDescription
EAB Type

RFC8555 compliant (MAC - symmetric key)

Generate KeyGenerates a 256 bits AES symmetric key. The key is stored either encrypted or not (see Encrypt Key). It is rendered as base64Url encoded value in the text field Insert base64Url Key. The SHA-1 hash of the AES key is generated and stored as a base64Url encoded value as key identifier and rendered in the text field Key Identifier as is.
Key IdentifierThe secret key identifier of the symmetric key. The value must not be empty, but max. 256 characters long and base64Url encoded. The value does not need to be a fingerprint depending on any known algorithm. It is entered by the user. Since the EAB is stored at the ACME alias configuration, EJBCA only verifies, that the EAB message contains the correct key identifier.
MAC AlgorithmThe secret MAC algorithm to sign the MAC protected EAB request (only HS256 at the time).
Encrypt KeyEncrypts the shared key in the data store if selected (rendered in clear text in the GUI).
Encryption KeyThe crypto token used to encrypt / decrypt the shared key.
Encryption Key AliasThe key alias of the crypto tokens key pair used to encrypt / decrypt the shared key.
Upload PEM/DER Key

Upload PEM or DER encoded symmetric AES key or a byte sequence. If a key is uploaded, the Insert base64Url Key below does not need to be specified and is populated after the form is saved.
To generate a 192 bits AES key file, use 'openssl rand 192 > name.key' or 'cat /dev/urandom | head -c 192 > name.key'.

Insert base64Url KeySymmetric key. The value must not be empty (except a file is uploaded),  but max. 512 characters long and base64Url encoded.

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 newAccount request with RFC8555 compliant EAB.

ACME EAB with asymmetric private/public key configuration.

Initial ACME EAB with symmetric key configuration.

Asymmetric key signature protected EAB

FieldDescription
EAB TypeCertificate / Public Key (asymmetric account key signature)
Use public keySet to true, if you want to upload a public key or set to false if you want to upload an X.509 certificate. If set to true and a certificate is uploaded, only the public key is stored and the fingerprint is generated using the signature algorithm selected.
Signature AlgorithmThe secret signature algorithm to sign the signature protected EAB request. It is considered only if a public key is used. Otherwise, this field will be filled with the certificate's signature algorithm after the form is saved.
Upload PEM/DER Public Key or CertificateUpload PEM or DER encoded RSA or ECDSA public key or X.509 certificate. If a certificate or key is uploaded, the text fields Public Key or Certificate Fingerprint and  Insert PEM Public Key or Certificate below do not need to be filled manually but are populated after the form is saved.
Public Key or Certificate FingerprintThe public key or certificate fingerprint. The value must not be empty, but max. 256 characters long and base64Url encoded. The value does not need to be a fingerprint depending on any known algorithm. It can be overwritten by the user. Since the EAB is stored at the ACME alias configuration, EJBCA only verifies, that the EAB message contains the correct string. This string might be used as a secret message, which is transmitted on a separate channel.
Insert PEM Public Key or CertificatePEM formatted X.509 certificate or RSA or ECDSA public key including boundaries. The value must not be empty,  but max. 4096 characters long.

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 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 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 Workflow 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:

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

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

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

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

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

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

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

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

HTTP Status Codes

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