luasec/doc/luasec.md
Bart van Strien cde151739e Add ssl.checkhostname and conn:checkhostname
Convenient (and important!) methods that allow checking for hostnames
against a (peer) certificate. Deals with wildcards and alternative names
(via the dnsnames extension).
2015-06-05 15:54:50 +02:00

1.7 KiB

LuaSec

LuaSec is a binding for OpenSSL library to provide TLS/SSL communication. It takes an already established TCP connection and creates a secure session between the peers.

Functions

ssl.newcontext

cfg = {
  protocol = "sslv23" | "sslv3" | "tlsv1" | "tlsv1_1" | "tlsv1_2",
  mode = "server" | "client",
  key = nil | filename,
  password = nil | string | function() -> string,
  certificate = nil | filename,
  cafile = nil | filename,
  capath = nil | path,
  ciphers = ciphers,
  verify = {"none" | "peer" | "client_once" | "fail_if_no_peer_cert", ...},
  options = options,
  depth = number,
  dhparam = function(is_export, keylength) -> dh_params_string,
  curve = curve,
  verifyext = {"lsec_continue" | "lsec_ignore_purpose" | "crl_check" |
      "crl_check_chain", ...},
}

context = ssl.newcontext(cfg)

Creates a new context based on the settings in the cfg table. See OpenSSL documentation on specifics on these settings, and see the openssl ciphers command for the list of supported ciphers and its format specifically.

For a list of options, see context.setoptions.

For a list of curves, see context.setcurve.

ssl.loadcertificate

Alias for cert.load.

ssl.wrap

conn = ssl.wrap(socket, cfg)

ssl.wrap wraps an existing luasocket socket into a luasec connection object. cfg is defined as for ssl.newcontext.

ssl.checkhostname

valid = ssl.checkhostname(cert, hostname)

Check if the certificate is valid for the given hostname. Deals with wildcards and alternative names.

NOTE: It is crucial the hostname is checked to verify the certificate is not only valid, but belonging to the host connected to.