libtls: rethinking the TLS/SSL API

Making it easier and safer to write applications that use TLS

Joel Sing <jsing@openbsd.org>

linux.conf.au 2017, Hobart, Australia

What is libtls?

• A new TLS library with a clean, obvious and simple API.
• Designed to make it easier to write foolproof applications.
• The fourth component of LibreSSL.

A bit of history...

April 2014 - LibreSSL

• Heartbleed...
• Ted Unangst (tedu@) started looking at exploit countermeasures and fell down a rabbit hole:
  • OpenSSL LIFO freelists (on by default, compile time option hence recompile to disable).
  • SSL_MODE_RELEASE_BUFFERS bug, hidden by LIFO freelists.
• OpenSSL was forked and LibreSSL began.

A bit of history...

July 2014 - libtls

"Hey, we should really create a better API."

• libtls (formerly ressl) was created, following a conversation with Ted.
• Currently uses libssl "under the hood".
• While the general goals for LibreSSL are to modernise the codebase, improve security, and apply best practice development processes, libtls aims to completely rethink the TLS API.

TLS is complex and messy!

• Handshake, record layer
• SSLv2, SSLv3, TLSv1.0, TLSv1.1, TLSv1.2... TLSv1.3
• SSLv2 records with SSLv3/TLS client hellos!
• TLS extensions - SNI, ALPN, etc
• Crypto - public key, symmetric, key exchange and loads of gotchas.
• PKI and X.509
• And mix in a good dose of ASN.1

It should be easy to use...

But I just want to write an application that has TLS support!

Why not just use existing APIs?

Let's write some code...

Presuming that we've already done the work to resolve DNS and establish a connected socket:

if ((ssl_ctx = SSL_CTX_new(SSLv23_method())) == NULL)
        errx(1, "failed to create ssl context");
if ((ssl = SSL_new(ssl_ctx)) == NULL)
        errx(1, "failed to create ssl");

if (SSL_set_fd(ssl, s) != 1)
        errx(1, "failed to set fd");

if (SSL_connect(ssl) != 1)
        errx(1, "failed to connect");

if (SSL_write(ssl, buf, len) != len)
        errx(1, "SSL_write failed");
if ((ret = SSL_read(ssl, buf, sizeof(buf))) <= 0)
        errx(1, "SSL_read failed");

if (SSL_shutdown(ssl) != 1)
        errx(1, "SSL_shutdown failed");
      

What just happened?

• What TLS version did I use?
• What ciphersuite was just negotiated?
• You may or may not have Perfect Forward Secrecy (PFS), depends on the ciphersuite.
• The certificate chain was verified (good)
• But if it failed, it just continued anyway (not so good)
• Oh, oops... I also forgot to verify the server name! (bad, MITM)

We should really fix that...

Certificate Verification

• Need to call SSL_set_verify(ssl, SSL_VERIFY_PEER, NULL)
  • The default is SSL_VERIFY_NONE (insecure by default)
• Also need to specify a file (or path) containing CA certificates.

We should really fix that...

Server Name Verification

• Now I need to know about X.509, Common Names (CNs) and Subject Alternative Names (SANs)
  (go read the RFCs... only around 220 pages)
• Handle nastiness such as NUL bytes in names.
• Figure out how to do wildcard matching.
• Correctly match IP addresses (and not match on the wrong things).
• About 200 lines of code to implement.

• At least there is now a X509_check_host() function (since January 2015).
• But... you still have to get the certificate and call it yourself.

libtls design philosophy

• As easy to use as possible.
• Safe and secure by default.
• Consistent, obvious and well documented.
• Support the use of pledge(2), chroot(2) and other sandbox environments:
  • Ensure access to files is deterministic (either at a certain point, or not at all).
  • Accept configuration via memory instead of files.

The libtls API

For full details read the man page, but in summary:

tls_init()

tls_config_new()
tls_config_set*()

tls_client() or tls_server()
tls_configure()
tls_connect*() or tls_accept*()
tls_handshake() ]
tls_read()/tls_write()
tls_close()
      

Let's rewrite that earlier code...

if ((ctx = tls_client()) == NULL)
        err(1, "failed to create client");
if (tls_configure(ctx, NULL) == -1)
        err(1, "failed to configure: %s", tls_error(ctx));

if (tls_connect(ctx, "www.linux.conf.au", "https") == -1)
        err(1, "failed to connect: %s", tls_error(ctx));

if (tls_write(ctx, buf, len) != len)
        errx(1, "failed to write: %s", tls_error(ctx));
if ((ret = tls_read(ctx, buf, sizeof(buf))) <= 0)
        errx(1, "failed to read: %s", tls_error(ctx));

if (tls_close(ctx) == -1)
        errx(1, "failed to close: %s", tls_error(ctx));
      

What just happened?

• You used TLSv1.2.
• You used an Authenticated Encryption with Authenticated Data (AEAD) ciphersuite.
• You have PFS.
• The certificate chain was verified successfully.
• The server name matched the certificate.

The libtls API design

• Consistent and deterministic return values (-1 or NULL indicates failure).
• POSIX-like behaviour where possible.
• tls_read(3)/tls_write(3) almost have read(2)/write(2) semantics.
• Opaque data structures.
• Take copies of strings and memory, instead of storing pointers.
• No X.509 or ASN.1 exposed (no sharp edges!).

General API design rules

• Keep it as simple as possible.
• Do not be afraid to iterate.
• Only add features when there is code that actually uses them:
  • Ensures that the API is appropriate.
  • Helps to manage feature bloat.
• Have symmetrical functions (for client/server) where possible.

Some more API examples

• Application-Layer Protocol Negotiation (ALPN)
• Server Name Indication (SNI)

Application-Layer Protocol Negotiation (ALPN)

libssl

After you've converted and packed your ALPN protocols into wire format (length prefixed strings)...

static int
tls_server_alpn_cb(SSL *ssl, const unsigned char **out, unsigned char *outlen,
    const unsigned char *in, unsigned int inlen, void *arg)
{
        struct tls *ctx = arg;

        if (SSL_select_next_proto((unsigned char**)out, outlen,
            ctx->config->alpn, ctx->config->alpn_len, in, inlen) ==
            OPENSSL_NPN_NEGOTIATED)
                return (SSL_TLSEXT_ERR_OK);

        return (SSL_TLSEXT_ERR_NOACK);
}
...
SSL_CTX_set_alpn_select_cb(*ssl_ctx, tls_server_alpn_cb, ctx);
      

Application-Layer Protocol Negotiation (ALPN)

libtls

if (tls_config_set_alpn(server_cfg, "h2,http/1.1") == -1)
        err(...);
      

Server Name Indication (SNI) - Server Side

libssl

For each additional certificate:

• Create an additional SSL_CTX and configure it.
• Load the certificate and private key on the new context.

Register a callback that:

• Receives the SNI that the client passed.
• Manually determines which of the certificates (and hence SSL_CTX) to use.
• Switches the SSL_CTX for the connection.

Server Name Indication (SNI) - Server Side

libtls

For each additional certificate:

if (tls_config_add_keypair_file(server_cfg, cert_path, key_path) == -1)
        err(...);
      

A quick look at return codes and error handling

libssl

If one of the following functions returns <= 0, call SSL_get_error().

• SSL_connect()
• SSL_accept()
• SSL_read()
• SSL_write()
• SSL_shutdown()

A quick look at return codes and error handling

libtls

If a function returns -1, call tls_config_error() or tls_error() to find out what went wrong.

The following functions, also have two special return values TLS_WANT_POLLIN and TLS_WANT_POLLOUT.

• tls_handshake()
• tls_read()
• tls_write()
• tls_close()

So what is wrong with a bad API?

But it was this way when I found it!

Bad APIs lead to:

• Security vulnerabilities
• Memory leaks
• Other bugs
• Wasted time
• Developer frustation

So what is wrong with a bad API?

"A principled solution to the problem must involve a complete redesign of the SSL libraries' API"

The most dangerous code in the world: validating SSL certificates in non-browser software (2012 paper)

So what is wrong with a bad API?

"The failure of various applications to note Python's negligence in this matter is a source of regular CVE assignment"

PEP 476 - Enabling certificate verification by default for stdlib http clients (2014)

Cites 11 CVEs in various applications, all due to bad default behaviour.

Some examples of how not to do things

SSL_CIPHER_description

desc = SSL_CIPHER_description(cipher, NULL, 0);
      

• Can return a pointer to dynamically allocated character array (caller is required to free).
• Or... can return a pointer to a static string!
• Effectively impossible to tell the difference based on the pointer.
• No other indicator.

Some examples of how not to do things

SSL_CIPHER_description

Must strcmp to determine what to do!

desc = SSL_CIPHER_description(cipher, NULL, 0);
if (strcmp(desc, "OPENSSL_malloc Error") == 0) {
        fprintf(stderr, "out of memory\n");
        goto err;
}
fprintf(stdout, "%s", desc);
free(desc);
      

Some examples of how not to do things

SSL_CIPHER_description

Some lessons to learn from this:

• Only return dynamic memory or static memory (never mix the two).
• Better: return a signal of success or failure, pass the data by reference.

Some examples of how not to do things

X509_verify_cert()

• Returns 1 if the chain built and successfully validated.
• Returns <= 0 if something failed.

Some examples of how not to do things

X509_verify_cert()

• Can return 1 (success) and have internal error code != X509_V_OK.
• Could previously return 0 (failure) and have internal error code == X509_V_OK.

Some examples of how not to do things

X509_verify_cert()

Some lessons to learn from this:

• If you're going to indicate success/failure in multiple places, ensure they're kept in sync.
• Better: return a signal of success or internal failure, make the detailed error authoritative.

OpenBSD: our development playground

• Proving ground - real world testing, bugs usually found very quickly.
• New API iteration/proof of concept.
• Initially ftp and httpd were using libtls (one client, one server).
• Now also acme-client, nc, ntpd, spamd, syslogd...
• Ports tree is incredibly beneficial (more so with libssl, but also libtls)

In summary

• Create APIs that are intuitive, easy to use and safe by default.
• Develop code that uses the API before (or during) the API development.
• Think about the corner cases and consider what users might overlook.

Thank you!

www.libressl.org