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

A socket-stream.

ssl-ctx

A symbol or a foreign pointer.

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