Scieneer Common Lisp 1.3.9 online documentation

Secure Socket Layer Library

Introduction

The Secure Socket Layer (SSL) support is an interface to the OpenSSL library and is needed by the HTTP library to support secure web services. The OpenSSL library is not distributed with the Scieneer Common Lisp due to possible export restrictions and is generally included with the operating environment. This SSL interface does no include any cryptographic ciphers and is dependant on the external OpenSSL library for these and thus the strength of security is dependant on the external OpenSSL library.

Initialization

ssl:make-ssl-server-stream fd &key element-type external-format buffering timeout expiration certificate key verify-mode verify-depth ciphers options ssl-context[Function]

Make a new SSL server stream on the given socket fd, returning the new stream upon success, and signaling an appropriate error upon failure. The socket fd is not closed upon a failure, and the caller is expected to ensure the socket is closed if necessary.

:element-type
Indicates the element type to use. Only the character and '(unsigned-byte 8) types are supported.
:external-format
For a character stream this is the external character format to use. The default value is :default for which the value of ext:*default-external-format* is used.
:buffering
Indicates the kind of output buffer flushing to use which may be one of: :none, :line, or the default :full. Line buffering is only applicable to character streams.
:timeout
The number of seconds to wait for an input or output operation. If false, which is the default, then wait forever. When a timeout occurs the sys:io-timeout condition is signaled.
:expiration
The number of seconds before the stream expires. If false, which is the default, then the stream does not expire. When the stream expires the sys:io-timeout condition is signaled until the expiration time is reset.
:ssl-context
The SSL context in which the stream will be created. If not supplied then the ssl:*default-ssl-context* is used, and a default context is created if necessary. See also: ssl:make-ssl-context, and ssl:initialize-ssl-context.

The following SSL options are accepted and override the SSL context defaults:

:certificate
The certificate file to use, in PEM format.
:key
The key file to use. If the key is password protected then the password must have been specified in the SSL global context, see ssl:initialize-ssl-context. If the key file is nil then the certificate file is used.
:verify-mode
One of the following
:none
Do not send a client certificate request.
:request
Send a client certificate request, and check the returned certificate if any. The client is not required to return a certificate.
:require
Send a client certificate request, requiring the client to sent a certificate which is checked.
:verify-depth
The limit up to which depth certificates in a chain are used during the verification procedure. Certificates above the limit are ignored.
:ciphers
A colon separated list of the restricted set of ciphers to use.

ssl:make-ssl-client-stream fd &key element-type external-format buffering timeout expiration certificate key verify-mode verify-depth ciphers options ssl-context[Function]

Make a new SSL client stream on the given socket fd, returning the new stream upon success, and signaling an appropriate error upon failure. The socket fd is not closed upon a failure, and the caller is expected to ensure the socket is closed if necessary.

:element-type
Indicates the element type to use. Only the character and '(unsigned-byte 8) types are supported.
:external-format
For a character stream this is the external character format to use. The default value is :default for which the value of ext:*default-external-format* is used.
:buffering
Indicates the kind of output buffer flushing to use which may be one of: :none, :line, or the default :full. Line buffering is only applicable to character streams.
:timeout
The number of seconds to wait for an input or output operation. If false, which is the default, then wait forever. When a timeout occurs the sys:io-timeout condition is signaled.
:expiration
The number of seconds to before the stream expires. If false, which is the default, then the stream does not expire. When the stream expires the sys:io-timeout condition is signaled until the expiration time is reset.
:ssl-context
The SSL context in which the stream will be created. If not supplied then the ssl:*default-ssl-context* is used, and a default context is created if necessary. See also: ssl:make-ssl-context, and ssl:initialize-ssl-context.

The following SSL options are accepted and override the global SSL context defaults:

:certificate
The certificate file to use, in PEM format.
:key
The key file to use. If the key is password protected then the password must have been specified in the SSL global context, see ssl:initialize-ssl-context. If the key file is nil then the certificate file is used.
:verify-mode
One of the following
:none
The server certificate, if any, is checked but the connection handshake will proceed regardless of the result of the server certificate verification. The verification result may be checked with ssl:ssl-stream-verify-result.
:request
The server certificate, if any, is checked and the handshake is terminated immediately upon a verification failure. A server certificate is not required.
:require
The server certificate is required and is checked and the handshake is terminated immediately upon a verification failure.
:verify-depth
The limit up to which depth certificates in a chain are used during the verification procedure. Certificates above the limit are ignored.
:ciphers
A colon separated list of the restricted set of ciphers to use.

ssl:make-ssl-context &key name method certificate key password verify-mode verify-depth ciphers cafile capath dh-params[Function]

Make and return a new SSL context. The SSL context provides the location of the trusted CA certificates and the key password, and may also provide default values for later operations. A default context will be automatically allocated when needed and does not need to be explicitly initialized unless the trusted CA certificates, or the key password, need to be specified. SSL contexts do not remain valid in a restarted lisp image so new contexts should be created and initialized when an application restarts.

:method
The method may be one of: :sslv2, :sslv3, :tlsv1, or :sslv23, and defaults to :sslv23. See the OpenSSL SSL_CTX_new function for more information.
:name
An optional name may be supplied which is printed if an interactive request is made for a password.
:certificate
The certificate file to use, in PEM format.
:key
The key file to use, and the password if applicable. If the key file is nil then the certificate file is used.
:password
The global password to use for password protected keys. Only a single global password can be specified. If a password is not supplied then it will be prompted for if needed and then stored.
:verify-mode
One of :none, :request, or :require. This affects both the client and server mode, see ssl:make-ssl-server-stream and ssl:make-ssl-client-stream respectively for more information. The default is :none which may be suitable for a server but probably not for a client.
:verify-depth
The limit up to which depth certificates in a chain are used during the verification procedure. Certificates above the limit are ignored. The default depth is one.
:ciphers
A colon separated list of the restricted set of ciphers to use.
:cafile
A file with the trusted CA certificates used for verification purposes.
:capath
The path to the trusted CA certificates directory.
:dh-params
A DH parameters file. If a file is not supplied then internal hard coded parameters are used.

ssl:initialize-ssl-context &key ssl-context certificate key password verify-mode verify-depth ciphers cafile capath dh-params[Function]

Initialize or reinitialize a SSL context. The SSL context provides the location of the trusted CA certificates and the key password, and may also provide default values for later operations. A default context will be automatically allocated when needed and does not need to be explicitly initialized unless the trusted CA certificates, or the key password, need to be specified.

:ssl-context
The SSL context to initialize. The ssl:*default-ssl-context* is used if not supplied, and a default context is created if necessary. See also: ssl:make-ssl-context, and ssl:initialize-ssl-context.
:certificate
The certificate file to use, in PEM format.
:key
The key file to use, and the password if applicable. If the key file is nil then the certificate file is used.
:password
The global password to use for password protected keys. Only a single global password can be specified. If a password is not supplied then it will be prompted for if needed and then stored.
:verify-mode
One of :none, :request, or :require. This affects both the client and server mode, see ssl:make-ssl-server-stream and ssl:make-ssl-client-stream respectively for more information. The default is :none which may be suitable for a server but probably not for a client.
:verify-depth
The limit up to which depth certificates in a chain are used during the verification procedure. Certificates above the limit are ignored. The default depth is one.
:ciphers
A colon separated list of the restricted set of ciphers to use.
:cafile
A file with the trusted CA certificates used for verification purposes.
:capath
The path to the trusted CA certificates directory.
:dh-params
A DH parameters file. If a file is not supplied then internal hard coded parameters are used.

ssl:*default-ssl-context*[Variable]

The default SSL context used by various SSL functions. A default SSL context is automatically created. See also: ssl:make-ssl-context, and ssl:initialize-ssl-context.

ssl:ssl-stream-cipher stream[Function]

Returns the current cipher name and version for the SSL stream.

ssl:ssl-stream-verify-result stream[Function]

Return the stream verify result which will be zero upon success or if a peer certificate was not presented.

ssl:clear-temporary-rsa-keys [Function]

Clear the temporary RSA keys causing new keys to be calculated when needed. These should be cleared periodically, but noted that the memory used is not freed when the keys are cleared.


X509 distinguished names

ssl:ssl-stream-peer-name stream[Function]

Return the stream peer X509 distinguished name as an alist of attribute name strings and values.

ssl:ssl-stream-peer-name-oneline stream[Function]

Return the stream peer X509 distinguished name as a one line string, otherwise return nil. See also ssl:ssl-stream-peer-name.