make-ssl-server-stream

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

A patch released in April, 2014, added the context keyword argument to this function.

This function is not available in all versions. Generally, you must have a Professional 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.

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, 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.

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.

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:

• method keyword argument allows control over the SSL protocol handshake process. Supported SSL protocols are SSLv2, SSLv3, and TLSv1, from oldest to newest. The method keyword argument can be:
  • :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.
• certificate names a file which contains one or more PEM-encoded certificates. The first (or only) certificate in the file will be used to identify the client (in the case of make-ssl-client-stream) or server (in the case of make-ssl-server-stream). Optionally, subsequent entries in the file may be used to supply intermediate CA certificates (also known as a certificate chain).
• The key argument is a string or pathname naming a file containing the private RSA key corresponding the the public key in the certificate. The file must be in PEM format. The key can be stored in an encrypted form which requires a pass phrase to read, but in that case the certificate-password must also be specified. If the key is stored in the certificate file, then you needn't specify the key argument.
• The certificate-password argument, if specified, should be a string. If the private key stored with the certificate inside the file named by the certificate argument is encrypted, then this value is used as the key to decrypt it.
• verify can be nil, :optional, or :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.
  • :verify nil means that the server will not ask the client to supply a certificate and will not do automatic verification if the client supplies a certificate anyway. If the client does provide a certificate, manual verification can be done using get-ssl-peer-certificate and get-ssl-verify-result.
  • :verify :optional means that the client will be asked to supply a certificate during SSL handshake. The certificate (if supplied) will be automatically verified during SSL handshake. If verification fails, an error will be generated during SSL handshake.
  • :verify :required means that the client will be asked to supply a certificate during SSL handshake. The client certificate will be automatically verified during SSL handshake. If the client does not supply a certificate or if verification of the supplied certificate fails, an error will be generated during SSL handshake.
• maxdepth must be an integer (which defaults to 10) which indicates the maximum allowable depth of the certificate verification chain. If the chain exceeds this depth, an error will be generated during SSL handshake.
• ca-file specifies the name of a file containing a series of trusted PEM-encoded Intermediate CA or Root CA certificates that will be used during peer certificate verification. Keep in mind that, when using on an SSL server, the subject name information for each of these certificates is supplied to the peer during SSL handshake, so you may want to keep the number of certificates listed in the file to a minimum. A file containing certificates of well-known root CAs can be found in [acl directory]/examples/ssl/ca-bundle.crt.
• ca-directory specifies the name of a directory containing a series of trusted Intermediate CA or Root CA certificate files that will be used during peer certificate verification. Each file in the directory should contain one certificate. The files should be named based on the hash value of the certificate subject name. If more than one certificate with the same hash value exists, the extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search is performed in the ordering of the extension number, regardless of other properties of the certificates. Use the c_rehash (available via standard OpenSSL distributions) utility to create the necessary links.
• ciphers: if the ciphers keyword argument is supplied, it must be a string which specifies an OpenSSL cipher list. This list determines which ciphers the SSL server will support. The strongest common entry from this list and the list supplied by the client during handshake will be used. If there is no entry in common, SSL handshake will fail and an error will be generated.

  For details on the cipher list format, see the CIPHER LIST FORMAT section of http://www.openssl.org/docs/apps/ciphers.html.

• crl-check: this argument controls certificate revocation list (CRL) checking. Its value may be nil (the default) for no CRL checking, t for CRL checking of the peer's certificate (if provided by the peer), or :all for 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.
• crl-file: this argument specifies the location of a PEM-encoded CRL file. If nil or 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.
• prefer-server-cipher-order: the value should be true or 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-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
The object described on this page has been modified in the 9.0 release; see the Release Notes.
Created 2019.8.20.