333 lines
11 KiB
HTML
333 lines
11 KiB
HTML
<?xml version="1.0" encoding="iso-8859-1"?>
|
||
<!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>
|
||
<h1>CL+SSL</h1>
|
||
|
||
<p>
|
||
A Common Lisp interface to OpenSSL.
|
||
</p>
|
||
|
||
<h3>About</h3>
|
||
|
||
<p>
|
||
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.
|
||
</p>
|
||
|
||
<p>
|
||
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.)
|
||
</p>
|
||
|
||
<h3>Download</h3>
|
||
<p>
|
||
The library is available via <a href="http://www.quicklisp.org/">Quicklisp</a>.
|
||
</p>
|
||
|
||
<p>
|
||
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>).
|
||
</p>
|
||
<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
|
||
information</a>).
|
||
</p>
|
||
|
||
<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>
|
||
|
||
|
||
<!--
|
||
<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>
|
||
<td>gray<sup>1</sup>, buffering output</td>
|
||
<td>yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td>CL-SSL</td>
|
||
<td>UFFI</td>
|
||
<td>gray, buffering I/O [<em>part of ACL-COMPAT</em>]</td>
|
||
<td>no</td>
|
||
</tr>
|
||
<tr>
|
||
<td>SSL-CMUCL</td>
|
||
<td>CMUCL/ALIEN</td>
|
||
<td>CMUCL, non-buffering</td>
|
||
<td>no</td>
|
||
</tr>
|
||
</table>
|
||
<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>
|
||
-->
|
||
|
||
<h3>API functions</h3>
|
||
<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>
|
||
<p>
|
||
<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>
|
||
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.
|
||
</p>
|
||
<p>
|
||
Keyword arguments:
|
||
</p>
|
||
<p>
|
||
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.
|
||
</p>
|
||
<p>
|
||
<tt>certificate</tt> is the path to a file containing the PEM-encoded
|
||
certificate.
|
||
</p>
|
||
<p>
|
||
<tt>key</tt> is the path to the PEM-encoded key, which may be associated
|
||
with the passphrase <tt>password</tt>.
|
||
</p>
|
||
<p>
|
||
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>
|
||
<p>
|
||
<div class="def">Function CL+SSL:USE-CERTIFICATE-CHAIN-FILE (certificate-chain-file)</div>
|
||
Loads a PEM encoded certificate chain file <tt>certificate-chain-file</tt>
|
||
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>
|
||
<p>
|
||
<div class="def">Function CL+SSL:RELOAD ()</div>
|
||
Reload <tt>libssl</tt>. Call this function after restarting a Lisp
|
||
core with CL+SSL dumped into it on Lisp implementations that do
|
||
not reload shared libraries automatically.
|
||
</p>
|
||
<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>
|
||
<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>
|
||
|
||
<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>
|
||
<tr><td>CLISP</td><td class="working">Working</td></tr>
|
||
<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>
|
||
<tr><td>ECL</td><td class="unknown">Unknown</td></tr>
|
||
<tr><td>GCL</td><td class="unknown">Unknown</td></tr>
|
||
</table>
|
||
|
||
<h3>TODO</h3>
|
||
<ul>
|
||
<li>CNAME checking</li>
|
||
<li>session caching</li>
|
||
<li>The FFI code for all platforms except clisp needs to be
|
||
rewritten.</li>
|
||
</ul>
|
||
|
||
<h3>News</h3>
|
||
<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>
|
||
<p>
|
||
2011-03-25
|
||
</p>
|
||
<ul>
|
||
<li>
|
||
OpenSSL libraries names for OpenBSD, thanks to Thomas de Grivel.
|
||
</li>
|
||
</ul>
|
||
<p>
|
||
2010-05-26
|
||
</p>
|
||
<ul>
|
||
<li>
|
||
Fixed two bugs in LISTEN, thanks to Ron Garret.
|
||
</li>
|
||
</ul>
|
||
<p>
|
||
2009-09-17
|
||
</p>
|
||
<ul>
|
||
<li>
|
||
libssl loading on FreeBSD 7.2 fixed, thanks to Stian Sletner.
|
||
</li>
|
||
</ul>
|
||
<p>
|
||
2008-xx-yy
|
||
</p>
|
||
<ul>
|
||
<li>
|
||
Support for I/O deadlines (Clozure CL and SBCL).
|
||
</li>
|
||
<li>
|
||
Support for encrypted keys, thanks to Vsevolod Dyomkin.
|
||
</li>
|
||
<li>
|
||
Chained certificates support, thanks to Juhani R<>nkimies.
|
||
</li>
|
||
<li>
|
||
More secure initialization of OpenSSL random number generator.
|
||
</li>
|
||
<li>
|
||
Minor CLISP-specific fixes.
|
||
</li>
|
||
</ul>
|
||
<p>
|
||
2007-xx-yy
|
||
</p>
|
||
<ul>
|
||
<li>
|
||
Fixed windows support, thanks to Matthew Kennedy and Anton Vodonosov.
|
||
</li>
|
||
</ul>
|
||
<p>
|
||
2007-07-07
|
||
</p>
|
||
<ul>
|
||
<li>
|
||
Improved CLISP support, thanks
|
||
to <a
|
||
href="http://web.kepibu.org/code/lisp/cl+ssl/">Pixel
|
||
// pinterface</a>, as well as client certificate support.
|
||
</li>
|
||
<li>
|
||
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>.
|
||
</li>
|
||
</ul>
|
||
<p>
|
||
2007-01-16: CL+SSL is now available under an MIT-style license.
|
||
</p>
|
||
</body>
|
||
</html>
|