OpenSSL: Secure Communication

The openssl library provides glue for the OpenSSL library with the Racket port system. It provides functions nearly identically to the standard TCP subsystem in Racket, plus a generic ports->ssl-ports interface.

To use this library, you will need OpenSSL installed on your machine, but on many platforms the necessary libraries are included with the OS or with the Racket distribution. In particular:

• For Windows, openssl depends on "libeay32.dll" and "ssleay32.dll", which are included in the Racket distribution for Windows.

• For Mac OS X, openssl depends on "libssl.dylib" and "libcrypto.dylib", which are provided by Mac OS X 10.2 and later.

• For Unix, openssl depends on "libssl.so" and "libcrypto.so", which must be installed in a standard library location or in a directory listed by LD_LIBRARY_PATH. These libraries are included in many OS distributions.

1 TCP-like Client Procedures

Use ssl-connect or ssl-connect/enable-break to create an SSL connection over TCP. To create a secure connection, supply the result of ssl-secure-client-context or create a client context with ssl-make-client-context and configure it using the functions described in Context Procedures.

The optional client-protocol argument determines which encryption protocol is used, whether the server’s certificate is checked, etc. The argument can be either a client context created by ssl-make-client-context, or one of the following symbols: 'sslv2-or-v3 (the default), 'sslv2, 'sslv3, or 'tls; see ssl-make-client-context for further details (including the meanings of the protocol symbols).

Closing the resulting output port does not send a shutdown message to the server. See also ports->ssl-ports.

If hostname verification is enabled (see ssl-set-verify-hostname!), the peer’s certificate is checked against hostname.

(let ([ctx (ssl-make-client-context 'tls)])

; Load default verification sources (root certificates)

(ssl-load-default-verify-sources! ctx)

; Require certificate verification

(ssl-set-verify! ctx #t)

; Require hostname verification

(ssl-set-verify-hostname! ctx #t)

; No weak cipher suites

(ssl-set-ciphers! ctx "DEFAULT:!aNULL:!eNULL:!LOW:!EXPORT:!SSLv2")

; Seal context so further changes cannot weaken it

(ssl-seal-context! ctx)

ctx)

The context is cached, so different calls to ssl-secure-client-context return the same context unless (ssl-default-verify-sources) has changed.

Note that SSL protocol version 2 is deprecated on some platforms and may not be present in your system libraries. The use of SSLv2 may also compromise security; thus, using SSLv3 is recommended.

2 TCP-like Server Procedures

Call ssl-load-certificate-chain! and ssl-load-private-key! to avoid a no shared cipher error on accepting connections. The file "test.pem" in the "openssl" collection is a suitable argument for both calls when testing. Since "test.pem" is public, however, such a test configuration obviously provides no security.

An SSL listener is a synchronizable value (see sync). It is ready—with itself as its value—when the underlying TCP listener is ready. At that point, however, accepting a connection with ssl-accept may not complete immediately, because further communication is needed to establish the connection.

Closing the resulting output port does not send a shutdown message to the client. See also ports->ssl-ports.

See also ssl-connect about the limitations of reading and writing to an SSL connection (i.e., one direction at a time).

The ssl-accept/enable-break procedure is analogous to tcp-accept/enable-break.

3 SSL-wrapper Interface

The mode argument can be 'connect or 'accept. The mode determines how the SSL protocol is initialized over the ports, either as a client or as a server. As with ssl-listen, in 'accept mode, supply a context that has been initialized with ssl-load-certificate-chain! and ssl-load-private-key! to avoid a no shared cipher error.

The context argument should be a client context for 'connect mode or a server context for 'accept mode. If it is not supplied, a context is created using the protocol specified by a protocol argument.

If the protocol argument is not supplied, it defaults to 'sslv2-or-v3. See ssl-make-client-context for further details (including all options and the meanings of the protocol symbols). This argument is ignored if a context argument is supplied.

If close-original? is true, then when both SSL ports are closed, the given input and output ports are automatically closed.

If shutdown-on-close? is true, then when the output SSL port is closed, it sends a shutdown message to the other end of the SSL connection. When shutdown is enabled, closing the output port can fail if the given output port becomes unwritable (e.g., because the other end of the given port has been closed by another process).

The error argument is an error procedure to use for raising communication errors. The default is error, which raises exn:fail; in contrast, ssl-accept and ssl-connect use an error function that raises exn:fail:network.

See also ssl-connect about the limitations of reading and writing to an SSL connection (i.e., one direction at a time).

If hostname verification is enabled (see ssl-set-verify-hostname!), the peer’s certificate is checked against hostname.

4 Context Procedures

The following kinds of verification sources are supported:

• If src is a path or string, it is treated as a PEM file containing root certificates. The file is loaded immediately.

• If src is (list 'directory dir), then dir should contain PEM files with hashed symbolic links (see the openssl c_rehash utility). The directory contents are not loaded immediately; rather, they are searched only when a certificate needs verification.

• If src is (list 'win32-store store), then the certificates from the store named store are loaded immediately. Only supported on Windows.

• If src is (list 'macosx-keychain path), then the certificates from the keychain stored at path are loaded immediately. Only supported on Mac OS X.

If try? is #f and loading src fails (for example, because the file or directory does not exist), then an exception is raised. If try? is a true value, then a load failure is ignored.

You can use the file "test.pem" of the "openssl" collection for testing purposes. Since "test.pem" is public, such a test configuration obviously provides no security.

• On Linux, the default sources are determined by the SSL_CERT_FILE and SSL_CERT_DIR environment variables, if the variables are set, or the system-wide default locations otherwise.

• On Mac OS X, the default sources consist of the system keychain for root certificates: '(macosx-keychain "/System/Library/Keychains/SystemRootCertificates.keychain").

• On Windows, the default sources consist of the system certificate store for root certificates: '(win32-store "ROOT").

This chain is used to identify the client or server when it connects or accepts connections. Loading a chain overwrites the old chain. Also call ssl-load-private-key! to load the certificate’s corresponding key.

You can use the file "test.pem" of the "openssl" collection for testing purposes. Since "test.pem" is public, such a test configuration obviously provides no security.

If rsa? is #t (the default), the first RSA key is read (i.e., non-RSA keys are skipped). If asn1? is #t, the file is parsed as ASN1 format instead of PEM.

You can use the file "test.pem" of the "openssl" collection for testing purposes. Since "test.pem" is public, such a test configuration obviously provides no security.

Loading the suggested certificates does not imply trust, however; any certificate presented by the client will be checked using the trusted roots loaded by ssl-load-verify-root-certificates!.

You can use the file "test.pem" of the "openssl" collection for testing purposes where the peer identifies itself using "test.pem".

5 Peer Verification

Enabling verification also requires, at a minimum, designating trusted certificate authorities with ssl-load-verify-source!.

Verifying the certificate is not sufficient to prevent attacks by active adversaries, such as man-in-the-middle attacks. See also ssl-set-verify-hostname!.

Hostname verification does not imply certificate verification. To verify the certificate itself, also call ssl-set-verify!.

The result list may contain both hostnames such as "www.racket-lang.org" and hostname patterns such as "*.racket-lang.org".

Use ssl-peer-check-hostname or ssl-peer-certificate-hostnames instead to check the validity of an SSL connection.

6 SHA-1 Hashing

The sha1 function composes bytes->hex-string with sha1-bytes.