LuaSSL
Securing Lua Connections

home · download · quickstart · references · index

Class Functions

ssl.wrap(key, certificate [, certdir, dhfile, cipherlist, verify_options, options])

This is the most important function for the SSL context to be created with the user preferences. Several default values are already configured so that it's not really needed to know much about each of these options to get your connection secure and running. Although it is highly recommended that you know what your doing.

This function returns a ssl object s, which is the object you'll use for all your ssl operations described in the next section

SSL Object Methods

s:accept( )

Waits for an SSL client to attempt connection. It is responsible for the first negotiations with the SSL client. They negotiate which authentication method to use, which cipher and exchange public keys/certificates to proove the authencity of both sides. If Ephemeral keying with Diffie Hellman algorithm is enabled with SSL_OP_SINGLE_DH_USE, all this negotiation is done using ephemeral keying.

s:bind(port)

binds the s to the specified port on the local host. Pay attention to the fact that only SSL servers can be bound to a socket, so do not use this function for connecting.

s:clear( )

Safely closes a broken connection. Broken means that the peer has disconnected without negotiating a shutdown.

s:connect(address, port [, exp_conn] )

Make an attempt to connect to (address, port). Address can be an IP address or a host name. It also performs all the negotiations needed by the SSL connection, and authenticates both the client and the server, exchanging keys and certificates. If Ephemeral keying with Diffie Hellman algorithm is enabled with SSL_OP_SINGLE_DH_USE, all this negotiation is done using ephemeral keying.

The optional parameter exp_conn stands for a post connection verification routine in which you will check the certificate sent by the peer, first of all, if it was really sent (i.e. this only makes sense if you are NOT using SSL_FAIL_IF_NO_PEER_CERTIFICATE). It also checks if the name recorded in the certificate is the same as exp_conn, which means "the peer you were expecting".

s:read( )

The function returns the decoded buffer read from the connection socket. In case of error it returns nil and the error code, which can be 0 for a "connection terminated" or < 0 for any problem that might have occurred.

s:renegotiate( )

SSL renegotiation is essentially an SSL handshake during a connection. This causes client credentials to be reevaluated and a new session to be created. It doesnt check *yet* if the handshake has been succesfully done since it depends on timeout.

s:shutdown( )

Shuts the SSL connection stablished by s down. The shutdown handshake and negotiations are performed by both server and the client, and the local address to which s was bound is made available to other applications. No further operations (except for further calls to close) are allowed on a closed object.

Note: It is important to shutdown all used objects once they are not needed, since, in many systems, each socket uses a file descriptor, which are a limited system resource.

s:write(string)

Writes the string encripted through the socket. The function returns an error code, which is nil in case of success, Or anything less than 0 if any error have occurred.


Attributes

The attributes of LuaSSL are exactly the same of the constants exported by OpenSSL. If you are already familiar with OpenSSL, you can just adapt to Lua way of summing them up.

In OpenSSL one could make the choice of having the peer verified and to fail no certificate were issued by the other part with the following sentence:

    SSL_VERIFY_PEER | SSL_FAIL_IF_NO_PEER_CERT

As in lua these constants became numbers, this summing becomes intuitively:

    ssl.VERIFY_PEER + ssl.FAIL_IF_NO_PEER_CERT

There are two groups of constants which may be added together, they are listed below:

Cipher Listing

The list of ciphers to be used by the application may be optionally determined in Lua. Since the default cipher list is both careful and complete, you may never need to specify a cipher list yourself, but if your are working with some specificity, you'll have to tell the SSL context which ciphers to use.

For instance "ALL" is a shortcut for every available combination. Additionally, we can precede a keyword with the "!" operator to remove all ciphers associated with the keyword. Using this we will create a string to define our custom cipher list. There are other operators such as "+" or "-", but they are not essential for specifying a secure list. For applications that need a custom definition, the ciphers manpage of the OpenSSL is a good reference on string formation.

A brief description of the keywords follows here:


Ephemeral Keying

As usually in SSL connections we shall use the RSA algorithm as it has the capabilities of doing most signing and encrypting. SSL can use it to perform the key agreement necessary to create the shared key under which the data in the stream is encrypted. This technique, such as when the key exchange is conducted through a persistent key is called static keying. Building on this definition, ephemeral keying is defined as key exchange through a temporary key. At first, it may seem that temporary keys may not allow for proper authentication -- not true. Generaly, with ephemeral keying, the authentication is accomplished through signature verification with persistent keys, and the temporary keys are used only for key agreement. There are two main advantages of ephemeral keying over static keying from a security perspective.

Consider the case the certificates are based upon DSA keys. The DSA algorithm provides a mechanism for signing but not for encrypting. Thus, having only DSA keys on either side of an SSL connection leaves the protocol unable to perform key exchange. It follows that static keying is not even an option for DSA-based certificates; we must supplement them with ephemeral keys.

The second advantage is that they provide forward secrecy. At a high level , forward secrecy means that if the private key is obtained by a third party, that third party will not be able to decode previous sessions conducted with that key or even future sessions conducted by someone else with the compromised key.

These two points make the benefits of using ephemeral keying clear. In terms of SSL, using ephemeral keys essentially mandates that the keys embedded in the certificates shall be used only for signatures and not for encryption. There are two methods for key exchange in OpenSSL: temporary RSA keys or Diffie-Hellman (DH) key agreement. Of these two choices, DH is better because temporary RSA keys violate the SSL/TLS protocols. The RSA keying was originally implemented to make sure export restrictions on cryptography were not violated. Today this issue is not a primary concert; thus, ephemeral RSA keys tend not to be used. Additionally, generation of these temporary RSA keys is much slower than using DH, presuming the DH parameters are pre-generated.

home · download · quickstart · references · index