Ratchet Library :: SSL Encryption
API  ·  Manual

ratchet.ssl API Reference

ratchet.ssl.session API Reference

Encryption Context

So that certificates, keys, and other settings can be loaded once in a central location, encryption contexts must be created first and used to create the individual encryption sessions used on sockets and the like.

ssl = ratchet.ssl.new(ratchet.ssl.SSLv3)

-- Change verification mode from the default, "peer".

-- For servers, or whenever this side of the connection must be verified...
ssl:load_certs("/path/to/cert.pem", "/path/to/private/key.pem", "password")

-- For clients, or whenever the remote end will need to be verified by a
-- trusted Certificate Authority.
ssl:load_cas("/path/to/CAs/", "/path/to/CA/file.pem")

-- To generate an ephemeral RSA key.

-- To load DH Parameters.

-- To load randomness.

Encryption Session

For actual SSL sessions, you create a ratchet.ssl.session object for each socket (or other layer). These objects cannot be created directly, and actually ratchet.ssl.session is a theoretical name that resolves to nil. To start a new session, you use the create_session() method of an encryption context object. This method is called automatically by socket:encrypt(), so calling it directly is rare unless you aren't using sockets or have special needs.

Once you have an encryption session, you can use it for all transactions. If anything fails, an error is propagated. Using encrypted sockets attempts to hide the encryption session as much as possible, so that the same code can be used for encrypted and unencrypted versions of a protocol. However, direct access to the following encrypted actions are available as session methods:

  • write(): Send encrypted data.
  • read(): Read encrypted data.
  • accept(): Server-side encryption handshake, (alias to server_handshake()).
  • connect(): Client-side encryption handshake, (alias to client_handshake()).
  • verify_certificate(): Check the remote peer certificate.
  • shutdown(): Terminate encrypted session cleanly.

Encrypting Other Non-Socket Channels

Encryption sessions are not limited to sockets, just as OpenSSL is not. As long as a communication layer can implement the BIO abstraction, it can be encrypted by both OpenSSL and thus the ratchet library. To create a session, you must first have a Lua object that implements the necessary protocol to have ratchet wait on reads and writes. That object shall be known as the "engine". From this engine object, by whatever means necessary, you must create a BIO object (or objects, for separate read and write).

local engine = get_engine_compatible_with_ratchet()
local rbio, wbio = create_BIOs_from_engine(engine)

local enc = ssl:create_session(engine, rbio, wbio)

With this new session object, you should be able to perform all encryption methods, or tweak your engine to call them instead like the socket library does.

Last modified:  Sun, 17 Aug 2014 09:32:32 -0400
Author:  ian.good