basic TLS/DTLS decorator. More...

#include <tls.hpp>

Inheritance diagram for join::BasicTls< Protocol >:

[legend]

Collaboration diagram for join::BasicTls< Protocol >:

Public Types
using	UnderlyingSocket = typename Protocol::Transport::Socket

using	Mode = typename UnderlyingSocket::Mode

using	Option = typename UnderlyingSocket::Option

using	State = typename UnderlyingSocket::State

using	Endpoint = typename Protocol::Endpoint

using	TimePoint = typename UnderlyingSocket::TimePoint

Public Member Functions
	BasicTls (TlsContext ctx, Mode mode=Mode::NonBlocking) noexcept
	create a TLS decorator with an internally created socket.

	BasicTls (UnderlyingSocket &&socket) noexcept
	create a TLS decorator taking ownership of the given socket, without context.

	BasicTls (UnderlyingSocket &&socket, TlsContext ctx) noexcept
	create a TLS decorator taking ownership of the given socket.

	BasicTls (const BasicTls &other)=delete
	copy constructor.

BasicTls &	operator= (const BasicTls &other)=delete
	copy assignment operator.

	BasicTls (BasicTls &&other) noexcept
	move constructor.

BasicTls &	operator= (BasicTls &&other) noexcept
	move assignment operator.

virtual	~BasicTls ()=default
	destroy the instance.

int	open (const Protocol &protocol=Protocol()) noexcept
	open the underlying socket using the given protocol.

bool	opened () const noexcept
	check if the underlying socket is opened.

int	bind (const Endpoint &ep) noexcept
	assigns the specified endpoint to the underlying socket.

int	bindToDevice (const std::string &dev) noexcept
	assigns the specified device to the underlying socket.

int	connect (const Endpoint &ep) noexcept
	connect the underlying socket to the remote endpoint.

bool	connected () noexcept
	check if the underlying socket is connected.

int	deferHandshake ()
	set the TLS layer up without negotiating immediately.

int	handshake ()
	perform the TLS handshake.

bool	waitHandshake ()
	block until TLS handshake is finished.

bool	waitHandshake (std::chrono::nanoseconds timeout)
	block until TLS handshake is finished, giving up after the given duration.

virtual bool	waitHandshake (TimePoint deadline)
	block until TLS handshake is finished, giving up at the given time point.

bool	encrypted () const noexcept
	check if the stream is encrypted.

int	shutdown () noexcept
	Perform the TLS shutdown.

bool	waitShutdown () noexcept
	block until TLS shutdown is finished.

bool	waitShutdown (std::chrono::nanoseconds timeout) noexcept
	block until TLS shutdown is finished, giving up after the given duration.

bool	waitShutdown (TimePoint deadline) noexcept
	block until TLS shutdown is finished, giving up at the given time point.

int	disconnect () noexcept
	disconnect the underlying socket from the remote endpoint.

void	close () noexcept
	close the socket handle.

bool	waitReadyRead () const noexcept
	block until new data is available for reading.

bool	waitReadyRead (std::chrono::nanoseconds timeout) const noexcept
	block until new data is available for reading, giving up after the given duration.

bool	waitReadyRead (TimePoint deadline) const noexcept
	block until new data is available for reading, giving up at the given time point.

ssize_t	read (char *buf, size_t len) noexcept
	read data from the TLS stream.

int	readExactly (char *data, size_t size)
	read data until size is reached or an error occurred.

int	readExactly (char *data, size_t size, std::chrono::nanoseconds timeout)
	read data until size is reached, an error occurred or the given duration elapsed.

int	readExactly (char *data, size_t size, TimePoint deadline)
	read data until size is reached, an error occurred or the deadline expired.

bool	waitReadyWrite () const noexcept
	block until at least one byte can be written on the socket.

bool	waitReadyWrite (std::chrono::nanoseconds timeout) const noexcept
	block until at least one byte can be written on the socket, giving up after the given duration.

bool	waitReadyWrite (TimePoint deadline) const noexcept
	block until at least one byte can be written, giving up at the given time point.

ssize_t	write (const char *buf, size_t len) noexcept
	write data to the TLS stream.

int	writeExactly (const char *data, size_t size)
	write data until size is reached or an error occurred.

int	writeExactly (const char *data, size_t size, std::chrono::nanoseconds timeout)
	write data until size is reached, an error occurred or the given duration elapsed.

int	writeExactly (const char *data, size_t size, TimePoint deadline)
	write data until size is reached, an error occurred or the deadline expired.

void	setMode (Mode mode) noexcept
	set the mode of the underlying socket.

int	setOption (Option opt, int val) noexcept
	set an option for the underlying socket.

int	handle () const noexcept
	get the underlying socket handle.

int	family () const noexcept
	get the underlying socket address family.

int	type () const noexcept
	get the underlying socket type.

int	protocol () const noexcept
	get the underlying protocol.

int	mtu () const noexcept
	get the maximum transmission unit.

Endpoint	localEndpoint () const noexcept
	get the local endpoint.

Endpoint	remoteEndpoint () const
	get the remote endpoint.

Protected Member Functions
int	handleTlsError (int result) noexcept
	handle TLS error.

void	infoCallback (int where, int ret) const noexcept
	SSL state info callback.

int	verifyCallback (int preverified, X509_STORE_CTX *context) noexcept
	verify peer certificate.

int	verifyCert (X509_STORE_CTX *context) const
	verify certificate validity.

bool	checkHostname (X509 *certificate) const noexcept
	check certificate hostname against remote endpoint.

Static Protected Member Functions
static void	infoWrapper (const SSL *ssl, int where, int ret) noexcept
	c style info callback wrapper.

static int	verifyWrapper (int preverified, X509_STORE_CTX *x509Ctx) noexcept
	c style verify callback wrapper.

Protected Attributes
UnderlyingSocket	_socket
	verify certificate revocation using CRL.

TlsContext	_ctx
	TLS context.

SslPtr	_ssl
	TLS handle.

Detailed Description

template<class Protocol>
class join::BasicTls< Protocol >

basic TLS/DTLS decorator.

Member Typedef Documentation

◆ Endpoint

template<class Protocol >

using join::BasicTls< Protocol >::Endpoint = typename Protocol::Endpoint

◆ Mode

template<class Protocol >

using join::BasicTls< Protocol >::Mode = typename UnderlyingSocket::Mode

◆ Option

template<class Protocol >

using join::BasicTls< Protocol >::Option = typename UnderlyingSocket::Option

◆ State

template<class Protocol >

using join::BasicTls< Protocol >::State = typename UnderlyingSocket::State

◆ TimePoint

template<class Protocol >

using join::BasicTls< Protocol >::TimePoint = typename UnderlyingSocket::TimePoint

◆ UnderlyingSocket

template<class Protocol >

using join::BasicTls< Protocol >::UnderlyingSocket = typename Protocol::Transport::Socket

Constructor & Destructor Documentation

◆ BasicTls() [1/5]

template<class Protocol >

join::BasicTls< Protocol >::BasicTls	(	TlsContext	ctx,
		Mode	mode = Mode::NonBlocking )

inlineexplicitnoexcept

create a TLS decorator with an internally created socket.

Parameters

ctx	TLS context.
mode	blocking mode.

◆ BasicTls() [2/5]

template<class Protocol >

join::BasicTls< Protocol >::BasicTls ( UnderlyingSocket && socket )

inlineexplicitnoexcept

create a TLS decorator taking ownership of the given socket, without context.

Parameters

socket underlying socket.

◆ BasicTls() [3/5]

template<class Protocol >

join::BasicTls< Protocol >::BasicTls	(	UnderlyingSocket &&	socket,
		TlsContext	ctx )

inlinenoexcept

create a TLS decorator taking ownership of the given socket.

Parameters

socket	underlying socket.
ctx	TLS context.

◆ BasicTls() [4/5]

template<class Protocol >

join::BasicTls< Protocol >::BasicTls ( const BasicTls< Protocol > & other )

delete

copy constructor.

Parameters

other other object to copy.

◆ BasicTls() [5/5]

template<class Protocol >

join::BasicTls< Protocol >::BasicTls ( BasicTls< Protocol > && other )

inlinenoexcept

move constructor.

Parameters

other other object to move.

◆ ~BasicTls()

template<class Protocol >

virtual join::BasicTls< Protocol >::~BasicTls ( )

virtualdefault

destroy the instance.

Member Function Documentation

◆ bind()

template<class Protocol >

int join::BasicTls< Protocol >::bind ( const Endpoint & ep )

inlinenoexcept

assigns the specified endpoint to the underlying socket.

Parameters

ep	endpoint to assign to the underlying socket.

Returns: 0 on success, -1 on failure.

◆ bindToDevice()

template<class Protocol >

int join::BasicTls< Protocol >::bindToDevice ( const std::string & dev )

inlinenoexcept

assigns the specified device to the underlying socket.

Parameters

dev	device name.

Returns: 0 on success, -1 on failure.

◆ checkHostname()

template<class Protocol >

bool join::BasicTls< Protocol >::checkHostname ( X509 * certificate ) const

inlineprotectednoexcept

check certificate hostname against remote endpoint.

Parameters

certificate X509 certificate.

Returns: true if hostname matches.

◆ close()

template<class Protocol >

void join::BasicTls< Protocol >::close ( )

inlinenoexcept

close the socket handle.

◆ connect()

template<class Protocol >

int join::BasicTls< Protocol >::connect ( const Endpoint & ep )

inlinenoexcept

connect the underlying socket to the remote endpoint.

Parameters

ep	endpoint to connect to.

Returns: 0 on success, -1 on failure.

Note: transport connection only, the TLS handshake is performed separately.

◆ connected()

template<class Protocol >

bool join::BasicTls< Protocol >::connected ( )

inlinenoexcept

check if the underlying socket is connected.

Returns: true if connected.

◆ deferHandshake()

template<class Protocol >

int join::BasicTls< Protocol >::deferHandshake ( )

inline

set the TLS layer up without negotiating immediately.

Returns: 0 on success, -1 on failure.

◆ disconnect()

template<class Protocol >

int join::BasicTls< Protocol >::disconnect ( )

inlinenoexcept

disconnect the underlying socket from the remote endpoint.

Returns: 0 on success, -1 on failure.

◆ encrypted()

template<class Protocol >

bool join::BasicTls< Protocol >::encrypted ( ) const

inlinenoexcept

check if the stream is encrypted.

Returns: true if encrypted.

◆ family()

template<class Protocol >

int join::BasicTls< Protocol >::family ( ) const

inlinenoexcept

get the underlying socket address family.

Returns: socket address family.

◆ handle()

template<class Protocol >

int join::BasicTls< Protocol >::handle ( ) const

inlinenoexcept

get the underlying socket handle.

Returns: socket handle.

◆ handleTlsError()

template<class Protocol >

int join::BasicTls< Protocol >::handleTlsError ( int result )

inlineprotectednoexcept

handle TLS error.

Parameters

result result returned by a previous call of the openssl API.

Returns: -1 is always returned.

◆ handshake()

template<class Protocol >

int join::BasicTls< Protocol >::handshake ( )

inline

perform the TLS handshake.

Returns: 0 on success, -1 on failure.

◆ infoCallback()

template<class Protocol >

void join::BasicTls< Protocol >::infoCallback	(	int	where,
		int	ret ) const

inlineprotectednoexcept

SSL state info callback.

Parameters

where	context flags.
ret	error condition.

◆ infoWrapper()

template<class Protocol >

static void join::BasicTls< Protocol >::infoWrapper	(	const SSL *	ssl,
		int	where,
		int	ret )

inlinestaticprotectednoexcept

c style info callback wrapper.

Parameters

ssl	SSL object.
where	context flags.
ret	error condition.

◆ localEndpoint()

template<class Protocol >

Endpoint join::BasicTls< Protocol >::localEndpoint ( ) const

inlinenoexcept

get the local endpoint.

Returns: local endpoint.

◆ mtu()

template<class Protocol >

int join::BasicTls< Protocol >::mtu ( ) const

inlinenoexcept

get the maximum transmission unit.

Returns: MTU.

◆ open()

template<class Protocol >

int join::BasicTls< Protocol >::open ( const Protocol & protocol = Protocol () )

inlinenoexcept

open the underlying socket using the given protocol.

Parameters

protocol protocol to use.

Returns: 0 on success, -1 on failure.

◆ opened()

template<class Protocol >

bool join::BasicTls< Protocol >::opened ( ) const

inlinenoexcept

check if the underlying socket is opened.

Returns: true if opened.

◆ operator=() [1/2]

template<class Protocol >

BasicTls & join::BasicTls< Protocol >::operator= ( BasicTls< Protocol > && other )

inlinenoexcept

move assignment operator.

Parameters

other other object to assign.

Returns: assigned object.

◆ operator=() [2/2]

template<class Protocol >

BasicTls & join::BasicTls< Protocol >::operator= ( const BasicTls< Protocol > & other )

delete

copy assignment operator.

Parameters

other other object to assign.

Returns: assigned object.

◆ protocol()

template<class Protocol >

int join::BasicTls< Protocol >::protocol ( ) const

inlinenoexcept

get the underlying protocol.

Returns: protocol.

◆ read()

template<class Protocol >

ssize_t join::BasicTls< Protocol >::read	(	char *	buf,
		size_t	len )

inlinenoexcept

read data from the TLS stream.

Parameters

buf	buffer to read into.
len	maximum number of bytes to read.

Returns: number of bytes read on success, -1 on failure.

◆ readExactly() [1/3]

template<class Protocol >

int join::BasicTls< Protocol >::readExactly	(	char *	data,
		size_t	size )

inline

read data until size is reached or an error occurred.

Parameters

data	buffer used to store the data received.
size	number of bytes to read.

Returns: 0 on success, -1 on failure.

◆ readExactly() [2/3]

template<class Protocol >

int join::BasicTls< Protocol >::readExactly	(	char *	data,
		size_t	size,
		std::chrono::nanoseconds	timeout )

inline

read data until size is reached, an error occurred or the given duration elapsed.

Parameters

data	buffer used to store the data received.
size	number of bytes to read.
timeout	maximum time granted to the whole read.

Returns: 0 on success, -1 on failure.

◆ readExactly() [3/3]

template<class Protocol >

int join::BasicTls< Protocol >::readExactly	(	char *	data,
		size_t	size,
		TimePoint	deadline )

inline

read data until size is reached, an error occurred or the deadline expired.

Parameters

data	buffer used to store the data received.
size	number of bytes to read.
deadline	time point at which to give up, max to wait indefinitely.

Returns: 0 on success, -1 on failure.

◆ remoteEndpoint()

template<class Protocol >

Endpoint join::BasicTls< Protocol >::remoteEndpoint ( ) const

inline

get the remote endpoint.

Returns: remote endpoint.

Note: returns by value, copying the endpoint hostname may allocate.

◆ setMode()

template<class Protocol >

void join::BasicTls< Protocol >::setMode ( Mode mode )

inlinenoexcept

set the mode of the underlying socket.

Parameters

mode	socket mode.

◆ setOption()

template<class Protocol >

int join::BasicTls< Protocol >::setOption	(	Option	opt,
		int	val )

inlinenoexcept

set an option for the underlying socket.

Parameters

opt	socket option.
val	option value.

Returns: 0 on success, -1 on failure.

◆ shutdown()

template<class Protocol >

int join::BasicTls< Protocol >::shutdown ( )

inlinenoexcept

Perform the TLS shutdown.

Returns: 0 on success, -1 on failure.

◆ type()

template<class Protocol >

int join::BasicTls< Protocol >::type ( ) const

inlinenoexcept

get the underlying socket type.

Returns: socket type.

◆ verifyCallback()

template<class Protocol >

int join::BasicTls< Protocol >::verifyCallback	(	int	preverified,
		X509_STORE_CTX *	context )

inlineprotectednoexcept

verify peer certificate.

Parameters

preverified	pre-verification status.
context	X509 store context.

Returns: 1 if verified, 0 otherwise.

◆ verifyCert()

template<class Protocol >

int join::BasicTls< Protocol >::verifyCert ( X509_STORE_CTX * context ) const

inlineprotected

verify certificate validity.

Parameters

context pointer to the complete context used for the certificate chain verification.

Returns: when verified successfully, the callback should return 1, 0 otherwise.

◆ verifyWrapper()

template<class Protocol >

static int join::BasicTls< Protocol >::verifyWrapper	(	int	preverified,
		X509_STORE_CTX *	x509Ctx )

inlinestaticprotectednoexcept

c style verify callback wrapper.

Parameters

preverified	pre-verification status.
x509Ctx	X509 store context.

Returns: 1 if verified, 0 otherwise.

◆ waitHandshake() [1/3]

template<class Protocol >

bool join::BasicTls< Protocol >::waitHandshake ( )

inline

block until TLS handshake is finished.

Returns: true if TLS handshake is finished.

◆ waitHandshake() [2/3]

template<class Protocol >

bool join::BasicTls< Protocol >::waitHandshake ( std::chrono::nanoseconds timeout )

inline

block until TLS handshake is finished, giving up after the given duration.

Parameters

timeout maximum time granted to the whole handshake.

Returns: true if TLS handshake is finished.

◆ waitHandshake() [3/3]

template<class Protocol >

virtual bool join::BasicTls< Protocol >::waitHandshake ( TimePoint deadline )

inlinevirtual

block until TLS handshake is finished, giving up at the given time point.

Parameters

deadline time point at which to give up, max to wait indefinitely.

Returns: true if TLS handshake is finished.

Reimplemented in join::BasicTlsWrapper< Protocol >.

◆ waitReadyRead() [1/3]

template<class Protocol >

bool join::BasicTls< Protocol >::waitReadyRead ( ) const

inlinenoexcept

block until new data is available for reading.

Returns: true if there is new data available for reading, false otherwise.

◆ waitReadyRead() [2/3]

template<class Protocol >

bool join::BasicTls< Protocol >::waitReadyRead ( std::chrono::nanoseconds timeout ) const

inlinenoexcept

block until new data is available for reading, giving up after the given duration.

Parameters

timeout maximum time to wait.

Returns: true if there is new data available for reading, false otherwise.

◆ waitReadyRead() [3/3]

template<class Protocol >

bool join::BasicTls< Protocol >::waitReadyRead ( TimePoint deadline ) const

inlinenoexcept

block until new data is available for reading, giving up at the given time point.

Parameters

deadline time point at which to give up, max to wait indefinitely.

Returns: true if there is new data available for reading, false otherwise.

◆ waitReadyWrite() [1/3]

template<class Protocol >

bool join::BasicTls< Protocol >::waitReadyWrite ( ) const

inlinenoexcept

block until at least one byte can be written on the socket.

Returns: true if data can be written on the socket, false otherwise.

◆ waitReadyWrite() [2/3]

template<class Protocol >

bool join::BasicTls< Protocol >::waitReadyWrite ( std::chrono::nanoseconds timeout ) const

inlinenoexcept

block until at least one byte can be written on the socket, giving up after the given duration.

Parameters

timeout maximum time to wait.

Returns: true if data can be written on the socket, false otherwise.

◆ waitReadyWrite() [3/3]

template<class Protocol >

bool join::BasicTls< Protocol >::waitReadyWrite ( TimePoint deadline ) const

inlinenoexcept

block until at least one byte can be written, giving up at the given time point.

Parameters

deadline time point at which to give up, max to wait indefinitely.

Returns: true if data can be written on the socket, false otherwise.

◆ waitShutdown() [1/3]

template<class Protocol >

bool join::BasicTls< Protocol >::waitShutdown ( )

inlinenoexcept

block until TLS shutdown is finished.

Returns: true if TLS shutdown is finished.

◆ waitShutdown() [2/3]

template<class Protocol >

bool join::BasicTls< Protocol >::waitShutdown ( std::chrono::nanoseconds timeout )

inlinenoexcept

block until TLS shutdown is finished, giving up after the given duration.

Parameters

timeout maximum time granted to the whole shutdown.

Returns: true if TLS shutdown is finished.

◆ waitShutdown() [3/3]

template<class Protocol >

bool join::BasicTls< Protocol >::waitShutdown ( TimePoint deadline )

inlinenoexcept

block until TLS shutdown is finished, giving up at the given time point.

Parameters

deadline time point at which to give up, max to wait indefinitely.

Returns: true if TLS shutdown is finished.

◆ write()

template<class Protocol >

ssize_t join::BasicTls< Protocol >::write	(	const char *	buf,
		size_t	len )

inlinenoexcept

write data to the TLS stream.

Parameters

buf	buffer to write from.
len	number of bytes to write.

Returns: number of bytes written on success, -1 on failure.

◆ writeExactly() [1/3]

template<class Protocol >

int join::BasicTls< Protocol >::writeExactly	(	const char *	data,
		size_t	size )

inline

write data until size is reached or an error occurred.

Parameters

data	data buffer to send.
size	number of bytes to write.

Returns: 0 on success, -1 on failure.

◆ writeExactly() [2/3]

template<class Protocol >

int join::BasicTls< Protocol >::writeExactly	(	const char *	data,
		size_t	size,
		std::chrono::nanoseconds	timeout )

inline

write data until size is reached, an error occurred or the given duration elapsed.

Parameters

data	data buffer to send.
size	number of bytes to write.
timeout	maximum time granted to the whole write.

Returns: 0 on success, -1 on failure.

◆ writeExactly() [3/3]

template<class Protocol >

int join::BasicTls< Protocol >::writeExactly	(	const char *	data,
		size_t	size,
		TimePoint	deadline )

inline

write data until size is reached, an error occurred or the deadline expired.

Parameters

data	data buffer to send.
size	number of bytes to write.
deadline	time point at which to give up, max to wait indefinitely.

Returns: 0 on success, -1 on failure.

Member Data Documentation

◆ _ctx

template<class Protocol >

TlsContext join::BasicTls< Protocol >::_ctx

protected

TLS context.

◆ _socket

template<class Protocol >

UnderlyingSocket join::BasicTls< Protocol >::_socket

protected

verify certificate revocation using CRL.

Parameters

context pointer to the complete context used for the certificate chain verification.

Returns: when verified successfully, the callback should return 1, 0 otherwise.

verify certificate revocation using OCSP.

Parameters

context pointer to the complete context used for the certificate chain verification.

Returns: when verified successfully, the callback should return 1, 0 otherwise. underlying socket.

◆ _ssl

template<class Protocol >

SslPtr join::BasicTls< Protocol >::_ssl

protected

TLS handle.

The documentation for this class was generated from the following file:

crypto/include/join/tls.hpp

Public Types

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ Endpoint

◆ Mode

◆ Option

◆ State

◆ TimePoint

◆ UnderlyingSocket

Constructor & Destructor Documentation

◆ BasicTls() [1/5]

◆ BasicTls() [2/5]

◆ BasicTls() [3/5]

◆ BasicTls() [4/5]

◆ BasicTls() [5/5]

◆ ~BasicTls()

Member Function Documentation

◆ bind()

◆ bindToDevice()

◆ checkHostname()

◆ close()

◆ connect()

◆ connected()

◆ deferHandshake()

◆ disconnect()

◆ encrypted()

◆ family()

◆ handle()

◆ handleTlsError()

◆ handshake()

◆ infoCallback()

◆ infoWrapper()

◆ localEndpoint()

◆ mtu()

◆ open()

◆ opened()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ protocol()

◆ read()

◆ readExactly() [1/3]

◆ readExactly() [2/3]

◆ readExactly() [3/3]

◆ remoteEndpoint()

◆ setMode()

◆ setOption()

◆ shutdown()

◆ type()

◆ verifyCallback()

◆ verifyCert()

◆ verifyWrapper()

◆ waitHandshake() [1/3]

◆ waitHandshake() [2/3]

◆ waitHandshake() [3/3]

◆ waitReadyRead() [1/3]

◆ waitReadyRead() [2/3]

◆ waitReadyRead() [3/3]

◆ waitReadyWrite() [1/3]

◆ waitReadyWrite() [2/3]

◆ waitReadyWrite() [3/3]

◆ waitShutdown() [1/3]

◆ waitShutdown() [2/3]

◆ waitShutdown() [3/3]

◆ write()

◆ writeExactly() [1/3]

◆ writeExactly() [2/3]

◆ writeExactly() [3/3]

Member Data Documentation

◆ _ctx

◆ _socket

◆ _ssl