6.5. OpenSSL

The most common open source implementation of the SSL protocol is OpenSSL, a library that implements the SSL protocol and other cryptographic functions. OpenSSL also has a command line front end that allows the user to perform various administrative tasks, such as making and signing certificates, making RSA and DSA keys, generating Diffie-Hellman parameters, calculating various message digests, encrypting and decrypting with several ciphers, and handling S/MIME signed or encrypted mail. Versions are available for virtually all UNIX systems, Windows, and VMS.

The OpenSSL front end also has s_client and s_server functions that implement configurable SSL-enabled client and server programs. These applications are convenient for testing and debugging SSL applications. Indeed, our example traces of client authentication and Diffie-Hellman key exchange were generated with these programs.

The OpenSSL library and command line front end are too large to cover here. Fortunately, [Viega, Messier, and Chandra 2002] covers the topic in detail. One can also find documentation, source code, and further information about OpenSSL at the OpenSSL Web site <http://www.openssl.org>.

In the next section, we'll find it convenient to have an SSL-aware echo server to explore stunnel, so let's take the opportunity here to briefly explore programming with the OpenSSL library. As we'll see, it follows the familiar TCP server paradigm but with calls specific to SSL. Thus, for example, we'll call SSL_read instead of read.

Our short example exercises only the most basic aspects of the API and is in no way representative of the full functionality. [Rescorla 2001] and [Viega, Messier, and Chandra 2002] cover the material in detail and should be consulted for more information about programming with SSL.

We begin with the includes, defines, and main function in Figure 6.22. This section initializes SSL, sets up our SSL context, and arranges for the application to listen for and accept connections.

Figure 6.22. An SSL-aware Echo Server (main)

[View full size image]

Initialization

19	We include the necessary SSL headers and the etcp.h header, which contains the definitions for the library code from ETCP. The ERROR macro simply retrieves a printable version of the SSL error information and calls the error function from ETCP.
17	The INIT macro sets the program name for use by the error function.
1820	We initialize SSL and load the error strings for use by the ERROR macro.
2123	We create an SSL context for a server and specify that the server should accept only SSL 3 connections. The OpenSSL library is very flexible about what versions it will accept, but here we are simply insisting on SSL 3.
2428	Next, we load our certificate chain and private key. As indicated by the SCERT define, these reside in the file sslecho.pem.

Accept Connections

29	We call the tcp_server function from ETCP to obtain a listening socket on port 4134.
3234	We accept a TCP-level connection as usual.
3537	OpenSSL uses an I/O abstraction called a BIO, which hides the underlying I/O details from the application and allows it to transparently handle normal I/O, encrypted I/O, and SSL connections. These lines create a BIO for our new socket connection.
3840	Next, we create a new SSL context for our connection. The new context will inherit the settings, such as protocol version, of our original context that we obtained in line 21.
41	The call to SSL_set_bio connects our new SSL context to the socket BIO that we created in line 35.
4243	We complete the client's connection with the call to SSL_accept. This function waits for the client to initiate the SSL handshake sequence and returns when the handshake is complete or has failed because of errors.
4447	At this point, we have an SSL session established, and we call the echo function (Figure 6.23) to process the client's input. When echo returns, we shut down the SSL session, release the SSL context, close the TCP connection, and wait for another client. Note that this simple server can handle only one client at a time.

Figure 6.23. An SSL-Aware Echo Server (echo)

[View full size image]

As we see, the echo function looks just like it would in a normal TCP connection except that we call SSL_read and SSL_write instead of read and write, and we pass them a pointer to the SSL context instead of a socket descriptor.

We test sslecho by running it on linux and connecting to it with s_client from bsd. We've wrapped the Session-ID and Master-Key to make them fit on the page.

bsd:~
$ openssl s_client -connect linux:4134 -ssl3 -CAfile rootcert.pem
CONNECTED(00000003)
depth=1 /C=US/ST=Florida/L=Tampa/O=Text CA/CN=bsd.jcs.local
verify return:1
depth=0 /C=US/ST=Florida/L=Tampa/O=sslecho/CN=linux.jcs.local
verify return:1
---
Certificate chain
 0 s:/C=US/ST=Florida/L=Tampa/O=sslecho/CN=linux.jcs.local
   i:/C=US/ST=Florida/L=Tampa/O=Text CA/CN=bsd.jcs.local
 1 s:/C=US/ST=Florida/L=Tampa/O=Text CA/CN=bsd.jcs.local
   i:/C=US/ST=Florida/L=Tampa/O=Text CA/CN=bsd.jcs.local
---
Server certificate
-----BEGIN CERTIFICATE-----
MIICPzCCAaigAwIBAgIBCTANBgkqhkiG9w0BAQUFADBZMQswCQYDVQQGEwJVUzEQ
MA4GA1UECBMHRmxvcmlkYTEOMAwGA1UEBxMFVGFtcGExEDAOBgNVBAoTB1RleHQg
Q0ExFjAUBgNVBAMTDWJzZC5qY3MubG9jYWwwHhcNMDMwMzMxMjAwMjQyWhcNMDQw
MzMwMjAwMjQyWjBbMQswCQYDVQQGEwJVUzEQMA4GA1UECBMHRmxvcmlkYTEOMAwG
A1UEBxMFVGFtcGExEDAOBgNVBAoTB3NzbGVjaG8xGDAWBgNVBAMTD2xpbnV4Lmpj
cy5sb2NhbDCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA1m/WQACKxoYAuDFi
86a9wfAQtWk0jPfWCZhmnd2lkF5Y+wadWSF1+6yrhlaDV6+FHlOQRffpP2ax8+f9
WcGI7oYTPHlVyVBYrloy1W6qp/D9LIi5iRydPpUna8ypH17AmdVleR4tZNNj3ZmP
HyIdLy4b+TlsxR6zAaAaB1YhW8MCAwEAAaMVMBMwEQYJYIZIAYb4QgEBBAQDAgZA
MA0GCSqGSIb3DQEBBQUAA4GBAEvnIpT5qcPba6XD6jm3mgQ2yd7Xwu1Z17u5TOw1
pBXpMtaw6thkXVxBP7vJQccy/a1HUiDE1QQ6kqhZ+DQ8V73MFaz0PlkRP8Q/L6V/
74mPE1HmnKeUIHHtWh1XZbs4NC8KhnPiGOCPI03Qoze27g9EBx2UZnB47zHRl1AR
7CXD
-----END CERTIFICATE-----
subject=/C=US/ST=Florida/L=Tampa/O=sslecho/CN=linux.jcs.local
issuer=/C=US/ST=Florida/L=Tampa/O=Text CA/CN=bsd.jcs.local
---
No client certificate CA names sent
---
SSL handshake has read 1497 bytes and written 300 bytes
---
New, TLSv1/SSLv3, Cipher is DES-CBC3-SHA
Server public key is 1024 bit
SSL-Session:
    Protocol : SSLv3
    Cipher : DES-CBC3-SHA
    Session-ID: 57B151EA5F439BB9FEB607DEF7D803B44706FD602A9FD208
                12516A154B35BA20
    Session-ID-ctx:
    Master-Key: 1D91D5BB779D29BF01006D00A0B6FD63D79CD31E1D13B423
                D44C47EDA14E24EB4B5C50C02B698C85876971F16FDD6DE7
    Key-Arg : None
    Start Time: 1049151347
    Timeout : 7200 (sec)
    Verify return code: 0 (ok)
---
Hello linux!
Hello linux!
^D
DONE
bsd:~

Most of the output is information that s_client prints about the SSL session. We see that s_client has verified the sslecho server's certificate, that no client certificate was requested, and that we are using SSL 3 as expected. At the bottom of the session's output, we see our Hello linux! echoed from the server. We end the session by sending a ^D as an EOF.