On the fly free SSL registration and renewal inside OpenResty/nginx, Envoy and any Golang TLS program, with Let's Encrypt.
The simplessl automatically and transparently issues SSL certificates from Let's Encrypt as requests are received, when a certificate needs a renewal, it automatically renews the certificate asynchronously in background.
The OpenResty plugin uses the ssl_certificate_by_lua functionality in OpenResty 1.9.7.2+.
For Envoy, simplessl implements SDS server to provide SSL certificates to the data plane.
By using simplessl to register SSL certificates with Let's Encrypt, you agree to the Let's Encrypt Subscriber Agreement.
Disclaimer: I got initial inspires and stole some code from the awesome project lua-resty-auto-ssl and Go's autocert package. Also, this program uses Lego to solve dns-01 challenge. Many thanks 😀
NOTE: currently this program is designed to be used inside intranet, security features are not seriously considered, be sure to PROTECT your certificate server properly and keep an eye on security concerns.
Compared to other similar projects, this project provides a centric certificate server to manage all your certificates (both auto issued or manually managed, and self-signed) in one place. The OpenResty plugin and Golang TLS config library acts as client to the server.
By this design, there are several advantages:
A multi-layered cache mechanism is used to help frontend Nginx and Golang web servers automatically update to renewed certificates with negligible performance penalty, and without any reloading:
The cached certificates and OCSP staple is automatically renewed and refreshed in backend simplessl server.
Considered BETA.
Although this program has been running for nearly 5 years supporting my personal sites, however this is a spare-time project and has not known deployment for large production systems.
Anyone interested with this is HIGHLY RECOMMENDED to do testing in your environment.
The lua library is published with OPM, the following command will install the simplessl library, as well as it's dependency "lua-resty-http".
opm get jxskiss/simplessl
If you do not have opm, you can install the lua libraries manually, take OpenResty installed under "/usr/local/openresty" as example (you may need to use sudo to grant proper permission):
mkdir -p /usr/local/openresty/site/lualib/resty
cd /usr/local/openresty/site/lualib/resty
wget https://raw.githubusercontent.com/ledgetech/lua-resty-http/v0.16.1/lib/resty/http.lua
wget https://raw.githubusercontent.com/ledgetech/lua-resty-http/v0.16.1/lib/resty/http_connect.lua
wget https://raw.githubusercontent.com/ledgetech/lua-resty-http/v0.16.1/lib/resty/http_headers.lua
wget https://raw.githubusercontent.com/jxskiss/simplessl/master/lib/resty/simplessl.luago get github.com/jxskiss/simplessl/lib/tlsconfig@latest
See the following doc for example of using lib/tlsconfig.
Download the cert server service binary file, either build by yourself:
go install github.com/jxskiss/simplessl@latest
or download prebuilt binaries from the release page.
Copy example.conf.yaml to your favorite location and edit it to fit your need.
Configuration options are explained in the example file.
Run your cert server:
/path/to/simplessl run -c /path/to/your/conf.yamlOr to generate a self-signed certificate, see simplessl generate-self-signed -h.
Now you can configure your OpenResty or Golang program to use the cert server for SSL certificates, see the following examples.
events {
worker_connections 1024;
}
http {
include mime.types;
default_type application/octet-stream;
lua_shared_dict ssl_certs_cache 1m;
init_by_lua_block {
-- Define a function to determine which SNI domains to automatically
-- handle and register new certificates for. Defaults to not allowing
-- any domain, so this must be configured.
function allow_domain(domain)
if domain:find("example.com$") then
return true
end
return false
end
-- Initialize backend certificate server instance.
-- Change lru_maxitems according to your deployment, default 100.
simplessl = (require "resty.simplessl").new({
backend = '127.0.0.1:8999',
allow_domain = allow_domain,
lru_maxitems = 100,
})
}
# HTTPS Server
server {
listen 443 ssl;
# Works also with non-default HTTPS port.
listen 8443 ssl;
server_name hello.example.com;
# Dynamic handler for issuing or returning certs for SNI domains.
ssl_certificate_by_lua_block {
simplessl:ssl_certificate()
}
# Fallback certificate required by nginx, self-signed is ok.
# simplessl generate-self-signed \
# -days 3650 \
# -cert-out /etc/nginx/certs/fallback-self-signed.crt \
# -key-out /etc/nginx/certs/fallback-self-signed.key
ssl_certificate /etc/nginx/certs/fallback-self-signed.crt;
ssl_certificate_key /etc/nginx/certs/fallback-self-signed.key;
location / {
content_by_lua_block {
ngx.say("It works!")
}
}
}
# HTTP Server
server {
listen 80;
server_name hello.example.com;
# Endpoint used for performing domain verification with Let's Encrypt.
location /.well-known/acme-challenge/ {
content_by_lua_block {
simplessl:challenge_server()
}
}
}
}lib/tlsconfigYou may use the package lib/tlsconfig to run Golang program with TLS. eg:
func main() {
handler := func(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("It works!"))
}
// See doc of tlsconfig.Options for available options.
tlsConfig := tlsconfig.NewConfig("127.0.0.1:8999", tlsconfig.Options{})
listener, err := tls.Listen("tcp", ":8443", tlsConfig)
if err != nil {
log.Fatal(err)
}
http.Serve(listener, http.HandlerFunc(handler))
}acme/autocert and lego) to talk with ACME serverslib/tlsconfig be standalone moduleUpdate: this release has known bugs, please upgrade to newer release.
This release is a major change with quite a lot of new features and improvements.
gocraft/web, jxskiss/glog),
resulting smaller binary size and easier installationacme/autocert package instead of forking,
makes code clearer and allows easier tracking of upstream changesInitial public release.