FunctionPackage: socketToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 9.0
Object described on page has changed in 9.0.
8.2 version


Arguments: socket &key certificate key certificate-password method verify max-depth ca-file ca-directory ciphers crl-check crl-file prefer-server-cipher-order

This function is not available in all versions. Generally, you must have an Enterprise license to use this function. Also, 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.

See the example file server.pem in [Allegro directory]/examples/ssl/.

If the server side of an SSL connection sends data before it receives data from the client, the data will not go through until the SSL handshake (which is initiated by the client) has completed.

The keyword arguments

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:

The deprecated other-certificates argument

make-ssl-server-stream also accepts the now deprecated other-certificates keyword argument, but a warning is signaled if a value is specified for it. (Note we do not list this keyword argument in the argument list.) The value of other-certificates should be a string naming a file of other certificates (in PEM format) that are needed to establish a trust hierarchy reaching up to a certificate that is implicitly trusted by the browser. If the certificate was obtained from a well known root certificate authority then you won't need to specify anything for this argument. The certificate keyword argument, which previously expected only the primary certificate as a value now loads a whole certificate chain if the file specified as its value has multiple certificates in it and so there is no need for an other-certificates argument.

If an error occurs, a condition of type 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.

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-2012, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 9.0. The object described on this page has been modified in the 9.0 release; see the Release Notes.
Created 2010.1.21.

Allegro CL version 9.0
Object described on page has changed in 9.0.
8.2 version