9.1 Creating an SSL Client

9.1.1 Problem

You want to establish a connection from a client to a remote server using SSL.

9.1.2 Solution

Establishing a connection to a remote server using SSL is not entirely different from establishing a connection without using SSL at least it doesn't have to be. Establishing an SSL connection requires a little more setup work, consisting primarily of building an spc_x509store_t object (see Recipe 10.5) that contains the information necessary to verify the server. Once this is done, you need to create an SSL_CTX object and attach it to the connection. OpenSSL will handle the rest.

Before reading this recipe, make sure you understand the basics of public key infrastructure (see Recipe 10.1).

9.1.3 Discussion

Once you've created an spc_x509store_t object by loading it with the appropriate certificates and CRLs (see Recipe 10.10 and Recipe 10.11 for information on obtaining CRLs), connecting to a remote server over SSL can be as simple as making a call to the following function, spc_connect_ssl( ). You can optionally create an SSL_CTX object yourself using spc_create_sslctx( ) or the OpenSSL API. Alternatively, you can share one that has already been created for other connections, or you can let spc_connect_ssl( ) do it for you. In the latter case, the connection will be established and the SSL_CTX object that was created will be returned by way of a pointer to the SSL_CTX object pointer in the function's argument list.

#include <openssl/bio.h> #include <openssl/ssl.h>     BIO *spc_connect_ssl(char *host, int port, spc_x509store_t *spc_store,                      SSL_CTX **ctx) {   BIO *conn = 0;   int our_ctx = 0;       if (*ctx) {     CRYPTO_add(&((*ctx)->references), 1, CRYPTO_LOCK_SSL_CTX);     if (spc_store && spc_store != SSL_CTX_get_app_data(*ctx)) {       SSL_CTX_set_cert_store(*ctx, spc_create_x509store(spc_store));       SSL_CTX_set_app_data(*ctx, spc_store);     }   } else {     *ctx = spc_create_sslctx(spc_store);     our_ctx = 1;   }       if (!(conn = BIO_new_ssl_connect(*ctx))) goto error_exit;   BIO_set_conn_hostname(conn, host);   BIO_set_conn_int_port(conn, &port);       if (BIO_do_connect(conn) <= 0) goto error_exit;   if (our_ctx) SSL_CTX_free(*ctx);   return conn;     error_exit:   if (conn) BIO_free_all(conn);   if (*ctx) SSL_CTX_free(*ctx);   if (our_ctx) *ctx = 0;   return 0; }

We're providing an additional function here that will handle the differences between connecting to a remote server using SSL and connecting to a remote server not using SSL. In both cases, a BIO object is returned that can be used in the same way regardless of whether there is an SSL connection in place. If the ssl flag to this function is zero, the spc_store and ctx arguments will be ignored because they're only applicable to SSL connections.

OpenSSL makes heavy use of BIO objects, and many of the API functions require BIO arguments. What are these objects? Briefly, BIO objects are an abstraction for I/O that provides a uniform, medium-independent interface. BIO objects exist for file I/O, socket I/O, and memory. In addition, special BIO objects, known as BIO filters, can be used to filter data prior to writing to or reading from the underlying medium. BIO filters exist for operations such as base64 encoding and encryption using a symmetric cipher.

The OpenSSL SSL API is built on BIO objects, and a special filter handles the details of SSL. The SSL BIO filter is most useful when employed with a socket BIO object, but it can also be used for directly linking two BIO objects together (one for reading, one for writing) or to wrap pipes or some other type of connection-oriented communications primitive.

BIO *spc_connect(char *host, int port, int ssl, spc_x509store_t *spc_store,                  SSL_CTX **ctx) {   BIO *conn;   SSL *ssl_ptr;       if (ssl) {     if (!(conn = spc_connect_ssl(host, port, spc_store, ctx))) goto error_exit;     BIO_get_ssl(conn, &ssl_ptr);     if (!spc_verify_cert_hostname(SSL_get_peer_certificate(ssl_ptr), host))       goto error_exit;     if (SSL_get_verify_result(ssl_ptr) != X509_V_OK) goto error_exit;     return conn;   }       *ctx = 0;   if (!(conn = BIO_new_connect(host))) goto error_exit;   BIO_set_conn_int_port(conn, &port);   if (BIO_do_connect(conn) <= 0) goto error_exit;   return conn;     error_exit:   if (conn) BIO_free_all(conn);   return 0; }

As written, spc_connect( ) will attempt to perform post-connection verification of the remote peer's certificate. If you instead want to perform whitelist verification or no verification at all, you'll need to make the appropriate changes to the code using Recipe 10.9 for whitelist verification.

If a connection is successfully established, a BIO object will be returned regardless of whether you used spc_connect_ssl( ) or spc_connect( ) to establish the connection. With this BIO object, you can then use BIO_read( ) to read data, and BIO_write( ) to write data. You can also use other BIO functions, such as BIO_printf( ), for example. When you're done and want to terminate the connection, you should always use BIO_free_all( ) instead of BIO_free( ) to dispose of any chained BIO filters. When you've obtained an SSL-enabled BIO object from either of these functions, there will always be at least two BIO objects in the chain: one for the SSL filter and one for the socket connection.

9.1.4 See Also

• OpenSSL home page: http://www.openssl.org/

• Recipe 10.1, Recipe 10.5, Recipe 10.9, Recipe 10.10, Recipe 10.11