The Socket Stream SSL interface allows you to use Secure Socket Layer (SSL) with Lisp objects of type
The interface is based on the OpenSSL code, and most of it is simply an FLI interface to OpenSSL functions. The main LispWorks specific code is the way OpenSSL is integrated with socket-stream.
The Socket Stream SSL interface is in the
"comm" module, so to load it you evaluate
In this section we assume that the current package uses the
comm package. That is,
comm package symbols may not be qualified explicitly.
There are three ways to make a socket-stream with SSL processing:
(make-instance 'socket-stream :ssl-ctx ...)
(open-tcp-stream ... :ssl-ctx ...)
(open-tcp-stream some-url 443 :ssl-ctx t)
When the value of the
:ssl-ctx argument is a symbol, LispWorks automatically creates an SSL_CTX object and an SSL object and uses them. If you need to configure these objects, you can access them by the following methods:
Where an OpenSSL function takes an SSL* or SSL_CTX*, the Lisp function's argument must be a foreign pointer of type ssl-pointer, ssl-ctx-pointer or ssl-cipher-pointer. Where an OpenSSL function takes a
int, the Lisp function's argument must be a string or integer. Where an OpenSSL function takes other kinds of pointers, the Lisp function's argument must be a foreign pointer. The return values are integers or foreign pointers unless stated otherwise.
If you do this, an important point to note is that on Microsoft Windows, the
:calling-convention must be
:cdecl (it defaults to
:stdcall). If using OpenSSL suddenly causes mysterious crashes, the calling-convention in your foreign function definitions is the first thing to check.
The keyword arguments
:ssl-configure-callback can be be passed to create and configure socket streams with SSL processing. The various methods for creating and configuring SSL streams accept these keyword arguments as shown in SSL configuration keywords.
Together with ssl-side, this symbol specifies which protocol to use. ssl-ctx can be one of:
:default, meaning use the default. Currently this is the same as
2) One of
:tls-v1. These are mapped to the SSLv2_*, SSLv3_*, SSLv23_*, TLSv1_* methods.
LispWorks makes a new SSL_CTX object and uses it and frees it when the stream is closed. make-instance, attach-ssl and open-tcp-stream also make an SSL object, use it and free it when the stream is closed.
A foreign pointer of type
This corresponds to the C type SSL_CTX*. This is used and is not freed when the stream is closed. make-instance, attach-ssl and open-tcp-stream also make an SSL object, use it and free it when the stream is closed. The foreign pointer maybe a result of a call to
make-ssl-ctx, but it can also be a result of your code, provided that it points to a valid SSL_CTX and has the type
A foreign pointer of type
This corresponds to the C type SSL*. This specifies the SSL to use in make-instance, attach-ssl and open-tcp-stream. This maybe a result of a call to
ssl-new. but can also be a result of your code, provided that it points to a valid SSL object and has the type
. The SSL is used and is not freed when the stream is closed.
:ssl-side specifies which side the stream is. The value ssl-side can be one of
:both. open-tcp-stream does not take this keyword and always uses
:client. For the other calls this argument defaults to
:server. The value of ssl-side is used in two cases:
If the value of ssl-ctx is a
, ssl-side is ignored.
:ctx-configure-callback specifies a callback, a function which takes a foreign pointer of type
. This is called immediately after a new SSL_CTX is created. If the value of ssl-ctx is not a symbol, ctx-configure-callback is ignored.
:ssl-configure-callback specifies a callback, a function which takes a foreign pointer of type
. This is called immediately after a new SSL is created. If the value of ssl-ctx is not a ssl-pointer, ssl-configure-callback is ignored.
You can attach SSL to an existing socket-stream by calling attach-ssl on the stream. attach-ssl ensures the OpenSSL library is loaded and seeds the Pseudo Random Number Generator (PRNG). The socket-stream SSL keyword arguments are processed by attach-ssl as described in Socket Stream SSL keyword arguments.
The C objects SSL and SSL_CTX are represented in LispWorks by foreign pointers with type ssl-pointer and ssl-ctx-pointer, which correspond to the C types SSL* and SSL_CTX*. These foreign types should be used for any foreign function that takes or returns these C types, and must be used when passing a foreign pointer as the value of the
Making SSL objects is a way of getting access to them to perform configuration, but, especially in the case of the SSL_CTX, it is a useful way to avoid repeated calls to the configuration routines which may be time consuming. For example, if we have defined a function
configure-a-ctx, and we want to read once every 60 seconds from some URL, we can write:
The SSL objects could be made either by make-ssl-ctx or
ssl-new or by user code that calls the C functions SSL_CTX_new and SSL_new.
destroy-ssl-ctx frees the SSL_CTX object. To free an SSL object you would call
destroy-ssl. See the manual entries for full descriptions of these functions.
All the functions that make a SSL_CTX first call
ensure-ssl, so normally you do not need to initialize the library. If your code makes a SSL_CTX itself (that is, not by calling any of the LispWorks interface functions), it needs to initialize the library first. Normally that should be done by an explicit call to ensure-ssl, which loads the SSL library and calls SSL_library_init and SSL_load_error_strings, and also does some LispWorks specific initializations. If your code must do the initialization, ensure-ssl should still be called with the argument
:already-done t, which tells it that the library is already loaded and initialized.
At the time of writing, OpenSSL is available as shown in OpenSSL availability:
32-bit and 64-bit libraries are available at
Installed by default on Solaris 10. For other versions, see the freeware from Sun at
LispWorks User Guide and Reference Manual - 13 Feb 2015