Repository files navigation

This project is not maintained anymore. It is recommended to switch to acme.sh instead:https://github.com/haproxy/wiki/wiki/Letsencrypt-integration-with-HAProxy-and-acme.sh

Beware, the fixes to support for ACME v2 protocol were recently merged, theremight be some sharp edges but it should work.

This is a client implementation for ACME (Automatic Certificate ManagementEnvironment) protocol, currently draft IETF standard(https://tools.ietf.org/html/draft-ietf-acme-acme-12)

The protocol will be supported by Let's Encrypt project from March 2018.and it is expected that otherCertificate Authorities will support thisACME version in the future.

The main idea of this ACME client is to implement as much functionality insideHAProxy. In addition to supporting single instance HAProxy installations, wealso aim to support multi-instance deployments (i.e. you have a cluster of loadbalancers on which you want to use ACME issued certs).

By using the internal HTTP interface (and http client such as curl), you willbe able to execute the following:

• Upload your own account and domain keys (only RSA keys for now)
• Automatically register your account on ACME servers (linked to your accountkey)
• Request and receive certificates for your domains

The only thing you need to do on your own is to save the received certificatebundles and reload HAProxy.

• A modern HAProxy version (v1.8) with Lua support (check withhaproxy -vv | grep USE_LUA=1)
• haproxy-lua-http - Lua HTTP server/client for HAProxy Lua host
• json.lua - Lua JSON library
• luaossl - OpenSSL bindings for Lua

Install the required Lua libraries to proper LUA_PATH location, and configurehaproxy as follows:

global    log /dev/log local0 debug    nbproc 1    daemon    lua-load config.lua    lua-load acme.luadefaults    log global    mode http    option httplog    timeout connect 5s    timeout client 10s    timeout server 10slisten http    bind *:80    http-request use-service lua.acme if { path_beg /.well-known/acme-challenge/  }listen acme    bind 127.0.0.1:9011    http-request use-service lua.acmelisten acme-ca  bind 127.0.0.1:9012  server ca acme-v02.api.letsencrypt.org:443 ssl verify required ca-file letsencrypt-x3-ca-chain.pem  http-request set-header Host acme-v02.api.letsencrypt.org

letsencrypt-x3-ca-chain.pem is the concatenation of the active root certificate and intermediate certificate in one pem file, available here :https://letsencrypt.org/certificates/

Configuration is kept in a separate Lua file, where you must explicitly settermsOfServiceAgreed option totrue in order to be able to acquirecerts. Before doing that, please read latest Let's Encrypt terms of service andsubscriber agreement available athttps://letsencrypt.org/repository/

config = {    registration = {        -- You can read TOS here: https://letsencrypt.org/repository/        termsOfServiceAgreed = false,        contact = {"mailto:postmaster@example.net"}    },    -- ACME certificate authority configuration    ca = {        -- HAProxy backend/server which proxies requests to ACME server        proxy_uri = "http://127.0.0.1:9012",        -- ACME server URI (also returned by ACME directory listings)        -- Use this server name in HAProxy config        uri = "https://acme-v02.api.letsencrypt.org",    }}

Although Lua module is able to create account key or domain automatically, forperformance and security reasons we require that you create your keysseparately.

Currently, we only support RSA keys. For account key, key size should be4096bits, and for domain key 2048bits (minimal key sizes are also enforced byLet's Encrypt).

You can use the following commands to create keys. Note that you need a modernopenssl version, we don't useopenssl genrsa butopenssl genpkey, aswe're going to use the same command to create ECDSA keys in the future.

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:4096 -out account.keyopenssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out example.net.key

After you have provisioned your keys, you can run certificate order via HTTP.For example by using curl to POST data inmultipart/form-data format:

curl -XPOST http://127.0.0.1:9011/acme/order -F 'account_key=@account.key' \     -F 'domain=example.net' -F 'domain_key=@example.net.key' \     -F 'aliases=www.example.net,example.com,www.example.com' \     -o example.net.pem

Aliases are optional, and we use curl@ syntax to post files.The output is full certificate chain (with key appended), suitable for directconsumption by HAProxy.