2008-11-03 18:50:17 +00:00
|
|
|
|
<?xml version="1.0" encoding="iso-8859-1"?>
|
2005-11-09 22:10:44 +00:00
|
|
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
|
|
|
|
|
<head>
|
|
|
|
|
<title>CL+SSL</title>
|
|
|
|
|
<link rel="stylesheet" type="text/css" href="index.css"/>
|
|
|
|
|
</head>
|
|
|
|
|
<body>
|
2008-03-07 21:28:49 +00:00
|
|
|
|
<h1>CL+SSL</h1>
|
2005-11-09 22:10:44 +00:00
|
|
|
|
|
2007-07-14 11:49:29 +00:00
|
|
|
|
<p>
|
2008-03-07 21:28:49 +00:00
|
|
|
|
A Common Lisp interface to OpenSSL.
|
2007-07-14 11:49:29 +00:00
|
|
|
|
</p>
|
2008-03-07 21:28:49 +00:00
|
|
|
|
|
|
|
|
|
<h3>About</h3>
|
|
|
|
|
|
2007-07-07 15:25:09 +00:00
|
|
|
|
<p>
|
2008-03-07 21:28:49 +00:00
|
|
|
|
This library is a fork
|
|
|
|
|
of <a href="http://www.cliki.net/SSL-CMUCL">SSL-CMUCL</a>. The
|
|
|
|
|
original SSL-CMUCL source code was written by Eric Marsden and
|
|
|
|
|
includes contributions by Jochen Schmidt. Development into CL+SSL
|
|
|
|
|
was done by David Lichteblau. License: MIT-style.
|
2007-07-07 15:25:09 +00:00
|
|
|
|
</p>
|
2008-03-07 21:28:49 +00:00
|
|
|
|
|
2007-01-16 19:49:03 +00:00
|
|
|
|
<p>
|
2008-03-07 21:28:49 +00:00
|
|
|
|
Distinguishing features: CL+SSL is portable code based on CFFI and
|
|
|
|
|
gray streams. It defines its own libssl BIO method, so that SSL
|
|
|
|
|
I/O can be written over portable Lisp streams instead of bypassing
|
|
|
|
|
the streams and sending data over Unix file descriptors directly.
|
|
|
|
|
(But the traditional approach is still used if possible.)
|
2007-01-16 19:49:03 +00:00
|
|
|
|
</p>
|
|
|
|
|
|
2005-11-09 22:10:44 +00:00
|
|
|
|
<h3>Download</h3>
|
2005-11-25 20:14:04 +00:00
|
|
|
|
<p>
|
2011-05-22 22:33:22 +00:00
|
|
|
|
The library is available via <a href="http://www.quicklisp.org/">Quicklisp</a>.
|
2005-11-25 20:14:04 +00:00
|
|
|
|
</p>
|
2011-05-22 22:33:22 +00:00
|
|
|
|
|
2005-11-25 22:55:18 +00:00
|
|
|
|
<p>
|
2011-05-22 22:33:22 +00:00
|
|
|
|
The Git repository: <a href="https://gitorious.org/cl-plus-ssl/cl-plus-ssl">https://gitorious.org/cl-plus-ssl/cl-plus-ssl</a>.
|
|
|
|
|
(<a href="https://gitorious.org/cl-plus-ssl/cl-plus-ssl/archive-tarball/master">download snapshot</a>).
|
2005-11-25 22:55:18 +00:00
|
|
|
|
</p>
|
2005-11-09 22:10:44 +00:00
|
|
|
|
<p>
|
|
|
|
|
Send bug reports to <a
|
|
|
|
|
href="mailto:cl-plus-ssl-devel@common-lisp.net">cl-plus-ssl-devel@common-lisp.net</a>
|
|
|
|
|
(<a
|
|
|
|
|
href="http://common-lisp.net/cgi-bin/mailman/listinfo/cl-plus-ssl-devel">list
|
2006-11-18 09:49:21 +00:00
|
|
|
|
information</a>).
|
2005-11-09 22:10:44 +00:00
|
|
|
|
</p>
|
|
|
|
|
|
2011-05-22 22:33:22 +00:00
|
|
|
|
<p>
|
|
|
|
|
<i>Note</i> that you need the <tt>libssl-dev</tt> package on Debian to
|
|
|
|
|
load this package without manual configuration.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
OpenSSL binaries for Windows may be found at
|
|
|
|
|
<a href="http://www.slproweb.com/products/Win32OpenSSL.html">http://www.slproweb.com/products/Win32OpenSSL.html</a>
|
|
|
|
|
(slproweb.com is a 3rd party; if you have questions about the OpenSSL installer they provide,
|
|
|
|
|
please ask in the mailing list specified on the linked page).
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
2008-03-07 21:28:49 +00:00
|
|
|
|
<!--
|
2005-11-09 22:10:44 +00:00
|
|
|
|
<p>
|
|
|
|
|
Comparison chart:
|
|
|
|
|
</p>
|
|
|
|
|
<table border="1" cellpadding="2" cellspacing="0">
|
|
|
|
|
<thead>
|
|
|
|
|
<tr>
|
|
|
|
|
<th></th>
|
|
|
|
|
<th><b>FFI</b></th>
|
|
|
|
|
<th><b>Streams</b></th>
|
|
|
|
|
<th><b>Lisp-BIO</b></th>
|
|
|
|
|
</tr>
|
|
|
|
|
</thead>
|
|
|
|
|
<tr>
|
|
|
|
|
<td>CL+SSL</td>
|
|
|
|
|
<td>CFFI</td>
|
2005-11-25 20:14:04 +00:00
|
|
|
|
<td>gray<sup>1</sup>, buffering output</td>
|
2005-11-09 22:10:44 +00:00
|
|
|
|
<td>yes</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td>CL-SSL</td>
|
|
|
|
|
<td>UFFI</td>
|
2005-11-25 20:14:04 +00:00
|
|
|
|
<td>gray, buffering I/O [<em>part of ACL-COMPAT</em>]</td>
|
2005-11-09 22:10:44 +00:00
|
|
|
|
<td>no</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td>SSL-CMUCL</td>
|
|
|
|
|
<td>CMUCL/ALIEN</td>
|
|
|
|
|
<td>CMUCL, non-buffering</td>
|
|
|
|
|
<td>no</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
2005-11-25 20:14:04 +00:00
|
|
|
|
<p>
|
|
|
|
|
<sup>1</sup> Character I/O and external formats in CL+SSL
|
|
|
|
|
are provided
|
|
|
|
|
using <a href="http://weitz.de/flexi-streams/">flexi-streams</a>.
|
|
|
|
|
</p>
|
2008-03-07 21:28:49 +00:00
|
|
|
|
-->
|
2005-11-09 22:10:44 +00:00
|
|
|
|
|
|
|
|
|
<h3>API functions</h3>
|
2008-11-04 00:25:52 +00:00
|
|
|
|
<p>
|
|
|
|
|
<div class="def">Function CL+SSL:ENSURE-INITIALIZED (&key (method 'ssl-v23-method) (rand-seed nil))</div>
|
|
|
|
|
In most cases you <strong>do not</strong> need to call this function, because it is called
|
|
|
|
|
automatically. The only reason to call it explicitly is to supply the <tt>rand-seed</tt> parameter.
|
|
|
|
|
In this case do it before calling any other functions.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
Keyword arguments:
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<tt>method</tt>. Just leave its default value.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<tt>rand-seed</tt> is an octet sequence to initialize OpenSSL random number generator.
|
|
|
|
|
On many platforms, including Linux and Windows, it may be leaved NIL (default),
|
|
|
|
|
because OpenSSL initializes the random number generator from OS specific service. But for
|
|
|
|
|
example on Solaris it may be necessary to supply this value. The minimum length required
|
|
|
|
|
by OpenSSL is 128 bits. See here <a href="http://www.openssl.org/support/faq.html#USER1">
|
|
|
|
|
http://www.openssl.org/support/faq.html#USER1</a> for the details.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
Hint: do not use Common Lisp RANDOM function to generate the <tt>rand-seed</tt>, because the function
|
|
|
|
|
usually returns predictable values.
|
|
|
|
|
</p>
|
2005-11-09 22:10:44 +00:00
|
|
|
|
<p>
|
2008-11-03 09:25:39 +00:00
|
|
|
|
<div class="def">Function CL+SSL:MAKE-SSL-CLIENT-STREAM (fd-or-stream &key external-format certificate key password close-callback (unwrap-streams-p t))<br/><br/>
|
|
|
|
|
Function CL+SSL:MAKE-SSL-SERVER-STREAM (fd-or-stream &key external-format certificate key password close-callback (unwrap-streams-p t))</div>
|
2008-03-07 21:28:49 +00:00
|
|
|
|
Return an SSL stream for the client (server)
|
|
|
|
|
socket <tt>fd-or-stream</tt>. All reads and writes to this
|
|
|
|
|
stream will be pushed through the OpenSSL library.
|
2007-07-07 17:42:22 +00:00
|
|
|
|
</p>
|
|
|
|
|
<p>
|
2008-03-07 21:28:49 +00:00
|
|
|
|
Keyword arguments:
|
2007-07-07 16:26:11 +00:00
|
|
|
|
</p>
|
|
|
|
|
<p>
|
2008-03-07 21:28:49 +00:00
|
|
|
|
If <tt>fd-or-stream</tt> is a lisp stream, the SSL stream will
|
|
|
|
|
close it automatically. File descriptors are not closed
|
|
|
|
|
automatically. However, if <tt>close-callback</tt> is non-nil, it
|
|
|
|
|
will be called with zero arguments when the SSL stream is closed.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
If <tt>unwrap-stream-p</tt> is true (the default), a stream for a
|
|
|
|
|
file descriptor will be replaced by that file descriptor
|
|
|
|
|
automatically. This is similar to passing the result
|
|
|
|
|
of <tt>stream-fd</tt> as an argument, except that a deadline
|
|
|
|
|
associated with the stream object will be taken into account, and
|
|
|
|
|
that the stream will be closed automatically. As with file
|
|
|
|
|
descriptor arguments, no I/O will actually be done on the stream
|
|
|
|
|
object.
|
2007-07-07 17:42:22 +00:00
|
|
|
|
</p>
|
|
|
|
|
<p>
|
2007-07-07 15:26:13 +00:00
|
|
|
|
<tt>certificate</tt> is the path to a file containing the PEM-encoded
|
2008-11-03 09:25:39 +00:00
|
|
|
|
certificate.
|
|
|
|
|
</p>
|
2008-11-03 17:58:45 +00:00
|
|
|
|
<p>
|
|
|
|
|
<tt>key</tt> is the path to the PEM-encoded key, which may be associated
|
2008-11-03 09:25:39 +00:00
|
|
|
|
with the passphrase <tt>password</tt>.
|
2005-11-09 22:10:44 +00:00
|
|
|
|
</p>
|
|
|
|
|
<p>
|
2005-11-25 20:14:04 +00:00
|
|
|
|
If <tt>external-format</tt> is <tt>nil</tt> (the default), a plain
|
|
|
|
|
<tt>(unsigned-byte 8)</tt> SSL stream is returned. With a
|
|
|
|
|
non-null <tt>external-format</tt>, a flexi-stream capable of
|
|
|
|
|
character I/O will be returned instead, with the specified value
|
|
|
|
|
as its initial external format.
|
|
|
|
|
</p>
|
2008-11-03 17:58:45 +00:00
|
|
|
|
<p>
|
|
|
|
|
<div class="def">Function CL+SSL:USE-CERTIFICATE-CHAIN-FILE (certificate-chain-file)</div>
|
2008-11-03 23:19:28 +00:00
|
|
|
|
Loads a PEM encoded certificate chain file <tt>certificate-chain-file</tt>
|
2008-11-03 17:58:45 +00:00
|
|
|
|
and adds the chain to global context. The certificates must be sorted
|
|
|
|
|
starting with the subject's certificate (actual client or server certificate),
|
|
|
|
|
followed by intermediate CA certificates if applicable, and ending at
|
|
|
|
|
the highest level (root) CA.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
Note: the RELOAD function clears the global
|
|
|
|
|
context and in particular the loaded certificate chain.
|
|
|
|
|
</p>
|
2005-11-16 17:07:53 +00:00
|
|
|
|
<p>
|
|
|
|
|
<div class="def">Function CL+SSL:RELOAD ()</div>
|
2005-11-25 20:14:04 +00:00
|
|
|
|
Reload <tt>libssl</tt>. Call this function after restarting a Lisp
|
2005-11-16 17:07:53 +00:00
|
|
|
|
core with CL+SSL dumped into it on Lisp implementations that do
|
|
|
|
|
not reload shared libraries automatically.
|
|
|
|
|
</p>
|
2008-03-07 21:28:49 +00:00
|
|
|
|
<p>
|
|
|
|
|
<div class="def">Function CL+SSL:STREAM-FD (stream)</div>
|
|
|
|
|
Return <tt>stream</tt>'s file descriptor as an integer, if known.
|
|
|
|
|
Otherwise return <tt>stream</tt> itself. The result of this
|
|
|
|
|
function can be passed to <tt>make-ssl-client-stream</tt>
|
|
|
|
|
and <tt>make-ssl-server-stream</tt>.
|
|
|
|
|
</p>
|
2011-05-22 22:33:22 +00:00
|
|
|
|
<p>
|
|
|
|
|
<div class="def">Function CL+SSL:RANDOM-BYTES (count)</div>
|
|
|
|
|
Generates <tt>count</tt> cryptographically strong pseudo-random bytes. Returns
|
|
|
|
|
the bytes as a <tt>simple-array</tt> with <tt>element-type '(unsigned-byte 8)</tt>.
|
|
|
|
|
Signals an <tt>error</tt> in case of problems, for example when the OpenSSL
|
|
|
|
|
random number generator has not been seeded with enough randomness to ensure
|
|
|
|
|
an unpredictable byte sequence.
|
|
|
|
|
</p>
|
2005-11-09 22:10:44 +00:00
|
|
|
|
|
|
|
|
|
<h3>Portability</h3>
|
|
|
|
|
<p>
|
|
|
|
|
CL+SSL requires CFFI with callback support.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
Test results for Linux/x86, except OpenMCL which was tested on
|
|
|
|
|
Linux/PPC:
|
|
|
|
|
</p>
|
|
|
|
|
<table border="1" cellpadding="2" cellspacing="0">
|
|
|
|
|
<thead>
|
|
|
|
|
<tr>
|
|
|
|
|
<th><b>Lisp Implementation</b></th>
|
|
|
|
|
<th><b>Status</b></th>
|
|
|
|
|
<th><b>Comments</b></th>
|
|
|
|
|
</tr>
|
|
|
|
|
</thead>
|
|
|
|
|
<tr><td>OpenMCL</td><td class="working">Working</td></tr>
|
|
|
|
|
<tr><td>SBCL</td><td class="working">Working</td></tr>
|
|
|
|
|
<tr><td>CMU CL</td><td class="working">Working</td></tr>
|
2007-07-07 16:47:57 +00:00
|
|
|
|
<tr><td>CLISP</td><td class="working">Working</td></tr>
|
2005-11-09 22:10:44 +00:00
|
|
|
|
<tr><td>LispWorks</td><td class="working">Working</td></tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td>Allegro</td>
|
|
|
|
|
<td class="broken">Broken</td>
|
|
|
|
|
<td>segfault</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr><td>Corman CL</td><td class="unknown">Unknown</td></tr>
|
|
|
|
|
<tr><td>Digitool MCL</td><td class="unknown">Unknown</td></tr>
|
|
|
|
|
<tr><td>Scieneer CL</td><td class="unknown">Unknown</td></tr>
|
2008-11-01 05:18:43 +00:00
|
|
|
|
<tr><td>ECL</td><td class="unknown">Unknown</td></tr>
|
2005-11-09 22:10:44 +00:00
|
|
|
|
<tr><td>GCL</td><td class="unknown">Unknown</td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
<h3>TODO</h3>
|
|
|
|
|
<ul>
|
2008-03-07 21:28:49 +00:00
|
|
|
|
<li>CNAME checking</li>
|
|
|
|
|
<li>session caching</li>
|
|
|
|
|
<li>The FFI code for all platforms except clisp needs to be
|
|
|
|
|
rewritten.</li>
|
2005-11-09 22:10:44 +00:00
|
|
|
|
</ul>
|
|
|
|
|
|
2008-03-07 21:28:49 +00:00
|
|
|
|
<h3>News</h3>
|
2011-05-22 22:33:22 +00:00
|
|
|
|
<p>
|
|
|
|
|
2011-05-22
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
Added new public function RANDOM-BYTES.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
2011-05-22
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
The source code repository is moved to Git.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
2011-03-25 12:17:15 +00:00
|
|
|
|
<p>
|
|
|
|
|
2011-03-25
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
OpenSSL libraries names for OpenBSD, thanks to Thomas de Grivel.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
2010-05-25 22:06:51 +00:00
|
|
|
|
<p>
|
|
|
|
|
2010-05-26
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
Fixed two bugs in LISTEN, thanks to Ron Garret.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
2009-09-16 21:30:29 +00:00
|
|
|
|
<p>
|
|
|
|
|
2009-09-17
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
libssl loading on FreeBSD 7.2 fixed, thanks to Stian Sletner.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
2007-01-16 19:49:03 +00:00
|
|
|
|
<p>
|
2008-03-07 21:28:49 +00:00
|
|
|
|
2008-xx-yy
|
2007-01-16 19:49:03 +00:00
|
|
|
|
</p>
|
2008-03-07 21:28:49 +00:00
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
2009-09-16 21:30:29 +00:00
|
|
|
|
Support for I/O deadlines (Clozure CL and SBCL).
|
2008-03-07 21:28:49 +00:00
|
|
|
|
</li>
|
2008-11-03 09:25:39 +00:00
|
|
|
|
<li>
|
2009-09-16 21:30:29 +00:00
|
|
|
|
Support for encrypted keys, thanks to Vsevolod Dyomkin.
|
2008-11-03 09:25:39 +00:00
|
|
|
|
</li>
|
2008-11-03 17:58:45 +00:00
|
|
|
|
<li>
|
2009-09-16 21:30:29 +00:00
|
|
|
|
Chained certificates support, thanks to Juhani R<>nkimies.
|
2008-11-04 00:25:52 +00:00
|
|
|
|
</li>
|
|
|
|
|
<li>
|
2009-09-16 21:30:29 +00:00
|
|
|
|
More secure initialization of OpenSSL random number generator.
|
2008-11-04 00:25:52 +00:00
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
Minor CLISP-specific fixes.
|
2008-11-03 17:58:45 +00:00
|
|
|
|
</li>
|
2008-03-07 21:28:49 +00:00
|
|
|
|
</ul>
|
2005-11-09 22:10:44 +00:00
|
|
|
|
<p>
|
2008-03-07 21:28:49 +00:00
|
|
|
|
2007-xx-yy
|
2005-11-09 22:10:44 +00:00
|
|
|
|
</p>
|
2008-03-07 21:28:49 +00:00
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
2009-09-16 21:30:29 +00:00
|
|
|
|
Fixed windows support, thanks to Matthew Kennedy and Anton Vodonosov.
|
2008-03-07 21:28:49 +00:00
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
2005-11-09 22:10:44 +00:00
|
|
|
|
<p>
|
2008-03-07 21:28:49 +00:00
|
|
|
|
2007-07-07
|
2005-11-09 22:10:44 +00:00
|
|
|
|
</p>
|
2008-03-07 21:28:49 +00:00
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
2009-09-16 21:30:29 +00:00
|
|
|
|
Improved CLISP support, thanks
|
|
|
|
|
to <a
|
|
|
|
|
href="http://web.kepibu.org/code/lisp/cl+ssl/">Pixel
|
|
|
|
|
// pinterface</a>, as well as client certificate support.
|
2008-03-07 21:28:49 +00:00
|
|
|
|
</li>
|
|
|
|
|
<li>
|
2009-09-16 21:30:29 +00:00
|
|
|
|
Re-introduced support for direct access to file descriptors as
|
|
|
|
|
an optimization. New function <tt>stream-fd</tt>. New keyword
|
|
|
|
|
argument <tt>close-callback</tt>.
|
2008-03-07 21:28:49 +00:00
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
2005-11-09 22:10:44 +00:00
|
|
|
|
<p>
|
2008-03-07 21:28:49 +00:00
|
|
|
|
2007-01-16: CL+SSL is now available under an MIT-style license.
|
2005-11-09 22:10:44 +00:00
|
|
|
|
</p>
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|