Home - Download - Reference

Reference

ssl.newcontext(params)

This function creates and returns a new context to wrap a connection. In case of errors, it returns nil followed by an error message. OpenSSL uses context as a framework for some of its TLS/SSL functions.

params must be a table with the connection parameters:

The field verify supports the following options:

• none
• peer
• client_once
• fail_if_no_peer_cert

The field options supports:

ssl.wrap(sock, ctx)

Wraps a TPC connection sock using the context ctx, and returns a new connection object. If an error occurs, it returns nil and an error message.

If ctx is a table, newcontext is used to create a new context. You can save memory sharing a context with the connections — this is more suitable in the server side.

For safetiness, the socket object passed as argument is invalidated, i.e., you cannot use it anymore. This prevents the garbage collector to close the connection when the socket object is disposed.

conn:close()

Closes the connection.

conn:dohandshake()

Initiates the TLS/SSL handshake. It returns true if the action was successfully performed, or false followed by an error message.

If timeout is set, dohandshake can also return "wantread" or "wantwrite" as possible error message. wantread means that the operation was not finished because it needs to read more information from the connection. In the same way, wantwrite indicates that data must be sent throught the connection. In this case, you can use socket.select to wait the connection be ready for reading or writing and call dohandshake again. For example:

  local succ, msg
  conn:settimeout(0.5)
  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 error
    end
  end

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

Reads data from a connection, according to 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 thedefault pattern;

• number: causes the method to read a specified number of bytes from the socket.

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 which can be the string "closed", in case the connection was closed before the transmission was completed; the strings "wantread" or "wantwrite" in case there was a timeout during the operation. Also, after the error message, the function returns the partial result of the transmission.

When wantread or wantwrite errors occur, you should wait the connection to be ready for reading or writing, respectively, and call receive again.

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

Sends data through client object.

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. The error message can be "closed", in case the connection was closed before the transmission was completed; or the strings "wantread" and "wantwrite", in case there was a timeout during the operation.

When wantread or wantwrite errors occur, you should wait the connection to be ready for reading or writing, respectively, and call send again.

conn:settimeout(value [, mode])

Changes the timeout values for the object. By default, the operations send, receive, and 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 send, receive, or dohandshake. The string "read" means the operation was not performed because the connection was not ready for reading. In the same way, "write" means the connection was not ready for writing. If the string "nothing" is returned, no timeout error was occurred.

Extensions

This is an experimental feature. You can use these functions to access OpenSSL structures created by LuaSec and create new modules to make addictional configurations or extract information. Take care!

ssl.rawcontext(ctx)

Returns a lightuserdata that is a pointer to SSL_CTX structure. ctx is a context created by ssl.newcontext.

ssl.rawconnection(conn)

Returns a lightuserdata that is a pointer to SSL structure. conn is a connection created by ssl.wrap.

Last update: 16-Jan-2009 10:29

SSL Lua SSL Lua OpenSSL Lua OpenSSL