NGINX introduces native support for the ACME protocol

The NGINX development team has announced the availability of a preview release of ACME support in NGINX. This release introduces the new module ngx_http_acme_module, designed to offer built-in directives that allow you to request, install, and renew certificates directly within the NGINX configuration, without the need for external procedures. ACME support is based on the SDK NGINX-Rust and is distributed as a dynamic module written in Rust, made available to both NGINX Open Source users and enterprise customers. NGINX Plus through the platform NGINX One.

The native integration of the ACME protocol into NGINX represents a significant step in simplifying SSL/TLS certificate management. The ability to directly configure the issuance and renewal process using NGINX directives significantly reduces the risk of manual errors while also improving operational efficiency. This approach eliminates much of the complexity and overhead typically associated with managing digital certificates, and reduces reliance on external tools like Certbot. The result is a more secure, streamlined, and centralized workflow with a smaller attack surface and more transparent management.

Another advantage over external tools is the lack of platform constraints. The native implementation in NGINX ensures superior portability and independence, making it suitable for a wide range of contexts, from established corporate web infrastructures to rapidly evolving cloud environments. This makes the new module a versatile and reliable solution, capable of meeting the scalability, security, and automation needs that characterize modern application architectures.

What is ACME?

The protocol ACME (Automated Certificate Management Environment) is a communication system designed to automate operations related to digital security certificates, particularly SSL/TLS. ACME allows you to manage the entire lifecycle of a certificate: from initial issuance to validation, renewal, and eventual revocation. This allows clients to interact with a Certification Authority (CA) without the need for manual intervention, reducing time, costs, and complexity. The availability of a standardized protocol has made it much easier to adopt HTTPS as a basic requirement for websites, applications, and online services that require encrypted and secure communications.

The development of the ACME protocol was initiated by theInternet Security Research Group (ISRG) within the project Let's Encrypt, launched in late 2015. The initiative had a revolutionary impact: for the first time, free and easily obtainable SSL/TLS certificates were offered, at a time when acquiring certificates was often a manual, costly, and error-prone process. The automation introduced by ACME radically changed the paradigm, transforming the adoption of HTTPS from an advanced option to the de facto standard for the modern web.

Over time, the protocol was further improved with the specification ACMEv2, which introduced new features and expanded its use cases. Key updates include support for new challenge types for identity verification, more flexible authentication methods, the introduction of wildcard certificates (useful for protecting entire domains and subdomains with a single certificate), and increased overall security robustness. Thanks to these developments, ACME is now considered a cornerstone of automated digital certificate management and an essential tool for ensuring the widespread availability of encrypted and secure connections globally.

How does the ACME protocol work?

There are actually two explanations for this question. A high-level one that covers just the basics, and a more in-depth one that covers the technical side. We'll try to keep things high-level.

Once the ACME agent is installed and properly configured, the process is actually quite simple. We'll discuss configuration shortly, but for now, keep in mind that during the verification process that occurs when the agent is installed, a key pair will be generated for use by the agent and the CA. These keys are sometimes called "authorization keys."

Issue/Renewal

To obtain a digital certificate, the agent must generate a Certificate Signing Request (CSR) for the desired domain and send it to the Certification Authority (CA). The entire process is secure via the HTTPS, ensuring the integrity and confidentiality of information.

• The agent generates a CSR for the domain
  The first phase consists in the creation of the Certificate Signing Request, which includes domain identification data (e.g. example.com) and the public key that will be associated with the certificate. This document is the starting point of the validation process.

• The agent signs the public key generated along with the CSR with the corresponding private key
  To ensure that the public key is truly bound to the domain and has not been tampered with, the agent uses its private key to sign the CSR. This establishes a secure cryptographic link between the public/private key pair.

• The agent signs the entire CSR with its private authorization key
  In addition to the signature associated with the domain key pair, the agent also applies the authorization private key, generated during the initial configuration of the ACME protocol. This second signature serves to prove to the CA that the request comes from a legitimate client authorized to request certificates.

• The CA verifies both signatures and issues the certificate
  The Certification Authority checks the validity of the signatures, the accuracy of the CSR, and the association with the domain. Once these checks are successfully completed, it issues the SSL/TLS digital certificate.

• The agent receives the certificate and installs it on the relevant domain
  Once issued, the certificate is sent to the agent, who installs it in the server's configuration. From then on, the domain is accessible via secure HTTPS connections, with the certificate valid and recognized by browsers and clients.

You'll notice that the agent we're talking about isn't a little guy residing on your server, as the icons I've chosen might suggest. So, there's no need to point that out. It's just more fun to imagine him that way.

In any case, this process works more or less the same way with renewals. The agent can be configured to ping the CA at regular intervals to rotate keys or replace entire certificates. And all of this happens behind the scenes, without any human intervention.

withdrawal

As with the emission, the revoking an SSL/TLS certificate It requires the agent's intervention, which must generate and sign an official request. In this case, however, the request is not for obtaining a new certificate, but for invalidating an existing one. The Certification Authority (CA) then revokes the certificate and updates the public registers that allow browsers and clients to check the certificate's status.

• The agent generates a revocation request for the SSL/TLS certificate
  The agent creates a document that identifies the certificate to be revoked, including the serial number and the information needed to uniquely link it to the original issuance.

• The agent signs the request with its private key
  To ensure that the request actually comes from the certificate holder, the agent uses its private key to digitally sign it. This proves to the CA that the revocation was not requested by an unauthorized third party.

• The CA verifies the signature to ensure that the request is authorized.
  The Certification Authority checks the validity of the signature and its correspondence with the public key associated with the certificate. If the verification is successful, the CA recognizes the request as legitimate.

• The CA revokes the certificate
  Once the authenticity of the request is confirmed, the certificate is officially revoked, making it no longer valid for establishing secure connections.

• Certificate revocation status is published to CRLs and OCSP responders
  Finally, the CA updates the Certificate Revocation List (CRL) and the responders Online Certificate Status Protocol (OCSP)These systems allow browsers and clients to check the validity status of the certificate in real time, ensuring that any compromised certificates can no longer be used for reliable HTTPS connections.

ACME Workflow in NGINX

The ACME workflow within NGINX can be described as a sequence of four main phases, which allow for the automated management of the entire digital certificate lifecycle:

1. Setting up the ACME server
   At this stage, NGINX is configured to communicate with a Certificate Authority that supports the ACME protocol. This establishes the point of contact from which to request, validate, and obtain SSL/TLS certificates.

2. Shared memory allocation
   To ensure efficiency and stability, the NGINX ACME module uses shared memory areas to manage request information and validation status. This architecture allows for reliable coordination between the various server processes.

3. Setting up challenges
   NGINX is instructed to handle validation challenges required by the CA, such as HTTP-01 or DNS-01. This step is essential for proving domain ownership and authorizing certificate issuance.

4. Issuance and renewal of certificates
   Once validation is complete, the certificate is automatically issued and installed. The ACME module also handles periodic renewal, eliminating the need for manual intervention and reducing the risk of service interruptions due to expired certificates.

Setting up the ACME server

To enable ACME features in NGINX, the first step—and the only required one—is to specify the ACME server directory URL. This parameter tells the module which Certificate Authority to contact for issuing, validating, and renewing SSL/TLS certificates.

Beyond this minimum requirement, you can define additional information useful for the module's proper functioning. For example, you can specify contact information to be used in the event the Certification Authority needs to report issues related to issued certificates. You can also configure the path to store module data, such as status information or the keys required for the validation process. These additional options, while not mandatory, help make management more reliable and ensure better operational control.

acme_issuer letsencrypt { uri https://acme-v02.api.letsencrypt.org/directory; # contact admin@example.test; state_path /var/cache/nginx/acme-letsencrypt; accept_terms_of_service; }

Shared memory allocation

The implementation of ACME support in NGINX also introduces the optional directive acme_shared_zone, designed to manage certificates, private keys, and challenge data from all configured issuers in a common area. This shared memory area allows different server processes to access the same information consistently, avoiding redundancies and simplifying internal coordination.

By default, the zone size is 256 KB, a sufficient value for simple scenarios. However, in more complex environments or with a large number of certificates to manage, this size can be increased as needed. The ability to adjust the dedicated memory makes the approach more flexible, ensuring that NGINX can adapt to both lightweight installations and more demanding enterprise environments.

acme_shared_zone zone=acme_shared:1M;

Setting up challenges

In the preview release, the ACME implementation in NGINX currently supports HTTP-01 challenge, used to verify the client's ownership of the domain. To properly manage this mechanism, you must define a listener on port 80, capable of receiving and responding to validation requests sent by the Certification Authority. This configuration ensures that the server can automatically and transparently demonstrate control over the domain, a prerequisite for issuing an SSL/TLS certificate.

server { # Listener on port 80 is required to process ACME HTTP-01 challenges listen 80; location / { # Serves as a basic 404 response while listening for challenges return 404; } }

The development team has also planned to extend support to other types of challenges, including TLS-ALPN-01 e DNS-01, which will be introduced in future releases. These additional methods will expand the validation capabilities, offering greater flexibility in complex scenarios such as load balancers, multi-server environments, or where direct access to port 80 is not practical.

Issuance and renewal of certificates

To automate the issuance and renewal of TLS certificates in NGINX you can use the directive acme_certificate within the relevant server blockThis directive requires the list of identifier (the domains) for which certificates should be dynamically generated. The list is typically defined using the directive server_name, which specifies the domain names associated with the server block.

A typical example is the configuration of a server block for the domain example.domain, using the previously defined ACME issuer (for example, Let's Encrypt's). In this scenario, the module automatically takes care of requesting and installing the SSL/TLS certificate, as well as managing its periodic renewals, without the need for manual intervention.

server { listen 443 ssl; server_name .example.com; acme_certificate letsencrypt; ssl_certificate $acme_certificate; ssl_certificate_key $acme_certificate_key; ssl_certificate_cache max=2; }

It is important to underline that not all values accepted by the directive server_name are considered valid identifiers. The preview version does not support wildcard (Eg *.example.domain) nor the use of regular expressionsThese limits will be progressively revised in future implementations to broaden compatibility with more complex scenarios.

Once the certificate is obtained, the related information can be managed through variables $acme_certificate e $acme_certificate_key, which provides the module with the data needed to enable SSL/TLS encryption on the associated domain. This integration simplifies the operational flow and ensures consistent certificate management directly within the NGINX configuration.

Why all this is important

The global spread of HTTPS has been decisively accelerated by the introduction of the protocol ACME, which has made web security a basic requirement, not an option. By automating the entire SSL/TLS certificate lifecycle—from issuance to renewal to day-to-day management—ACME has eliminated much of the operational complexity and costs associated with manual processes, making securing online communications simpler and more accessible.

ACME's role is not limited to the traditional web. With the exponential growth of IoT devices, API services, and infrastructure, edge computing, the protocol is also establishing itself as a fundamental element in security automation in distributed and highly scalable contexts. In such scenarios, the ability to provide reliable and always up-to-date certificates is a crucial requirement to ensure system integrity, privacy, and resilience.

Native support for ACME within Nginx confirms the strategic importance of this protocol for the future of security, automation, and scalability. All indications are that ACME will remain the cornerstone of certificate automation for a long time to come, extending its impact well beyond the web. Since security is now an integral part of network standards, it's natural to expect continued evolution in both application deployment models and security requirements, driving further improvements and enhancements to the protocol itself.

Looking to the future, the NGINX development team has expressed its commitment to progressively growing its implementation to align not only with current user and customer needs, but also with emerging ones. The goal is to provide features that are ready to address new scenarios, with an approach that balances reliability, security, and innovation.

How to get started

You can already experience native ACME support in NGINX.

• For users open source, downloadable pre-built packages are available.

• For enterprise customers of NGINX Plus, through the platform NGINX One, the module is provided as a dynamic component supported by F5.

More information about configuring and using the module can be found in the official NGINX documentation.