attach-ssl

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`⇩	A 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.