|Allegro CL version 10.1|
Unrevised from 10.0 to 10.1.
Arguments: socket &key context certificate key certificate-password method verify max-depth ca-file ca-directory ciphers ciphersuites crl-check crl-file prefer-server-cipher-order server-name
You must have the OpenSSL libraries installed for this facility to
work. Note that shared library versions of the OpenSSL libraries
(required by Allegro CL) are not available on all platforms. The SSL
functionality is in the ssl module. To ensure it
is loaded, evaluate
(require :ssl). Calling this function automatically
loads the module.
This function creates and returns a new SSL server socket stream that communicates via SSL via the given socket. Once this function is called and an SSL socket stream is returned, no I/O calls should be done directly to socket. Note that closing the SSL socket stream will result in the original socket file descriptor being closed as well. Therefore, the idiomatic way to establish an SSL server socket stream is:
;; SOCK is already a socket: (setf sock (make-ssl-server-stream sock ...))
Unless ssl-do-handshake is called, the secure connection isn't negotiated until the first byte is sent through the SSL socket stream to the underlying stream (and this will usually occur when the first force-output is done to the SSL socket stream).
When that first write is done a negotiation process is begun that involves reads and writes. This negotiation process will not occur if the SSL socket on the other end of the connection is not sitting waiting for data to arrive. Thus if you create two connected sockets in a single Lisp process, and make one the client and the other the server, and then write to the client side the Lisp will hang since the server side socket isn't being read. You can make this work if you use the Lisp multiprocessing facility (see multiprocessing.htm) to cause the server socket to be read at the same time that the write to the client socket is being done.
The context keyword argument takes an SSL context object as a value. Such objects contain relevant information about the server stream being created. The function make-ssl-server-context create a context suitable for a server stream.
Note that if you supply an SSL context object as the value of context, you can specify values for the arguments method, ciphers, ciphersuites, verify, max-depth, and prefer-server-cipher-order in the call to this function. Doing so causes the associated argument value to be local to the connection being created (i.e. the specified argument value overrides the value in the context object). However, it is an error to specify values for the arguments certificate, key, ca-file, ca-directory, certificate-password, crl-file, and crl-check as they cannot be overridden when a context is provided.
The server-name keyword argument appears in the argument list for this function but is not supported at this time. Do not specify a value for that argument.
If an error occurs, a condition of
excl::ssl-error is signaled. This condition
has slots what (a string indicating what internal operation was being
performed when the error occurred), codes (a ist of numeric OpenSSL
error codes that represented the accumulated errors that resulted in
the final error), strings (a list of the corresponding string forms of
the OpenSSL error codes in the 'codes' slot) and verify-result, and
verify-result-string. The last two will be populated if possible when
an ssl error occurs. If non-nil, this information is included in the
printed representation of the condition. This aids recognizing and
debugging certificate-related SSL errors.
make-ssl-server-stream's keyword arguments are the same as make-ssl-client-stream's. The keyword arguments to make-ssl-server-stream are:
:sslv23: (the default) the server will handle SSLv2, SSLv3, and TLSv1. The highest protocol version that is common between the client and server will be selected. This method allows for best compatibility.
:sslv2: the server will only handle SSLv2. This option is not recommended as SSLv2 has known security issues (such as susceptibility to man In the middle attacks).
:sslv3: the server will only handle SSLv3.
:sslv3+: this is the same as :sslv23 except that, after handshake, if the selected protocol is SSLv2, an error will be generated. This option allows for high handshake compabitility while avoiding communication under the deprecated SSLv2 protocol.
:tlsv1: the server will only handle TLSv1.
:required. Due to the way OpenSSL is implemented, the behavior of peer verification differs for servers and clients. Here we describe the behavior for servers. See make-ssl-client-stream for a discussion of the client behavior.
For details on the cipher list format, see the CIPHER LIST FORMAT section of http://www.openssl.org/docs/apps/ciphers.html.
This argument is not used with TLS 1.3. See the ciphersuites argument below.
nilor unspecified, OpenSSL defaults are used.
nil(the default) for no CRL checking,
tfor CRL checking of the peer's certificate (if provided by the peer), or
:allfor CRL checking of all components of the peer's supplied certificate chain. If this argument is non-
nil, the verify argument must also be non-
nil. If you enable CRL checking, you must supply a proper PEM-encoded CRL, even if it contains zero revocations. If you do not supply a CRL, peer verification will never succeed.
nilor not supplied, defaults to the value of the ca-file argument (if supplied). It is acceptable for CRL to be included amongst other PEM-encoded certificates.
nil. The typical behavior when choosing a cipher during an SSLv3 or TLSv1 handshake is to use the client's preference. If this argument is true (the default is
nil), the server's preference will be used.
See make-ssl-client-stream. See also socket.htm for information on sockets. For information on Secure Sockets, see the section Secure Socket Layer (SSL) in that document.
Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
|Allegro CL version 10.1|
Unrevised from 10.0 to 10.1.