diff options
Diffstat (limited to 'meta/3rd/OpenResty/library/ngx/ssl')
| -rw-r--r-- | meta/3rd/OpenResty/library/ngx/ssl/clienthello.lua | 102 | ||||
| -rw-r--r-- | meta/3rd/OpenResty/library/ngx/ssl/session.lua | 52 |
2 files changed, 154 insertions, 0 deletions
diff --git a/meta/3rd/OpenResty/library/ngx/ssl/clienthello.lua b/meta/3rd/OpenResty/library/ngx/ssl/clienthello.lua new file mode 100644 index 00000000..d2e40665 --- /dev/null +++ b/meta/3rd/OpenResty/library/ngx/ssl/clienthello.lua @@ -0,0 +1,102 @@ +---@meta +local clienthello = {} + +clienthello.version = require("resty.core.base").version + +---Returns the TLS SNI (Server Name Indication) name set by the client. +--- +---Return `nil` when then the extension does not exist. +--- +---In case of errors, it returns `nil` and a string describing the error. +--- +---Note that the SNI name is gotten from the raw extensions of the client hello message associated with the current downstream SSL connection. +--- +---So this function can only be called in the context of `ssl_client_hello_by_lua*`. +---@return string? host +---@return string? error +function clienthello.get_client_hello_server_name() end + + +--- Returns raw data of arbitrary SSL client hello extension including custom extensions. +--- +--- Returns `nil` if the specified extension type does not exist. +--- +--- In case of errors, it returns `nil` and a string describing the error. +--- +--- Note that the ext is gotten from the raw extensions of the client hello message associated with the current downstream SSL connection. +--- +--- So this function can only be called in the context of `ssl_client_hello_by_lua*`. +--- +--- Example: +--- +--- Gets server name from raw extension data. The `0` in `ssl_clt.get_client_hello_ext(0)` denotes `TLSEXT_TYPE_server_name`, and the `0` in `byte(ext, 3) ~= 0` denotes `TLSEXT_NAMETYPE_host_name`. +--- +--- ```nginx +--- # nginx.conf +--- server { +--- listen 443 ssl; +--- server_name test.com; +--- ssl_client_hello_by_lua_block { +--- local ssl_clt = require "ngx.ssl.clienthello" +--- local byte = string.byte +--- local ext = ssl_clt.get_client_hello_ext(0) +--- if not ext then +--- print("failed to get_client_hello_ext(0)") +--- ngx.exit(ngx.ERROR) +--- end +--- local total_len = string.len(ext) +--- if total_len <= 2 then +--- print("bad SSL Client Hello Extension") +--- ngx.exit(ngx.ERROR) +--- end +--- local len = byte(ext, 1) * 256 + byte(ext, 2) +--- if len + 2 ~= total_len then +--- print("bad SSL Client Hello Extension") +--- ngx.exit(ngx.ERROR) +--- end +--- if byte(ext, 3) ~= 0 then +--- print("bad SSL Client Hello Extension") +--- ngx.exit(ngx.ERROR) +--- end +--- if total_len <= 5 then +--- print("bad SSL Client Hello Extension") +--- ngx.exit(ngx.ERROR) +--- end +--- len = byte(ext, 4) * 256 + byte(ext, 5) +--- if len + 5 > total_len then +--- print("bad SSL Client Hello Extension") +--- ngx.exit(ngx.ERROR) +--- end +--- local name = string.sub(ext, 6, 6 + len -1) +--- +--- print("read SNI name from Lua: ", name) +--- } +--- ssl_certificate test.crt; +--- ssl_certificate_key test.key; +--- } +--- ``` +--- +---@param ext_type number +---@return string? ext +function clienthello.get_client_hello_ext(ext_type) end + + +--- Sets the SSL protocols supported by the current downstream SSL connection. +--- +--- Returns `true` on success, or a `nil` value and a string describing the error otherwise. +--- +--- Considering it is meaningless to set ssl protocols after the protocol is determined, +--- so this function may only be called in the context of `ssl_client_hello_by_lua*`. +--- +--- Example: +--- ```lua +--- ssl_clt.set_protocols({"TLSv1.1", "TLSv1.2", "TLSv1.3"})` +--- ``` +--- +---@param protocols string[] +---@return boolean ok +---@return string? error +function clienthello.set_protocols(protocols) end + + +return clienthello diff --git a/meta/3rd/OpenResty/library/ngx/ssl/session.lua b/meta/3rd/OpenResty/library/ngx/ssl/session.lua new file mode 100644 index 00000000..7307b00c --- /dev/null +++ b/meta/3rd/OpenResty/library/ngx/ssl/session.lua @@ -0,0 +1,52 @@ +---@meta +local session={} + +session.version = require("resty.core.base").version + + +--- Sets the serialized SSL session provided as the argument to the current SSL connection. +--- If the SSL session is successfully set, the current SSL connection can resume the session +--- directly without going through the full SSL handshake process (which is very expensive in terms of CPU time). +--- +--- This API is usually used in the context of `ssl_session_fetch_by_lua*` +--- when a cache hit is found with the current SSL session ID. +--- +--- The serialized SSL session used as the argument should be originally returned by the +--- `get_serialized_session` function. +--- +---@param session string +---@return boolean ok +---@return string? error +function session.set_serialized_session(session) end + +--- Returns the serialized form of the SSL session data of the current SSL connection, in a Lua string. +--- +--- This session can be cached in `lua-resty-lrucache`, `lua_shared_dict`, +--- and/or external data storage services like `memcached` and `redis`. The SSL session ID returned +--- by the `get_session_id` function is usually used as the cache key. +--- +--- The returned SSL session data can later be loaded into other SSL connections using the same +--- session ID via the `set_serialized_session` function. +--- +--- In case of errors, it returns `nil` and a string describing the error. +--- +--- This API function is usually called in the context of `ssl_session_store_by_lua*` +--- where the SSL handshake has just completed. +--- +---@return string? session +---@return string? error +function session.get_serialized_session() end + +--- Fetches the SSL session ID associated with the current downstream SSL connection. +--- The ID is returned as a Lua string. +--- +--- In case of errors, it returns `nil` and a string describing the error. +--- +--- This API function is usually called in the contexts of +--- `ssl_session_store_by_lua*` and `ssl_session_fetch_by_lua*`. +--- +---@return string? id +---@return string? error +function session.get_session_id() end + +return session
\ No newline at end of file |