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

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.

If ssl-ctx is a symbol, it creates the SSL_CTX and calls ctx-configure-callback if this is non-nil. If ssl-ctx is not a ssl-pointer, it creates the SSL object, calls ssl-configure-callback if this is non-nil, and sets the ACCEPT/CONNECT state if the value of ssl-side is not :both. Then it uses SSL_set_fd to attach the SSL to the socket, and records this in the socket stream. It returns the SSL.

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

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