net.SslSocket#

The SslSocket object provides an SSL encrypted socket for both clients and servers.

SslSocket establishes a secure, encrypted TCP connection you can use for transmitting encrypted data. It supports modern SSL protocols, including SSL 3 and TLS 1.2.

SSL encryption operates on top of the existing TCP stream after the socket enters CONNECTED_STATE. There are two simple ways to establish a secure connection using SslSocket: with an immediate SSL handshake, or with a delayed SSL handshake occurring after the connection has been established in unencrypted mode.

The most common way to use SslSocket is to construct an object and start a secure connection by calling connect_encrypted(). This method starts an immediate SSL handshake once the connection has been established.

socket = iomodules.net.SslSocket.new()
socket.encrypted_handler = function()
    -- start talking now that encryption has begun
end
socket:connect_encrypted("chat.example.com", 993, net.Stream.READ_WRITE_MODE)

As with a plain TcpSocket, SslSocket enters the HOST_LOOKUP_STATE, CONNECTING_STATE, and finally the CONNECTED_STATE, if the connection is successful. The handshake then starts automatically, and if it succeeds, the encrypted_handler is called to indicate the socket has entered the encrypted state and is ready for use.

Note that data can be written to the socket immediately after the return from connect_encrypted() (i.e. before the encrypted_handler is called) — the data is queued in SslSocket until after the encrypted_handler is called.

Once encrypted, you use SslSocket as a regular TcpSocket. When the ready_read_handler is called, you can call the read functions (see Stream) to read decrypted data from the socket’s internal buffer, and you can call one of the write functions to write data back to the peer. SslSocket will automatically encrypt the written data for you.

Properties#

SslSocket.encrypted#

Read only. True if the socket is encrypted.

An encrypted socket encrypts all data that is written by calling one of the write functions before the data is written to the network, and decrypts all incoming data as the data is received from the network, before you call one of the read functions.

SslSocket calls the encrypted_handler when it enters encrypted mode.

SslSocket.mode#

Read only. The current SSL mode for the socket; either UNENCRYPTED_MODE, where the SslSocket behaves identically to a TcpSocket, or one of SSL_CLIENT_MODE or SSL_SERVER_MODE, where the client is either negotiating or in encrypted mode.

When the mode changes, the mode_changed_handler is called.

Mode	Value	Description
`UNENCRYPTED_MODE`	0	The socket is unencrypted. Its behaviour is identical to a TcpSocket.
`SSL_CLIENT_MODE`	1	The socket is a client-side SSL socket. It is either already encrypted, or it is in the SSL handshake phase.
`SSL_SERVER_MODE`	2	The socket is a server-side SSL socket. It is either already encrypted, or it is in the SSL handshake phase.

SslSocket.configuration#

The SSL configuration of this socket. SslSockets have a default configuration that will work for the majority of use cases. If more control is needed — for instance, the server requires the client to provide a certificate — this can be overriden. If overriden, the new configuration will be applied during the next SSL handshake.

See net.SslConfiguration for details about the SSLConfiguration API.

SslSocket.peer_verify_mode#

The current peer verification mode for the socket.

Mode	Value	Description
`VERIFY_NONE`	0	The socket will not request a certificate from the peer. You can set this mode if you are not interested in the identity of the other side of the connection. The connection will still be encrypted, and your socket will still send its local certificate to the peer if it’s requested.
`QUERY_PEER`	1	The socket will request a certificate from the peer, but does not require this certificate to be valid. This is useful when you want to display peer certificate details to the user without affecting the actual SSL handshake. This mode is the default for servers.
`VERIFY_PEER`	2	The socket will request a certificate from the peer during the SSL handshake phase, and requires that this certificate is valid. This mode is the default for clients.
`AUTO_VERIFY_PEER`	3	The socket will automatically use QUERY_PEER for server sockets and VERIFY_PEER for client sockets.

Methods#

SslSocket.new() -> SslSocket#

Create a new SslSocket.

SslSocket:connect_encrypted(hostname, port, openmode)#

Attempts to make an encrypted connection to hostname on the given port, using the given Stream.open_mode. This is the equivalent of calling connect() to establish the connection, followed by a call to start_client_encryption().

SslSocket:start_client_encryption()#

Starts a delayed SSL handshake for a client connection. This function can be called when the socket is in the CONNECTED_STATE but still in the UNENCRYPTED_MODE. If it is not yet connected, or if it is already encrypted, this function has no effect.

Clients that implement STARTTLS functionality often make use of delayed SSL handshakes. Most other clients can avoid calling this function directly by using connect_encrypted() instead, which automatically performs the handshake.

Event handlers#

SslSocket.encrypted_handler#

The handler has the following signature:

function(socket)

The handler is called when the socket enters encrypted mode. After this handler has been called, the encrypted property will be true and all further transmissions on the socket will be encrypted.

SslSocket.mode_changed_handler#

The handler has the following signature:

function(socket, mode)

The handler is called when the socket SSL mode changes. mode is the new mode.