Module ssl

ssl modules to create SSL/TLS server or client, send and recv data over SSL channels.

Usage:

    ssl = require('openssl').ssl

Functions

ctx_new (protocol[, support_ciphers]) create ssl_ctx object, which mapping to SSL_CTX in openssl.
alert_type (alert[, long=false]) get alert_type for ssl state
alert_desc (alert[, long=false]) get alert_desc for ssl state

Class ssl_ctx

ssl_ctx:use (pkey, cert) tell ssl_ctx use private key and certificate, and check private key
ssl_ctx:add (clientca[, extra_chain_cert_array]) add client ca cert and option extra chain cert
ssl_ctx:timeout () get timeout
ssl_ctx:timeout (timeout) set timeout
ssl_ctx:mode (clear, mode[, ...]) clean given mode mode support ‘enable_partial_write’,‘accept_moving_write_buffer’,‘auto_retry’,‘no_auto_chain’,‘release_buffers’
ssl_ctx:options () get options
ssl_ctx:options (option) set options
ssl_ctx:options (clear, option) clear options
ssl_ctx:version () get min_proto_version and max_proto_version
ssl_ctx:options (min, max) set min_proto_version and max_proto_version
ssl_ctx:quiet_shutdown () get quit_shutdown is set or not Normally when a SSL connection is finished, the parties must send out “close notify” alert messages using SSL:shutdown" for a clean shutdown.
ssl_ctx:quiet_shutdown (quiet) set quiet_shutdown
ssl_ctx:verify_locations (cafile, capath) set verify locations with cafile and capath ssl_ctx:verify_locations specifies the locations for ctx, at which CA certificates for verification purposes are located.
ssl_ctx:cert_store () get certificate verification store of ssl_ctx
ssl_ctx:cert_store (store) set or replaces then certificate verification store of ssl_ctx
ssl_ctx:ssl (fd[, server=false]) create ssl object
ssl_ctx:ssl (input[, ouput=input[, server=false]]) create ssl object
ssl_ctx:bio (host_addr[, server=false[, autoretry=true]]) create bio object
ssl_ctx:verify_depth () get verify depth when cert chain veirition
ssl_ctx:verify_depth (depth) set verify depth when cert chain veirition
ssl_ctx:verify_mode () get verify_mode, return number mode and all string modes list
ssl_ctx:verify_mode (mode[, ssl=nil]) set ssl verify mode and callback
ssl_ctx:set_cert_verify ([cert_verify_cb]) set certificate verify callback function
ssl_ctx:set_cert_verify (verify_cb_flag) set certificate verify options
ssl_ctx:set_alpn_protos (protos) set the list of client ALPN protocols available to be negotiated by the server
ssl_ctx:set_alpn_select_cb ([alpn_select_cb]) set ALPN server protocol selection callback to select which protocol to use for the incoming connection
ssl_ctx:set_tmp (keytype, tmp_cb[, vararg]) set temp callback
ssl_ctx:set_tmp (keytype[, private]) set tmp key content pem format
ssl_ctx:set_servername_callback (info) set servername callback
ssl_ctx:set_session_callback (new, get, remove) set session callback
ssl_ctx:flush () flush sessions
ssl_ctx:sessions () set ssl session
ssl_ctx:session_cache_mode () get current session cache mode
ssl_ctx:session_cache_mode (mode) set session cache mode,and return old mode
ssl_ctx:getpeerverification () get peer certificate verify result

Class ssl

ssl:clear () reset ssl object to allow another connection
ssl:use (pkey[, cert]) tell ssl use private key and certificate, and check private key
ssl:peer () get peer certificate and certificate chains
ssl:want () get want to do
ssl:current_compression () get current compression name
ssl:current_cipher () get current cipher info
ssl:pending () get number of bytes available inside SSL fro immediate read
ssl:getfd () get socket fd of ssl
ssl:is_server () check SSL is a server
ssl:get (arg) get value according to arg
ssl:set (arg, value) set value according to arg
ssl:accept () do ssl server accept
ssl:connect () do ssl client connect
ssl:read ([length=4096]) do ssl read
ssl:peek ([length=4096]) do ssl peak, data can be read again
ssl:write (data) do ssl write
ssl:handshake () do ssl handshake, support both server and client side
ssl:renegotiate () do ssl renegotiate
ssl:renegotiate_pending () get ssl renegotiate_pending
ssl:renegotiate_pending () do ssl renegotiate_pending
ssl:shutdown (mode) shutdown ssl connection with quite or noquite mode
ssl:shutdown () shutdown SSL connection
ssl:shutdown (mode) shutdown ssl connect with special mode, disable read or write, enable or disable quite shutdown
ssl:set_connect_state () make ssl to client mode
ssl:set_accept_state () make ssl to server mode
ssl:dup () duplicate ssl object
ssl:session_reused () get ssl session resused
ssl:ctx () get ssl_ctx associate with current ssl
ssl:ctx (ctx) set ssl_ctx associate to current ssl
ssl:session () get ssl session
ssl:session (sesion) set ssl session
ssl:get_alpn_selected () get the ALPN protocol selected


Functions

ctx_new (protocol[, support_ciphers])
create ssl_ctx object, which mapping to SSL_CTX in openssl.

Parameters:

  • protocol string support ‘SSLv3’, ‘SSLv23’, ‘SSLv2’, ‘TSLv1’, ‘TSLv1_1’,‘TSLv1_2’,‘TLS’, ‘DTLSv1’,‘DTLSv1_2’, and can be follow by ‘server’ or ‘client’, in general you should use ‘TLS’ to negotiate highest available SSL/TLS version
  • support_ciphers string , if not given, default of openssl will be used (optional)

Returns:

    ssl_ctx
alert_type (alert[, long=false])
get alert_type for ssl state

Parameters:

  • alert number
  • long boolean (default false)

Returns:

    string alert type
alert_desc (alert[, long=false])
get alert_desc for ssl state

Parameters:

  • alert number
  • long boolean (default false)

Returns:

  1. string alert type
  2. string desc string, if long set true will return long info

Class ssl_ctx

openssl.ssl_ctx object
ssl_ctx:use (pkey, cert)
tell ssl_ctx use private key and certificate, and check private key

Parameters:

  • pkey evp_pkey
  • cert x509

Returns:

    boolean result return true for ok, or nil followed by errmsg and errval
ssl_ctx:add (clientca[, extra_chain_cert_array])
add client ca cert and option extra chain cert

Parameters:

  • clientca x509
  • extra_chain_cert_array table (optional)

Returns:

    boolean result
ssl_ctx:timeout ()
get timeout

Returns:

    number
ssl_ctx:timeout (timeout)
set timeout

Parameters:

  • timeout number

Returns:

    number previous timeout
ssl_ctx:mode (clear, mode[, ...])
clean given mode mode support ‘enable_partial_write’,‘accept_moving_write_buffer’,‘auto_retry’,‘no_auto_chain’,‘release_buffers’

Parameters:

  • clear boolean must be true
  • mode string
  • ... (optional)

Returns:

  1. string
  2. ...

Usage:

    modes = { ssl_ctx:mode('enable_partial_write','accept_moving_write_buffer','auto_retry') },

 for  i, v in ipairs(modes)
   print(v)
end
--output 'enable_partial_write','accept_moving_write_buffer','auto_retry'
ssl_ctx:options ()
get options

Returns:

    table string list of current options
ssl_ctx:options (option)
set options

Parameters:

  • option string , support “microsoft_sess_id_bug”, “netscape_challenge_bug”, “netscape_reuse_cipher_change_bug”, “sslref2_reuse_cert_type_bug”, “microsoft_big_sslv3_buffer”, “msie_sslv3_rsa_padding”,“ssleay_080_client_dh_bug”, “tls_d5_bug”,“tls_block_padding_bug”,“dont_insert_empty_fragments”,“all”, please to see ssl_options.h

Returns:

    table string list of current options after set new option
ssl_ctx:options (clear, option)
clear options

Parameters:

  • clear boolean set true to clear options
  • option string , support “microsoft_sess_id_bug”, “netscape_challenge_bug”, “netscape_reuse_cipher_change_bug”, “sslref2_reuse_cert_type_bug”, “microsoft_big_sslv3_buffer”, “msie_sslv3_rsa_padding”,“ssleay_080_client_dh_bug”, “tls_d5_bug”,“tls_block_padding_bug”,“dont_insert_empty_fragments”,“all”, please to see ssl_options.h

Returns:

    table string list of current options after clear some option
ssl_ctx:version ()
get min_proto_version and max_proto_version

Returns:

    integer min_proto_version

Or

    integer man_proto_version
ssl_ctx:options (min, max)
set min_proto_version and max_proto_version

Parameters:

  • min integer
  • max integer

Returns:

    boolean result or fail
ssl_ctx:quiet_shutdown ()
get quit_shutdown is set or not Normally when a SSL connection is finished, the parties must send out “close notify” alert messages using SSL:shutdown" for a clean shutdown.

Returns:

    boolean result
ssl_ctx:quiet_shutdown (quiet)
set quiet_shutdown

Parameters:

  • quiet boolean When setting the “quiet shutdown” flag to 1, SSL:shutdown will set the internal flags to SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN. SSL:shutdown then behaves like SSL:set_shutdown* called with SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN. The session is thus considered to be shutdown, but no “close notify” alert is sent to the peer. This behaviour violates the TLS standard. The default is normal shutdown behaviour as described by the TLS standard.

Returns:

    boolean result
ssl_ctx:verify_locations (cafile, capath)
set verify locations with cafile and capath ssl_ctx:verify_locations specifies the locations for ctx, at which CA certificates for verification purposes are located. The certificates available via CAfile and CApath are trusted.

Parameters:

Returns:

    boolean result
ssl_ctx:cert_store ()
get certificate verification store of ssl_ctx

Returns:

    x509_store store
ssl_ctx:cert_store (store)
set or replaces then certificate verification store of ssl_ctx

Parameters:

  • store x509_store

Returns:

    x509_store store
ssl_ctx:ssl (fd[, server=false])
create ssl object

Parameters:

  • fd number
  • server boolean , true will make ssl server (default false)

Returns:

    ssl
ssl_ctx:ssl (input[, ouput=input[, server=false]])
create ssl object

Parameters:

  • input bio
  • ouput bio , default will use input as output (default input)
  • server boolean , true will make ssl server (default false)

Returns:

    ssl
ssl_ctx:bio (host_addr[, server=false[, autoretry=true]])
create bio object

Parameters:

  • host_addr string format like ‘host:port’
  • server boolean , true listen at host_addr,false connect to host_addr (default false)
  • autoretry boolean ssl operation autoretry mode (default true)

Returns:

    bio bio object
ssl_ctx:verify_depth ()
get verify depth when cert chain veirition

Returns:

    number depth
ssl_ctx:verify_depth (depth)
set verify depth when cert chain veirition

Parameters:

  • depth number

Returns:

    number depth
ssl_ctx:verify_mode ()
get verify_mode, return number mode and all string modes list

Returns:

  1. number mode_code
  2. … none: not verify client cert peer: verify client cert fail: if client not have cert, will failure once: verify client only once.

Usage:

    mode = {ctx:verify_mode()}
print('integer mode',mode[1])
for i=2, #mode then
  print('string mode:'..mode[i])
end
ssl_ctx:verify_mode (mode[, ssl=nil])
set ssl verify mode and callback

Parameters:

  • mode number , mode set to ctx, must be ssl.none or ssl.peer, and ssl.peer support combine with ssl.fail or ssl.once
  • ssl function verify callback in lua function, not give will use default openssl callback, when mode is ‘none’, will be ignore this verify_cb must be boolean function(verifyarg) prototype, return true to continue or false to end ssl handshake verifyarg has field ‘error’, ‘error_string’,‘error_depth’,‘current_cert’, and ‘preverify_ok’ (default nil)

Returns:

    boolean result
ssl_ctx:set_cert_verify ([cert_verify_cb])
set certificate verify callback function

Parameters:

  • cert_verify_cb function with boolean function(verifyargs) prototype, if nil or none will use openssl default callback verifyargs has field ‘error’, ‘error_string’,‘error_depth’,‘current_cert’ (optional)
ssl_ctx:set_cert_verify (verify_cb_flag)
set certificate verify options

Parameters:

  • verify_cb_flag table support field always_continue with boolean value and verify_depth with number value.
ssl_ctx:set_alpn_protos (protos)
set the list of client ALPN protocols available to be negotiated by the server

Parameters:

  • protos table the protocol list
ssl_ctx:set_alpn_select_cb ([alpn_select_cb])
set ALPN server protocol selection callback to select which protocol to use for the incoming connection

Parameters:

  • alpn_select_cb function callback that receive the prototype list as a table and return the one selected as a string (optional)
ssl_ctx:set_tmp (keytype, tmp_cb[, vararg])
set temp callback

Parameters:

  • keytype string , ‘dh’,‘ecdh’,or ‘rsa’
  • tmp_cb function
  • vararg (optional)
ssl_ctx:set_tmp (keytype[, private])
set tmp key content pem format

Parameters:

  • keytype string , ‘dh’,‘ecdh’,or ‘rsa’
  • private string key file (optional)
ssl_ctx:set_servername_callback (info)
set servername callback

Parameters:

  • info table or function function(name) return ctx end or table

Returns:

    ssl_ctx or fail
ssl_ctx:set_session_callback (new, get, remove)
set session callback

Parameters:

  • new function
  • get function
  • remove function
ssl_ctx:flush ()
flush sessions
ssl_ctx:sessions ()
set ssl session
ssl_ctx:session_cache_mode ()
get current session cache mode

Returns:

    table modes as array, mode is ‘no_auto_clear’,‘server’,‘client’,‘both’,‘off’
ssl_ctx:session_cache_mode (mode)
set session cache mode,and return old mode

Parameters:

  • mode string support ‘no_auto_clear’,‘server’,‘client’,‘both’,‘off’, ‘no_auto_clear’ can be combine with others, so accept one or two param.
ssl_ctx:getpeerverification ()
get peer certificate verify result

Returns:

  1. boolean true for success
  2. table all certificate in chains verify result preverify_ok as boolean verify result error as number error code error_string as string error message error_depth as number verify depth current_cert as x509 certificate to verified

Class ssl

openssl.ssl object All SSL object IO operation methods(connect, accept, handshake, read, peek or write) return nil or false when fail or error. When nil returned, it followed by ‘ssl’ or ‘syscall’, means SSL layer or system layer error. When false returned, it followed by number 0, ‘want_read’,‘want_write’,‘want_x509_lookup’,‘want_connect’,‘want_accept’. Numnber 0 means SSL connection closed, others means you should do some SSL operation.
ssl:clear ()
reset ssl object to allow another connection

Returns:

    boolean result true for success
ssl:use (pkey[, cert])
tell ssl use private key and certificate, and check private key

Parameters:

  • pkey evp_pkey
  • cert x509 (optional)

Returns:

    boolean result return true for ok, or nil followed by errmsg and errval
ssl:peer ()
get peer certificate and certificate chains

Returns:

  1. x509 certificate
  2. sk_of_x509 chains of peer
ssl:want ()
get want to do

Returns:

  1. string ‘nothing’, ‘reading’, ‘writing’, ‘x509_lookup’
  2. number state want
ssl:current_compression ()
get current compression name

Returns:

    string
ssl:current_cipher ()
get current cipher info

Returns:

    table include name,version,id,bits,algbits and description
ssl:pending ()
get number of bytes available inside SSL fro immediate read

Returns:

    number
ssl:getfd ()
get socket fd of ssl

Returns:

    number fd
ssl:is_server ()
check SSL is a server

Returns:

    boolean is_server
ssl:get (arg)
get value according to arg

Parameters:

  • arg string
    certificate: return SSL certificates
    fd: return file or network connect fd
    rfd:
    wfd:
    client_CA_list
    read_ahead: –> boolean
    shared_ciphers: string
    cipher_list –> string
    verify_mode: number
    verify_depth
    state_string
    state_string_long
    rstate_string
    rstate_string_long
    iversion
    version
    default_timeout,
    certificate
    verify_result
    state
    hostname
    state_string
    side

Returns:

    according to arg
ssl:set (arg, value)
set value according to arg

Parameters:

  • arg string
    certificate: return SSL certificates
    fd: return file or network connect fd
    rfd:
    wfd:
    client_CA:
    read_ahead:
    cipher_list:
    verify_depth:
    purpose:
    trust:
    verify_result:
    hostname:
  • value val type accroding to arg

Returns:

    value
ssl:accept ()
do ssl server accept

Returns:

  1. boolean true for success
  2. string fail reason
ssl:connect ()
do ssl client connect

Returns:

  1. boolean true for success
  2. string fail reasion
ssl:read ([length=4096])
do ssl read

Parameters:

  • length number to read (default 4096)

Returns:

  1. string data, nil or false for fail
  2. string fail reason
ssl:peek ([length=4096])
do ssl peak, data can be read again

Parameters:

  • length number to read (default 4096)

Returns:

  1. string data, nil or false for fail
  2. string fail reason
ssl:write (data)
do ssl write

Parameters:

Returns:

  1. number count of bytes write successfully
  2. string fail reason
ssl:handshake ()
do ssl handshake, support both server and client side

Returns:

  1. boolean true for success
  2. string fail reasion
ssl:renegotiate ()
do ssl renegotiate

Returns:

  1. boolean true for success
  2. string fail reasion
ssl:renegotiate_pending ()
get ssl renegotiate_pending

Returns:

  1. boolean true for success
  2. string fail reasion
ssl:renegotiate_pending ()
do ssl renegotiate_pending

Returns:

  1. boolean true for success
  2. string fail reasion
ssl:shutdown (mode)
shutdown ssl connection with quite or noquite mode

Parameters:

  • mode boolean

Returns:

  1. boolean if mode is true, return true or false for quite
  2. string if mode is false, return ‘read’ or ‘write’ for shutdown direction
ssl:shutdown ()
shutdown SSL connection
ssl:shutdown (mode)
shutdown ssl connect with special mode, disable read or write, enable or disable quite shutdown

Parameters:

  • mode string support ‘read’,‘write’, ‘quite’, ‘noquite’
ssl:set_connect_state ()
make ssl to client mode
ssl:set_accept_state ()
make ssl to server mode
ssl:dup ()
duplicate ssl object

Returns:

    ssl
ssl:session_reused ()
get ssl session resused
ssl:ctx ()
get ssl_ctx associate with current ssl

Returns:

    ssl_ctx
ssl:ctx (ctx)
set ssl_ctx associate to current ssl

Parameters:

Returns:

    ssl_ctx orgine ssl_ctx object
ssl:session ()
get ssl session

Returns:

    ssl_session session object
ssl:session (sesion)
set ssl session

Parameters:

Returns:

    boolean result
ssl:get_alpn_selected ()
get the ALPN protocol selected

Returns:

    the ALPN protocol selected or nil
generated by LDoc 1.5.0 Last updated 2024-01-20 16:21:56