Overview

SecuriTLS includes an ACME server that allows compatible ACME clients to request certificates from a selected SecuriTLS private certificate authority.

The ACME server is another certificate issuance interface within SecuriTLS. Certificates can also be created and managed through the SecuriTLS platform and API.

ACME is useful for services and systems that already support automated certificate enrollment and renewal through the Automated Certificate Management Environment protocol.

Requirements

Before configuring an ACME client, you need:

• A SecuriTLS root or intermediate CA that can issue leaf certificates
• External Account Binding credentials generated from the selected CA in SecuriTLS
• The CA-specific ACME directory URL
• A compatible ACME client with External Account Binding support
• A domain or hostname permitted by the EAB credential's allowed identifier policy
• Network access from the ACME client to the SecuriTLS ACME endpoints over HTTPS
• HTTP port 80 connectivity from the SecuriTLS validation path to the requested hostname

The selected CA must remain available and capable of signing new certificate requests. A deleted, expired, revoked, renewed, rekeyed, or otherwise unavailable CA may not be able to issue new certificates.

Directory URL

Each issuing CA has its own ACME directory URL:

https://www.securitls.com/acme/<CA_ID>/directory

Replace <CA_ID> with the SecuriTLS database ID of the CA that should sign certificates requested through that directory.

Example:

https://www.securitls.com/acme/6a39e9de9d46b16778b41ff0/directory

The directory response advertises the ACME resources supported by SecuriTLS, including account creation, order creation, nonce issuance, and certificate revocation.

Directory response

A directory request returns an object similar to:

{
  "newNonce": "https://www.securitls.com/acme/<CA_ID>/new-nonce",
  "newAccount": "https://www.securitls.com/acme/<CA_ID>/new-account",
  "newOrder": "https://www.securitls.com/acme/<CA_ID>/new-order",
  "revokeCert": "https://www.securitls.com/acme/<CA_ID>/revoke-cert",
  "meta": {
    "termsOfService": "https://www.securitls.com/terms",
    "website": "https://www.securitls.com",
    "externalAccountRequired": true
  }
}

The externalAccountRequired value tells compatible ACME clients that External Account Binding credentials must be supplied when the ACME account is first registered.

Other ACME resources, such as account, order, authorization, challenge, finalization, and certificate download URLs, are returned as the ACME workflow progresses.

ACME workflow

A typical SecuriTLS ACME enrollment follows this process:

1. An authorized SecuriTLS user generates EAB credentials from the selected certificate authority.
2. The ACME client retrieves the CA-specific ACME directory.
3. The client obtains a replay nonce.
4. The client registers an ACME account using the generated EAB key ID and HMAC key.
5. SecuriTLS verifies the External Account Binding request and associates the resulting ACME account with the selected CA, allowed identifiers, and satellite configuration.
6. The client creates an order containing one or more requested identifiers.
7. SecuriTLS confirms that every requested identifier is allowed by the account's EAB policy.
8. SecuriTLS creates authorizations and HTTP-01 challenges for those identifiers.
9. The client publishes the HTTP-01 challenge response.
10. SecuriTLS validates the challenge from the platform or, when the CA is assigned to a satellite, from that same satellite.
11. The client submits a certificate signing request to finalize the order.
12. SecuriTLS validates the CSR and issues the certificate using the CA identified in the directory URL.
13. The client downloads the issued certificate.

Challenge validation

SecuriTLS currently supports ACME HTTP-01 challenge workflows.

During an HTTP-01 challenge, the ACME client publishes a token at:

http://<DOMAIN>/.well-known/acme-challenge/<TOKEN>

SecuriTLS requests that URL and checks the returned key authorization before marking the authorization valid.

The validation request is performed from one of two locations:

• If the issuing CA is not assigned to a satellite, the challenge URL must be reachable from the SecuriTLS platform validation service.
• If the issuing CA is assigned to a satellite, the challenge URL must be reachable from that same satellite.

The requested hostname must resolve correctly from the applicable validation location. Private DNS, split-horizon DNS, firewalls, reverse proxies, redirects, web-server routing rules, and port 80 restrictions can prevent challenge validation from succeeding.

Configure an ACME client

Before issuing certificates, generate External Account Binding credentials from the selected CA in SecuriTLS.

The generated credential includes:

• The CA-specific ACME directory URL
• An EAB key ID
• An EAB HMAC key
• The credential expiration time
• The DNS identifiers permitted for the resulting ACME account

The EAB HMAC key is shown only when it is generated. Copy and store it securely before closing the dialog.

Use the EAB credentials to register the ACME account once. After registration, the client uses its locally stored ACME account private key for later orders and renewals.

https://www.securitls.com/acme/<CA_ID>/directory

The exact registration command depends on the client. The client must support External Account Binding.

acme.sh example

First, generate EAB credentials from the issuing CA in SecuriTLS. Then register the ACME account:

acme.sh \
            --register-account \
            --server "https://www.securitls.com/acme/<CA_ID>/directory" \
            --eab-kid "<EAB_KEY_ID>" \
            --eab-hmac-key "<EAB_HMAC_KEY>"

The EAB credential is used only to authorize the initial account registration. After registration, acme.sh stores its ACME account key and account configuration locally.

Issue a certificate using the same acme.sh home and configuration:

acme.sh --issue \
            --server "https://www.securitls.com/acme/<CA_ID>/directory" \
            -d "service.example.com" \
            --standalone

The --standalone option starts a temporary HTTP server for HTTP-01 validation. Port 80 must be reachable from the applicable SecuriTLS validation location.

When the CA is assigned to a satellite, the requested hostname and port 80 must be reachable from that same satellite. Otherwise, they must be reachable from the SecuriTLS platform validation service.

The requested hostname must also match one of the allowed DNS identifiers configured when the EAB credential was generated.

Certbot example

SecuriTLS requires External Account Binding during ACME account registration. Confirm that your Certbot version and configuration support supplying an EAB key ID and HMAC key for a custom ACME server.

After the ACME account has been registered, Certbot can use the CA-specific directory through its --server option:

certbot certonly \
            --server "https://www.securitls.com/acme/<CA_ID>/directory" \
            --standalone \
            -d "service.example.com"

The requested identifier must be permitted by the EAB credential used to register the account.

Because certificates are issued by your private CA, the resulting certificate will only be trusted by systems that trust the appropriate SecuriTLS root or intermediate CA chain.

Private certificate trust

SecuriTLS ACME certificates are signed by the private CA selected in the directory URL. They are not automatically trusted by public browsers, operating systems, or external clients.

Install the appropriate root CA certificate into the trust stores of systems that need to trust certificates issued through your private ACME directory.

The trust model is the same whether the certificate is issued through ACME, the SecuriTLS user interface, or the API.

Certificate records in SecuriTLS

Certificates issued through ACME are recorded in SecuriTLS so they can participate in supported lifecycle, inventory, revocation, and audit workflows.

The ACME client normally generates and retains the leaf private key. SecuriTLS receives the CSR and signs the public key contained in that request.

Because the ACME client controls the private key, SecuriTLS may not be able to perform platform-managed private-key deployment or key recovery for that certificate unless a separate custody workflow is configured.

Certificate renewal

Renewal is initiated by the ACME client according to that client's renewal schedule and configuration.

The client creates a new order and submits a new CSR. SecuriTLS issues a new certificate and stores the resulting certificate record.

Continue running the client through its normal timer, scheduled task, service, or container workflow so renewals occur before expiration.

Certificate revocation

Compatible ACME clients can submit revocation requests through the directory's revokeCert endpoint.

Revocation updates the certificate state in SecuriTLS and connects to the CA's supported CRL and OCSP workflows.

See the related documentation for additional revocation behavior:

Security model

SecuriTLS requires External Account Binding for ACME account registration. An EAB credential is generated by an authenticated SecuriTLS user and is tied to a specific issuing CA.

EAB credentials can restrict the DNS identifiers that the resulting ACME account may request. Credentials also expire and are normally limited to a single account registration.

During registration, the client uses the EAB key ID and HMAC key to bind its new ACME account public key to the SecuriTLS-issued credential.

After registration, protected ACME requests use JSON Web Signatures. SecuriTLS validates the protected request header, account identity, request URL, replay nonce, and signature before processing the request.

Replay nonces are single-use values intended to prevent a valid signed request from being replayed.

The ACME client retains its account private key and certificate private keys locally. Protect these keys and the EAB HMAC key from unauthorized access.

The EAB HMAC key is needed only for initial account registration. Later certificate issuance and renewal requests are authenticated using the ACME account key.

Troubleshooting

ACME account registration fails

• Confirm the EAB key ID and HMAC key were copied exactly as shown by SecuriTLS.
• Confirm the EAB credential has not expired or already been used.
• Confirm the EAB credential was generated for the same CA ID used in the directory URL.
• Confirm the ACME client supports External Account Binding with HS256.
• Generate a new EAB credential if the HMAC key was lost or the credential is no longer valid.

The requested identifier is rejected

• Confirm the hostname matches an allowed identifier configured when the EAB credential was generated.
• A wildcard such as *.example.com permits a name such as server.example.com, but does not permit the bare name example.com.
• Generate a new EAB credential and register a new ACME account when a different identifier policy is required.

The client cannot load the directory

• Confirm the directory URL uses the correct CA ID.
• Confirm the SecuriTLS hostname is reachable over HTTPS.
• Confirm the selected CA still exists and is accessible.
• Inspect the client output for TLS or JSON parsing errors.

HTTP-01 validation fails

• Confirm the requested hostname resolves correctly from the applicable validation location.
• If the CA is assigned to a satellite, confirm the hostname and TCP port 80 are reachable from that same satellite.
• If the CA is not assigned to a satellite, confirm the hostname and TCP port 80 are reachable from the SecuriTLS platform.
• Confirm the challenge token is available at /.well-known/acme-challenge/.
• Confirm the response body exactly matches the expected ACME key authorization.
• Check private DNS, split-horizon DNS, reverse-proxy, redirect, CDN, web-server routing, and firewall rules.
• Confirm another service is not intercepting the challenge request.

The certificate is not trusted

• Install the issuing private PKI root certificate in the relying system's trust store.
• Include the required intermediate chain when configuring the service.
• Confirm the service is presenting the correct certificate chain.

Finalization fails

• Confirm all order authorizations are valid.
• Confirm the CSR contains the same identifiers requested by the order.
• Confirm the CSR is valid DER encoded data submitted using the expected ACME base64url representation.
• Confirm the selected CA can still sign leaf certificates.