All Manuals > LispWorks® User Guide and Reference Manual > 32 The COMM Package

attach-ssl Function

Summary

Attaches SSL to a socket stream.

Package

comm

Signature

attach-ssl socket-stream &key ssl-ctx ssl-side ctx-configure-callback ssl-configure-callback handshake-timeout tlsext-host-name => ssl

Arguments
socket-stream
ssl-ctx
A symbol, a foreign pointer or a ssl-abstract-context.
ssl-side
One of the keywords :client, :server or :both.
ctx-configure-callback
A function designator or nil. The default value is nil.
ssl-configure-callback
A function designator or nil. The default value is nil.
handshake-timeout
A real or nil (the default).
tlsext-host-name
A string or nil.
Values
ssl
A foreign pointer of type ssl-pointer.
Description

The function attach-ssl attaches SSL to the socket-stream socket-stream.

The allowed values and meaning of the keyword arguments are as described for socket-stream.

Note that attach-ssl is used by:

(make-instance 'comm:socket-stream :ssl-ctx ...)

and by:

(comm:open-tcp-stream ... :ssl-ctx ...)

but you can also call it explicitly.

Before starting to create objects, attach-ssl ensures the SSL library (by calling ensure-ssl) and calls do-rand-seed to seed the Pseudo Random Number Generator (PRNG), so normally you do not need to worry about these.

ssl-side, ssl-ctx, ctx-configure-callback, ssl-configure-callback and handshake-timeout are interpreted as described in 25.8.6 Keyword arguments for use with SSL. After this, SSL_set_fd is used to attach the SSL to the socket and this is recorded in the socket stream.

The default value of ssl-ctx is t and the default value of ssl-side is :server.

If tlsext-host-name is non-nil, then the SNI extension in the SSL connection is set to its value.

When a socket-stream is closed, detach-ssl is called with :retry-count nil, which, if the stream is attached to SSL, calls SSL_shutdown and then frees the object (or objects) that were automatically allocated.

If SSL is already attached to socket-stream then attach-ssl signals an error.

See also

detach-ssl
create-ssl-client-context
create-ssl-server-context
25 TCP and UDP socket communication and SSL


LispWorks® User Guide and Reference Manual - 01 Dec 2021 19:30:26