LuaSec 0.4

Index

ssl.newcontext
ssl.wrap
conn:close
conn:dohandshake
conn:receive
conn:send
conn:settimeout
conn:want
https.request

ssl.newcontext(params)

Creates a context that is used to wrap a TCP connection. In case of errors, the function returns nil, followed by an error message.

params is a table that contains parameters to create the context. These parameters can be:

Key	Value Type	Value	Mandatory
mode	String	Use "client" or "server".	Yes
protocol	String	"tlsv1": for TLS version 1 "sslv3": for SSL version 3 "sslv23": for SSL version 2 and 3	Yes
key	String	Path to the file that contains the key (in PEM format).	No
password	String / Function	Password of the encrypted key, or a callback function that returns it. If the callback does not return a string, a null password is used.	No
certificate	String	Path to the file that contains the chain certificates. These must be in PEM format and must be sorted starting from the subject's certificate (client or server), followed by intermediate CA certificates if applicable, and ending at the highest level CA.	No
cafile	String	Path to the file that contains a set of trusting certificates (in PEM format).	No
capath	String	Path to the directory that constains a set of files with trusting certificates.	No
verify	String / Table	Options used to verify the certificates. Use an array of strings for multiple options.	No
options	String / Table	Options to change the behaviour of the OpenSSL library. Use an array of strings for multiple options.	No
ciphers	String	The list of ciphers to be used in the connection.	No
depth	Number	Maximum depth in the certificate chain verification.	No

Please, see OpenSSL documentation for more information.

The field verify supports:

none
peer
client_once
fail_if_no_peer_cert

The field options supports:

all
cipher_server_preference
cookie_exchange
dont_insert_empty_fragments
ephemeral_rsa
microsoft_big_sslv3_buffer
microsoft_sess_id_bug
msie_sslv2_rsa_padding
netscape_ca_dn_bug
netscape_challenge_bug
netscape_demo_cipher_change_bug
netscape_reuse_cipher_change_bug
no_query_mtu
no_session_resumption_on_renegotiation
no_sslv2
no_sslv3
no_ticket
no_tlsv1
pkcs1_check_1
pkcs1_check_2
single_dh_use
single_ecdh_use
ssleay_080_client_dh_bug
sslref2_reuse_cert_type_bug
tls_block_padding_bug
tls_d5_bug
tls_rollback_bug
allow_unsafe_legacy_renegotiation
legacy_server_connect
cisco_anyconnect
cryptopro_tlsext_bug
no_compression

Note: you need to check if your version of OpenSSL provides these options.

ssl.wrap(sock, params)

Wraps the TCP connection sock and returns a new object that is used to establish a secure session. In case of error, the function returns nil, followed by an error message.

ssl.wrap needs a context, which provides parameters such as protocol, certificate, key, etc., in order to create the new connection object. You can provide a already created context in params or a table with the parameters. In this case, ssl.wrap calls ssl.newcontext to obtain the context.

Note: ssl.wrap invalidates the socket passed as argument. This prevents the garbage collector to close the TCP connection when the socket object is disposed.

conn:close()

Closes the connection.

conn:dohandshake()

Performs theTLS/SSL handshake to establesh the secure connection. In case of success, the function returns true, otherwise, false followed by an error message.

If timeout is set, conn:dohandshake can return nil followed by "wantread" or "wantwrite" to indicate that the handshake was not finished yet. "wantread" indicates that the operation was not finished because a timeout in the underline TCP connection prevents it of sending data. In the same way, "wantwrite" indicates a timeout while receiving information from TCP connection. In these cases, you can use socket.select to wait the connection to be ready for reading or writing and call conn:dohandshake again to finish the operation.

For example:

local succ, msg
conn:settimeout(0)
while not succ do
  succ, msg = conn:dohandshake()
  if msg == "wantread" then
    socket.select({conn}, nil)
  elseif msg == "wantwrite" then
    socket.select(nil, {conn})
  else
    -- other errors
  end
end

conn:receive([[pattern][, prefix]])

Reads data from the connection conn, according to the specified read pattern:

'*a': reads from the connection until it is closed. No end-of-line translation is performed;
'*l': reads a line of text from the connection. The line is terminated by a LF character (ASCII 10), optionally preceded by a CR character (ASCII 13). The CR and LF characters are not included in the returned line. In fact, all CR characters are ignored by the pattern. This is the default pattern;
number: causes the method to read a specified number of bytes from the socket.

The parameter prefix is an optional string to be concatenated to the beginning of any received data before return.

If successful, the method returns the received pattern. In case of error, the method returns nil followed by an error message.

Among the error messages, "closed" indicates that the connection was closed before the transmission was completed; "wantread" and "wantwrite" indicates that a timeout occurred during the operation. Also, after the error message, the function returns the partial result of the transmission.

In the case of "wantread" or "wantwrite" errors, you should wait the connection to be ready for reading or writing, respectively, and call conn:receive again.

conn:send(data [, i [, j]])

Sends data through the connection.

data is the string to be sent. The optional arguments i and j work exactly like the standard string.sub Lua function to allow the selection of a substring to be sent.

If successful, the method returns the index of the last byte within [i, j] that has been sent. Notice that, if i is 1 or absent, this is effectively the total number of bytes sent. In case of error, the method returns nil, followed by an error message and the index of the last byte within [i, j] that has been sent. You might want to try again from the byte following that.

Among the error messages, "closed" indicates that the connection was closed before the transmission was completed; "wantread" and "wantwrite" indicates that a timeout occured during the operation.

In the case of "wantread" or "wantwrite" errors, you should wait the connection to be ready for reading or writing, respectively, and call conn:send again.

conn:settimeout(value [, mode])

Changes the timeout values for the connection. By default, the operations conn:send, conn:receive, and conn:dohandshake will block indefinitely, until the operation completes. When a timeout is set and the specified amount of time has elapsed, the affected methods give up and fail with an error code.

The amount of time to wait is specified as the value parameter, in seconds. There are two timeout modes and both can be used together for fine tuning:

'b': block timeout. Specifies the upper limit on the amount of time LuaSec can be blocked by the operating system while waiting for completion of any single I/O operation. This is the default mode;
't': total timeout. Specifies the upper limit on the amount of time LuaSec can block a Lua script before returning from a call.

The nil timeout value allows operations to block indefinitely. Negative timeout values have the same effect.

conn:want()

Informs the reason that triggers the timeout in the last call of conn:send, conn:receive, or conn:dohandshake. The string "read" indicates the operation was not performed because the connection was not ready for reading. In the same way, "write" indicates the connection was not ready for writing. If the operations were successfully complited, the string "nothing" is returned.

https.request(url [ , body])

This is a simple HTTPS client built on top of LuaSocket's HTTP module. This function creates a custom create function, that performs the secure connection with the server, and passes it to LuaSocket.

If url is a table, it should contain an union of LuaSocket's HTTP options and LuaSec configuration. However, the current implementation does not support proxy nor URL redirection, so the fields redirect and proxy are not supported in url. Also, setting http.PROXY is not permitted.

In the case url is a string, the module uses the following default configuration to establish the connection:

default = {
  protocol = "tlsv1",
  options = "all",
  verify = "none",
}

The parameter body is an optional string sent as request body.

In case of failure, https.requet returns nil followed by an error message. In case of success, if url is a string, the function returns the response's body, status code, headers, and status line. If url is a table, the function returns the same results, except the response's body is replaced by the value 1.