翻译自： ngx.ssl - Lua API for controlling NGINX downstream SSL handshakes

1. 概要

# 注意：如果你使用的是 OpenResty 1.9.7.2+，则不需要该行

lua_package_path "/path/to/lua-resty-core/lib/?.lua;;";

server {

    listen 443 ssl;

    server_name test.com;

    # useless placeholders: just to shut up NGINX configuration

    # loder errors:

    ssl_certificate /path/to/fallback.crt;

    ssl_certificate_key /path/to/fallback.key;

    ssl_certificate_by_lua_block {

        local ssl = require "ngx.ssl"

        -- clear the fallback certificates and private keys

        -- set by the ssl_certificate and ssl_certificate_key

        -- directives above:

        local ok, err = ssl.clear_certs()

        if not ok then

            ngx.log(ngx.ERR, "failed to clear existing (fallback) certificates")

            return ngx.exit(ngx.ERROR)

        end

        -- assuming the user already the my_load_certificate_chain()

        -- herself.

        local pem_cert_chain = assert(my_load_certifiate_chain())

        local der_cert_chain, err = ssl.cert_pem_to_der(pem_cert_chain)

        if not der_cert_chain then

            ngx.log(ngx.ERR, "failed to convert certificate chain ",

                    "from PEM to DER: ", err)

            return ngx.exit(ngx.ERROR)

        end

        local ok, err = ssl.set_der_cert(der_cert_chain)

        if not ok then

            ngx.log(ngx.ERR, "failed to set DER cert: ", err)

            return ngx.exit(ngx.ERROR)

        end

        -- assuming the user already defined the my_load_private_key()

        -- function herself.

        local pem_pkey = assert(my_load_private_key())

        local der_pkey, err = ssl.priv_key_pem_to_der(pem_pkey)

        if not der_pkey then

            ngx.log(ngx.ERR, "failed to convert private key ",

                    "from PEM to DER: ", err)

            return ngx.exit(ngx.ERROR)

        end

        local ok, err = ssl.ser_der_priv_key(der_pkey)

        if not ok then

            ngx.log(ngx.ERR, "failed to set DER private key: ", err)

            return ngx.exit(ngx.ERROR)

        end

    }

    location / {

        root html;

    }

}

2. 描述

该 Lua 模块提供 API 函数来控制类似 ssl_certificate_by_lua*（ngx_lua 模块）等上下文的 SSL 握手过程。

OpenSSL 允许我们动态地设置证书和私钥，因此期望可以在建立连接前才设置证书和私钥，这样，可以结合 SNI，针对不同的请求域名动态设置不同的证书和私钥，而无需事先把可能用到的证书和私钥都准备好。该 lua 模块提供的 API 以在 ssl_certificate_by_lua* 指令的上下文中支持此种情况。

在 Lua 中加载 ngx.ssl 模块，因如下：

local ssl = require "ngx.ssl"

3. 方法

3.1 clear_certs

语法：ok, err = ssl.clear_certs()

上下文：ssl_certificate_by_lua*

清除在当前 SSL 连接中设置的任何已经存在的 SSL 证书和私钥。
成功返回 true，失败返回一个 nil 值并且通过字符串描述错误。

3.2 cert_pem_to_der

语法：der_cert_chain, err = ssl.cert_pem_to_der(pem_cert_chain)

上下文：任意

将 PEM 格式的 SSL 证书链数据转换为 DER 格式（转换后的 der 格式数据将用于 set_der_cert 函数）。
失败，则返回 nil 值，并且通过字符串描述错误。
openssl 命令行工具可能无法正确将 SSL 证书链从 PEM 格式转换为 DER，因此总是使用该 Lua 函数进行转换。你可以总是使用类似 lua-resty-lrucache 或者 ngx_lua API（如 lua_shared_dict）等库来缓存 DER 格式的结果。
该函数可以在任何上下文中使用。

3.3 set_der_cert

语法：ok, err = ssl.set_der_cert(der_cert_chain)

上下文：ssl_certificate_by_lua*

为当前的 SSL 连接设置 DER 格式的 SSL 证书链数据。注意，该 DER 数据是直接保存在 Lua 字符串参数中的。不需要外部文件支持。
若成功返回 true，否则返回 nil 并且通过字符串描述错误。
注意，SSL 证书链通常以 PEM 格式编码，因此首先需要使用 cert_perm_to_der 函数进行转换。

3.4 priv_key_pem_to_der

语法：der_priv_key, err = ssl.priv_key_perm_to_der(perm_priv_key)

上下文：任意

将 PEM 格式的 SSL 私钥数据转换为 DER 格式（用于 set_der_priv_key 函数）。
失败，返回 nil 并通过字符串描述错误。
可选地，你可以使用 openssl 命令行工具脱机下执行 PEM 转换为 DER，如下：

openssl rsa -in key.pem -outform DER -out key.der

该函数可以在任意上下文中调用。

3.5 set_der_priv_key

语法：ok, err = ssl.set_der_priv_key(der_priv_key)

上下文：ssl_certificate_by_lua*

为当前 SSL 连接设置 DER 格式的私钥。
成功返回 true，失败返回 nil 并通过字符串描述错误。
通常，私钥是以 PEM 格式编码的。可以使用 priv_key_perm_to_der 函数或者使用 openssl 命令行工具脱机将 PEM 转换为 DER，如下：

openssl rsa -in key.pem -outform DER -out key.der

3.6 server_name

语法：name, err = ssl.server_name()

上下文：任意

返回由客户端设置的 TLS SNI（Server Name Indication）名。若客户端没有设置则返回 nil。
失败，返回 nil 并通过字符串描述错误。
通常我们使用 SNI 名作为域名（如 www.openresty.org）来标识当前的 web 站点，同时为当该网站加载相应的 SSL 证书链和私钥。
注意，并不是所有的 https 客户端都设置 SNI 名，因此当从客户端握手请求中缺失 SNI 名时，我们可以使用客户端访问的服务器 IP 地址来标识该网站。有关更多详细信息，参阅 raw_server_addr 方法。
可以在下游 https 的任何上下文中调用该函数。

3.7 raw_server_addr

语法：addr_data, addr_type, err = ssl.raw_server_addr()

上下文：任意

返回当前 SSL 连接中客户端实际访问的原始服务器地址。
前两个返回值分别表示地址数据和地址类型的字符串，根据地址类型值对地址值进行不同的解释：
- unix: 地址数据是 UNIX 域套接字的文件路径。
- inet：地址数据是 4 字节长的二进制 IPv4 地址。
- inet6：地址数据时 16 字节长的二进制 IPv6 地址。
失败返回 nil，并通过字符串描述错误。
以下代码显示如何将 UNIX 域套接字和 IPv4 地址打印为人类可读的字符串：

local ssl = require "ngx.ssl"

local byte = string.byte

local addr, addrtyp, err = ssl.raw_server_addr()

if not addr then

    ngx.log(ngx.ERR, "failed to fetch raw server addr: ", err)

    return

end

if addrtyp == "inet" then  -- IPv4

    ip = string.format("%d.%d.%d.%d", byte(addr, 1), byte(addr, 2),

                       byte(addr, 3), byte(addr, 4))

    print("Using IPv4 address: ", ip)

elseif addrtyp == "unix" then  -- UNIX

    print("Using unix socket file ", addr)

else  -- IPv6

    -- leave as an exercise for the readers

end

可以在下游 https 的任何上下文中调用该函数。

3.8 raw_client_addr

语法：addr_data, addr_type, err = ssl.raw_client_addr()

上下文：任意

巴特西

OpenResty之ngx.ssl