Swift and OpenSSL, part 4: Client details

In the previous post we looked at the big picture of how a SSL connection is created from a client to a SSL-Server.

In this post I want to take a look at some of the details involved.

The first detail is an answer to the question: What is a "ssl-session"?

SSL Session

I am sure that the people that work on openSSL can give a very good answer. But for us API users we can take comfort in the fact that we don't need to know.

That is, an SSL session represents a connection between a SSL-client and a SSL-server. But other than that, we don't need to know how it is represented.

The openSSL team has made this very clear: All sessions are referred to by an OpaquePointer.

We create a session by calling SSL_new and get back an OpaquePointer. All use of the internal structure that hides behind the pointer can be done though API calls.

Usually those API calls take multiple parameters of which the first is the OpaquePointer of the session we want to use.

For example the openSSL read. It is defined as:

int SSL_read(SSL *ssl, void *buf, int num);

Which appears in Swift as:

SSL_read(ssl: OpaquePointer!, buf: UnsafeMutableRawPointer!, num: Int32) -> Int32

The first parameter is the OpaquePointer to the session. The second parameter a pointer to the buffer in which the data should be written and the third parameter is the size of the buffer. Just like the POSIX read call it returns an integer that contains either the number of bytes read, or an error indicator.

The OpaquePointer approach is typical for openSSL 1.1.0. It is used everywhere to avoid exposing the internals of the data structures.

As far as I see, all OpaquePointer's are force unwrapped. This means that they can be nil. In fact, using nil is rather common in C and (to my knowledge) none of the openSSL operations will crash if we pass nil.

Again I glossed over something: how do we create a session?

Well, we use SSL_new ... right, but what parameters do we need?

That brings us to point 2,

SSL Context

To create a session (client side) we provide a context.

SSL *SSL_new(SSL_CTX *ctx);

Which appears in Swift as:

SSL_new(ctx: OpaquePointer!) -> OpaquePointer!

Again we see the usage of OpaquePointer to hide the internal details. Which is good, because now we now we don't need to know :-)

Still we do need to know what a context is used for.

A context is used to store data that a session needs to operate. All kinds of data, most noticeably the certificates! (or at least the path to the certificates).

So before we create the session, we need to set up the context in which that session will operate.

It is worth mentioning that the context used to create a session is copied by that session. Thus if we need to change things afterwards, we need to do that on the session, and not on the context.

This allows us to store a context and keep it handy whenever we need to create a new session.

I strongly suggest you lookup what data can be set in the context, or alternatively know that you can set all parameters necessary for a session in the original context - so you know where to look.

Oh, about those OpaquePointer's...

OpaquePointer's

They hide their structure, but those structures take up memory. And memory must be allocated and deallocated.

You'll see where this is going... yup, reference counters. OpenSSL has them.

When a new session (or context or ... whatever) is created the ref-count is set to 1. When we are done with it, we need to decrease the ref-count. This is done by "free" calls. Each internal openSSL structure has an associated "free" call to decrement the ref-count. Once the ref-count reaches zero, the memory is deallocated.

The SSL_new has a corresponding SSL_free, the SSL_CTX_new has a SSL_CTX_free etc.

When data is retrieved (copied) from another data structure, sometimes openSSL will allocate a new structure for us. And sometimes it won't. It is always a good idea to check the documentation. But there are a couple of calls where this has been made explicit in the name of the call.

These can be recognized by their xxx_get0_xxx and xxx_get1_xxx signature.

The 'get0' returns a structure that should NOT be freed. While the 'get1' returns a structure that MUST be freed.

Now the last of the details that I glossed over, but do want to mention

Certificate Verification

To verify if a client connection to a server is secure, it first should be checked that the server presented a certificate. If that did not happen, there can be no secure connection. OpenSSL does not implicitly check this, we need to do that ourselves.

And then of course the results of the verification must be checked. If that fails, that does not necessary mean that the connection should not be established.

As an example: If we browse to a website that uses self-signed certificated, the verification will fail, but we can still decide to accept that certificate.

In the same way, when a certificate verification fails, it is often a good idea to ask the user what he wants. Does he want to continue or not?

Next in the series: a quick look at the server side.

Happy coding...

Did this help?, then please help out a small independent.
If you decide that you want to make a small donation, you can do so by clicking this
link: a cup of coffee ($2) or use the popup on the right hand side for different amounts.
Payments will be processed by PayPal, receiver will be sales at balancingrock dot nl
Bitcoins will be gladly accepted at: 1GacSREBxPy1yskLMc9de2nofNv2SNdwqH

We don't get the world we wish for... we get the world we pay for.

Swift and OpenSSL, part 3: Connecting to a SSL Server

In this part I will talk about the high-level view of creating a secure connection to a server. I will use the methods and wrappers from SecureSockets as these are easier to read and follow. (SecureSockets can be downloaded from github)

If you are new to socket programming it is probably best to first read up on socket programming. I always refer to beej's guide on network programming as a very fine resource for this.

It turns out that the way we need to use OpenSSL is very similar to normal socket programming.

For the POSIX "connect" call, there is a parallel "SSL_connect".

For the POSIX "accept" call there is a parallel "SSL_accept". For "read" there is "SSL_read" and for "write" there is "SSL_write".

The main difference is that instead of working on sockets, the openSSL calls work on "sessions".

The way this is implemented is that we first have to set up the socket and then we call the session operations.

An example, suppose we want to connect to a server:

First we set up the socket:

    var socket: Int32

    switch connectToTipServer(atAddress: address, atPort: port) {

    case let .error(message): return .error(message: message)

    case let .success(s): socket = s

    }

I'll hope you pardon me the usage of my own SwifterSockets framework (which can be downloaded for free from github)

The connectToTipServer returns a socket on success. From this moment on, the socket is connected to the server but no data has been transferred. The server has accepted the connection and is now waiting for the client to start transmitting something. In this case -of course- the server wants to start a SSL-handshake. But it waits for the client to initiate this.

At the client side we continue the sequence by creating a session:

    guard let ssl = Ssl(context: ctx) else {

        return .error(message: "Failed to create Ssl,\n\n\(errPrintErrors())")

    }

Then we assign the socket to the session:

    switch ssl.setFd(socket) {

    case let .error(message): return .error(message: "Failed to set socket to ssl,\n\(message)")

    case .success: break

    }

And then we tell the client to connect securely to the server:

    switch ssl.connect(socket: socket, timeout: timeoutTime) {

    case .timeout: return .timeout

    case let .error(message): return .error(message: "Failed to connect via SSL,\n\(message)")

    case .closed: return .error(message: "Connection unexpectedly closed")

    case .ready: break

    }

Before we start transferring data back and forth, we need to check if the connection was established securely.

This is a two step approach: first we need to know if the server did send a certificate, and secondly we need to know if the certificate is valid.

    guard let x509 = ssl.getPeerCertificate() else {

        return .error(message: "Verification failed, no certificate received")

    }

        

    switch ssl.getVerifyResult() {

    case let .error(message): return .error(message: "Verification failed,\n\(message)")  

    case .success: break

    }

Once this sequence completes, the "ssl" session is ready to transfer data back and forth.

Conceptually that is all there is to a secure client / server connection. But I did gloss over some details as you noticed.

Still the big picture on the client side is complete.

Just in case you want to know how the data transfers look like:

Writing: let res = SSL_write(optr, buf, num)

Reading: let res = SSL_read(optr, buf, num)

These are almost "drop in" replacements to the POSIX read and write. Except that they operate on the session instead of the socket.

Once the session can be closed, use SSL_shutdown(optr). It is possible to simply terminate the connection, but let's play nice ;-)

The next post will address some of the details that I glossed over today.

2017-02-07: One more thing...

Managing and maintaining a SSL connection means that the SSL layer will start read & write actions on its own. When using the POSIX select call to wait for events to happen on a connect, write, read etc, be sure to monitor for all events. For example monitoring only read events for a SSL_read will most likely fail at some point because the SSL layer wants to write.

Happy coding...

Did this help?, then please help out a small independent.
If you decide that you want to make a small donation, you can do so by clicking this
link: a cup of coffee ($2) or use the popup on the right hand side for different amounts.
Payments will be processed by PayPal, receiver will be sales at balancingrock dot nl
Bitcoins will be gladly accepted at: 1GacSREBxPy1yskLMc9de2nofNv2SNdwqH

We don't get the world we wish for... we get the world we pay for.