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

60 lines
1.7 KiB
Markdown

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.