[RFC] Implement ACME Automatic SSL for Apache APISIX Gateway

[praswicaksono]

Description

Introduction

This RFC proposes the implementation of ACME (Automatic Certificate Management Environment) to automate the process of obtaining and renewing SSL/TLS certificates for the Apache APISIX Gateway. This will enhance security by ensuring that all communications are encrypted and up-to-date with minimal manual intervention.

Motivation

Currently, managing SSL certificates for the Apache APISIX Gateway involves manual processes that are prone to errors and can lead to downtime if certificates expire. By integrating ACME, we can automate this process, reducing the risk of expired certificates and improving the overall security posture.

Proposal

Introducing new way to automatically manage SSL certificate, this proposal intend to not make any modification to current process to manage certificate. Let user decide how they want to manage certificate via yaml config

This proposal will use this library to automatically handle certificate management. This library support multiple storage backend such as etcd or local file.

• https://github.com/fffonion/lua-resty-acme

Example implementation

config

apisix:
  ssl:
    automatic: true
    acme:
      some-comfig:

ngx template

{% if acme_enabled then %}
ssl_certificate_by_lua_block {
    require("resty.acme.autossl").ssl_certificate()
}
location /.well-known {
    content_by_lua_block {
        require("resty.acme.autossl").serve_http_challenge()
    }
}
{% else %}
ssl_client_hello_by_lua_block {
    apisix.http_ssl_client_hello_phase()
}

ssl_certificate_by_lua_block {
    apisix.http_ssl_phase()
}
{% end %}

Pros

• No need to create bash script to generate SSL certificate and update via admin api
• Fully automatic including automatic renewal

Cons

• Only able to use one method to manage SSL certificate, either it manual or automatic

[membphis]

@praswicaksono I carefully review your proposal. There are one basic question we need to answer first.

Only able to use one method to manage SSL certificate, either it manual or automatic

I think this is unacceptable, here is my explanation:

The APISIX had supported those cases at same time:

1. Allow to store the SSL certificates in the etcd(set through by Admin API): https://apisix.apache.org/docs/apisix/ssl-protocol/#examples
2. Allow to reference the SSL certificates from the ENV: https://apisix.apache.org/docs/apisix/terminology/secret/#use-environment-variables-to-manage-secrets
3. Allow to reference the SSL certificates from the Vault: https://apisix.apache.org/blog/2023/07/09/apisix-integrates-with-vault/#deploy-and-configure-vault-service

In my opinion, those are the thing we should do:

1. Support ACME, it is ok
2. Allows ACME to be used with other SSL certificate management methods at the same time, it should be ok too

[praswicaksono]

@membphis I see so you are suggesting to support ACME in same way we support referencing certificate via vault?

For example if we want to to enable acme we must create SSL record

curl -i "http://127.0.0.1:9180/apisix/admin/ssls" -X PUT -d '
{
  "id": "quickstart-tls-client-ssl",
  "sni": "test.com",
  "cert": "$acme,
  "key": "$acme"
}'

[membphis]

you can take a at: https://docs.konghq.com/hub/kong-inc/acme

fetch the latest certificates by control API