create-ssl-socket-stream

create-ssl-socket-stream Function

Summary

Create a socket-stream from a socket handle.

Package

comm

Signature

create-ssl-socket-stream socket ssl-ctx &rest initargs &key errorp stream-class => stream-or-nil, maybe-condition

Arguments

`socket`⇩	A socket handle.
`ssl-ctx`⇩	A SSL context specifier or `nil`.
`initargs`⇩	Initargs for socket-stream.
`errorp`⇩	A boolean, default to `nil`.
`stream-class`⇩	A symbol or a class.

Values

`stream-or-nil`⇩	A socket-stream or `nil`.
`maybe-condition`	`nil` or a condition.

Description

The function create-ssl-socket-stream is a simple way to create a socket-stream with SSL from a socket handle. Its main purpose is to be used as part of the function that is specified by function in start-up-server, but it can be used with other socket handles.

socket must be a TCP socket handle that is open for communications.

ssl-ctx specifies the SSL configuration. If ssl-ctx is nil, then the socket-stream is created without SSL. Otherwise ssl-ctx must be a valid SSL context specifier as described for :ssl-ctx keyword in 25.8.6 Keyword arguments for use with SSL.

stream-class must be a class, or a symbol that names a class. The class must be a subclass of socket-stream. stream-class defaults to socket-stream.

initargs is used to supply valid initargs for the new instance of stream-class, with the following modifications:

The :ssl-ctx initarg is forced to have value ssl-ctx.
If :direction defaults to :io if omitted from initargs.
If :element-type defaults to base-char if omitted from initargs.
The :errorp and :stream-class arguments are removed.

create-ssl-socket-stream returns an instance of stream-class made by calling make-instance with the modified initargs if successful. If an error of type socket-error (which is most likely to be some ssl-condition) is signaled when the making the instance of stream-class and errorp is nil (the default), then create-ssl-socket-stream returns nil and the condition as the second value. When errorp is non-nil or an error that is not of type socket-error is signaled, then the function error is called.

create-ssl-socket-stream takes ownership of socket. If successful, socket will be closed when stream-or-nil is closed. On failure, create-ssl-socket-stream closes the socket on exit (in a cleanup-form of an unwind-protect).

Notes

The main advantage of using create-ssl-socket-stream over using make-instance with socket-stream is the error handling and closing of socket on error. If you use make-instance, you need to deal with these issues in your own code.

Examples

For an example of using create-ssl-socket-stream, see:

(example-edit-file "ssl/ssl-server")