basic TLS socket class. More...

#include <socket.hpp>

Inheritance diagram for join::BasicTlsSocket< Protocol >:

[legend]

Collaboration diagram for join::BasicTlsSocket< Protocol >:

[legend]

Public Types
using	Ptr = std::unique_ptr <BasicTlsSocket <Protocol>>

using	Mode = typename BasicStreamSocket <Protocol>::Mode

using	Option = typename BasicStreamSocket <Protocol>::Option

using	State = typename BasicStreamSocket <Protocol>::State

using	Endpoint = typename Protocol::Endpoint

Public Types inherited from join::BasicStreamSocket< Protocol >
using	Ptr = std::unique_ptr <BasicStreamSocket <Protocol>>

using	Mode = typename BasicDatagramSocket <Protocol>::Mode

using	Option = typename BasicDatagramSocket <Protocol>::Option

using	State = typename BasicDatagramSocket <Protocol>::State

using	Endpoint = typename Protocol::Endpoint

Public Types inherited from join::BasicDatagramSocket< Protocol >
using	Ptr = std::unique_ptr <BasicDatagramSocket <Protocol>>

using	Mode = typename BasicSocket <Protocol>::Mode

using	Option = typename BasicSocket <Protocol>::Option

using	State = typename BasicSocket <Protocol>::State

using	Endpoint = typename Protocol::Endpoint

Public Types inherited from join::BasicSocket< Protocol >
enum	Mode { Blocking , NonBlocking }
	socket modes. More...

enum	Option { NoDelay , KeepAlive , KeepIdle , KeepIntvl , KeepCount , SndBuffer , RcvBuffer , TimeStamp , ReuseAddr , ReusePort , Broadcast , Ttl , MulticastLoop , MulticastTtl , PathMtuDiscover , RcvError , AuxData }
	socket options. More...

enum	State { Connecting , Connected , Disconnecting , Disconnected , Closed }
	socket states. More...

using	Ptr = std::unique_ptr <BasicSocket <Protocol>>

using	Endpoint = typename Protocol::Endpoint

Public Member Functions
	BasicTlsSocket ()
	default constructor.

	BasicTlsSocket (Mode mode)
	create instance specifying the mode.

	BasicTlsSocket (join::SslCtxPtr tlsContext)
	create instance specifying TLS context.

	BasicTlsSocket (Mode mode, join::SslCtxPtr tlsContext)
	Create socket instance specifying the socket mode and TLS context.

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

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

	BasicTlsSocket (BasicTlsSocket &&other)
	move constructor.

BasicTlsSocket &	operator= (BasicTlsSocket &&other)
	move assignment operator.

virtual	~BasicTlsSocket ()=default
	destroy the instance.

int	connectEncrypted (const Endpoint &endpoint)
	make an encrypted connection to the given endpoint.

int	startEncryption ()
	start socket encryption (perform TLS handshake).

bool	waitEncrypted (int timeout=0)
	wait until TLS handshake is performed or timeout occur (non blocking socket).

virtual int	disconnect () override
	shutdown the connection.

virtual void	close () noexcept override
	close the socket handle.

virtual bool	waitReadyRead (int timeout=0) const noexcept override
	block until new data is available for reading.

virtual int	canRead () const noexcept override
	get the number of readable bytes.

virtual int	read (char *data, unsigned long maxSize) noexcept override
	read data on the socket.

virtual bool	waitReadyWrite (int timeout=0) const noexcept override
	block until until at least one byte can be written on the socket.

virtual int	write (const char *data, unsigned long maxSize) noexcept override
	write data on the socket.

virtual bool	encrypted () const noexcept override
	check if the socket is secure.

int	setCertificate (const std::string &cert, const std::string &key="")
	set the certificate and the private key.

int	setCaPath (const std::string &caPath)
	set the location of the trusted CA certificates.

int	setCaFile (const std::string &caFile)
	set the location of the trusted CA certificate file.

void	setVerify (bool verify, int depth=-1)
	Enable/Disable the verification of the peer certificate.

int	setCipher (const std::string &cipher)
	set the cipher list (TLSv1.2 and below).

int	setCipher_1_3 (const std::string &cipher)
	set the cipher list (TLSv1.3).

Public Member Functions inherited from join::BasicStreamSocket< Protocol >
	BasicStreamSocket ()
	default constructor.

	BasicStreamSocket (Mode mode)
	create instance specifying the mode.

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

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

	BasicStreamSocket (BasicStreamSocket &&other)
	move constructor.

BasicStreamSocket &	operator= (BasicStreamSocket &&other)
	move assignment operator.

virtual	~BasicStreamSocket ()=default
	destroy the instance.

virtual bool	waitConnected (int timeout=0)
	block until connected.

virtual bool	waitDisconnected (int timeout=0)
	wait until the connection as been shut down.

int	readExactly (char *data, unsigned long size, int timeout=0)
	read data until size is reached or an error occurred.

int	readExactly (std::string &data, unsigned long size, int timeout=0)
	read data until size is reached or an error occurred.

int	writeExactly (const char *data, unsigned long size, int timeout=0)
	write data until size is reached or an error occurred.

virtual int	setOption (Option option, int value) noexcept override
	set the given option to the given value.

virtual bool	connecting () const noexcept
	check if the socket is connecting.

virtual bool	connected () noexcept override
	check if the socket is connected.

Public Member Functions inherited from join::BasicDatagramSocket< Protocol >
	BasicDatagramSocket (int ttl=60)
	Default constructor.

	BasicDatagramSocket (Mode mode, int ttl=60)
	Create instance specifying the mode.

	BasicDatagramSocket (const BasicDatagramSocket &other)=delete
	Copy constructor.

BasicDatagramSocket &	operator= (const BasicDatagramSocket &other)=delete
	Copy assignment operator.

	BasicDatagramSocket (BasicDatagramSocket &&other)
	Move constructor.

BasicDatagramSocket &	operator= (BasicDatagramSocket &&other)
	Move assignment operator.

virtual	~BasicDatagramSocket ()=default
	Destroy the instance.

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

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

virtual int	connect (const Endpoint &endpoint)
	make a connection to the given endpoint.

virtual int	readFrom (char data, unsigned long maxSize, Endpoint endpoint=nullptr) noexcept
	read data on the socket.

virtual int	writeTo (const char *data, unsigned long maxSize, const Endpoint &endpoint) noexcept
	write data on the socket.

const Endpoint &	remoteEndpoint () const
	determine the remote endpoint associated with this socket.

int	mtu () const
	get socket mtu.

int	ttl () const
	returns the Time-To-Live value.

Public Member Functions inherited from join::BasicSocket< Protocol >
	BasicSocket ()
	default constructor.

	BasicSocket (Mode mode)
	create socket instance specifying the mode.

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

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

	BasicSocket (BasicSocket &&other)
	move constructor.

BasicSocket &	operator= (BasicSocket &&other)
	move assignment operator.

virtual	~BasicSocket ()
	destroy the socket instance.

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

void	setMode (Mode mode) noexcept
	set the socket to the non-blocking or blocking mode.

Endpoint	localEndpoint () const
	determine the local endpoint associated with this socket.

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

int	family () const noexcept
	get socket address family.

int	type () const noexcept
	get the protocol communication semantic.

int	protocol () const noexcept
	get socket protocol.

int	handle () const noexcept override
	get socket native handle.

Public Member Functions inherited from join::EventHandler
	EventHandler ()=default
	create instance.

virtual	~EventHandler ()=default
	destroy instance.

Protected Types
enum	TlsState { Encrypted , NonEncrypted }
	TLS state. More...

Protected Member Functions
int	startHandshake ()
	Start SSL handshake.

void	infoCallback (int where, int ret) const
	state information callback.

int	verifyCallback (int preverified, X509_STORE_CTX *context) const
	trusted CA certificates verification callback.

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

bool	checkHostName (X509 *certificate) const
	confirm a match between the hostname contacted and the hostnames listed in the certificate.

Protected Member Functions inherited from join::BasicSocket< Protocol >
int	wait (bool wantRead, bool wantWrite, int timeout) const noexcept
	wait for the socket handle to become ready.

Protected Member Functions inherited from join::EventHandler
virtual void	onReceive ()
	method called when data are ready to be read on handle.

virtual void	onClose ()
	method called when handle is closed.

virtual void	onError ()
	method called when an error occured on handle.

Static Protected Member Functions
static void	infoWrapper (const SSL *ssl, int where, int ret)
	c style callback wrapper for the state information callback.

static int	verifyWrapper (int preverified, X509_STORE_CTX *context)
	c style callback wrapper for the Trusted CA certificates verification callback.

Protected Attributes
join::SslCtxPtr	_tlsContext
	verify certificate revocation using CRL.

join::SslPtr	_tlsHandle
	TLS handle.

TlsState	_tlsState = TlsState::NonEncrypted
	TLS state.

Protected Attributes inherited from join::BasicDatagramSocket< Protocol >
Endpoint	_remote
	remote endpoint.

int	_ttl = 60
	packet time to live.

Protected Attributes inherited from join::BasicSocket< Protocol >
State	_state = State::Closed
	socket state.

Mode	_mode = Mode::NonBlocking
	socket mode.

int	_handle = -1
	socket handle.

Protocol	_protocol
	protocol.

Friends
class	BasicTlsAcceptor< Protocol >
	friendship with basic TLS acceptor

Additional Inherited Members
Static Public Member Functions inherited from join::BasicSocket< Protocol >
static uint16_t	checksum (const uint16_t *data, size_t len, uint16_t current=0)
	get standard 1s complement checksum.

Detailed Description

template<class Protocol>
class join::BasicTlsSocket< Protocol >

basic TLS socket class.

Member Typedef Documentation

◆ Endpoint

template<class Protocol >

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

◆ Mode

template<class Protocol >

using join::BasicTlsSocket< Protocol >::Mode = typename BasicStreamSocket <Protocol>::Mode

◆ Option

template<class Protocol >

using join::BasicTlsSocket< Protocol >::Option = typename BasicStreamSocket <Protocol>::Option

◆ Ptr

template<class Protocol >

using join::BasicTlsSocket< Protocol >::Ptr = std::unique_ptr <BasicTlsSocket <Protocol>>

◆ State

template<class Protocol >

using join::BasicTlsSocket< Protocol >::State = typename BasicStreamSocket <Protocol>::State

Member Enumeration Documentation

◆ TlsState

template<class Protocol >

enum join::BasicTlsSocket::TlsState

protected

TLS state.

Enumerator
Encrypted	Socket is encrypted
NonEncrypted	Socket is not encrypted

Constructor & Destructor Documentation

◆ BasicTlsSocket() [1/6]

template<class Protocol >

join::BasicTlsSocket< Protocol >::BasicTlsSocket ( )

inline

default constructor.

◆ BasicTlsSocket() [2/6]

template<class Protocol >

join::BasicTlsSocket< Protocol >::BasicTlsSocket ( Mode mode )

inline

create instance specifying the mode.

Parameters

mode	Set the socket blocking mode.

◆ BasicTlsSocket() [3/6]

template<class Protocol >

join::BasicTlsSocket< Protocol >::BasicTlsSocket ( join::SslCtxPtr tlsContext )

inline

create instance specifying TLS context.

Parameters

tlsContext TLS context.

◆ BasicTlsSocket() [4/6]

template<class Protocol >

join::BasicTlsSocket< Protocol >::BasicTlsSocket	(	Mode	mode,
		join::SslCtxPtr	tlsContext )

inline

Create socket instance specifying the socket mode and TLS context.

Parameters

mode	Set the socket blocking mode.
tlsContext	TLS context.

◆ BasicTlsSocket() [5/6]

template<class Protocol >

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

delete

copy constructor.

Parameters

other other object to copy.

◆ BasicTlsSocket() [6/6]

template<class Protocol >

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

inline

move constructor.

Parameters

other other object to move.

◆ ~BasicTlsSocket()

template<class Protocol >

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

virtualdefault

destroy the instance.

Member Function Documentation

◆ canRead()

template<class Protocol >

virtual int join::BasicTlsSocket< Protocol >::canRead ( ) const

inlineoverridevirtualnoexcept

get the number of readable bytes.

Returns: The number of readable bytes, -1 on failure.

Reimplemented from join::BasicSocket< Protocol >.

◆ checkHostName()

template<class Protocol >

bool join::BasicTlsSocket< Protocol >::checkHostName ( X509 * certificate ) const

inlineprotected

confirm a match between the hostname contacted and the hostnames listed in the certificate.

Parameters

certificate the server certificate.

Returns: true if an alternative name matched the server hostname.

◆ close()

template<class Protocol >

virtual void join::BasicTlsSocket< Protocol >::close ( )

inlineoverridevirtualnoexcept

close the socket handle.

Reimplemented from join::BasicDatagramSocket< Protocol >.

◆ connectEncrypted()

template<class Protocol >

int join::BasicTlsSocket< Protocol >::connectEncrypted ( const Endpoint & endpoint )

inline

make an encrypted connection to the given endpoint.

Parameters

endpoint endpoint to connect to.

Returns: 0 on success, -1 on failure.

◆ disconnect()

template<class Protocol >

virtual int join::BasicTlsSocket< Protocol >::disconnect ( )

inlineoverridevirtual

shutdown the connection.

Returns: 0 on success, -1 on failure.

Reimplemented from join::BasicStreamSocket< Protocol >.

◆ encrypted()

template<class Protocol >

virtual bool join::BasicTlsSocket< Protocol >::encrypted ( ) const

inlineoverridevirtualnoexcept

check if the socket is secure.

Returns: true if the socket is secure, false otherwise.

Reimplemented from join::BasicSocket< Protocol >.

◆ infoCallback()

template<class Protocol >

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

inlineprotected

state information callback.

Parameters

where	information about which context the callback function was called.
ret	error condition.

◆ infoWrapper()

template<class Protocol >

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

inlinestaticprotected

c style callback wrapper for the state information callback.

Parameters

ssl	SSL objects created from context during connection.
where	information about which context the callback function was called.
ret	error condition.

◆ operator=() [1/2]

template<class Protocol >

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

inline

move assignment operator.

Parameters

other other object to assign.

Returns: assigned object.

◆ operator=() [2/2]

template<class Protocol >

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

delete

copy assignment operator.

Parameters

other other object to assign.

Returns: assigned object.

◆ read()

template<class Protocol >

virtual int join::BasicTlsSocket< Protocol >::read	(	char *	data,
		unsigned long	maxSize )

inlineoverridevirtualnoexcept

read data on the socket.

Parameters

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

Returns: the number of bytes received, -1 on failure.

Reimplemented from join::BasicDatagramSocket< Protocol >.

◆ setCaFile()

template<class Protocol >

int join::BasicTlsSocket< Protocol >::setCaFile ( const std::string & caFile )

inline

set the location of the trusted CA certificate file.

Parameters

caFile path of the trusted CA certificate file.

Returns: 0 on success, -1 on failure.

◆ setCaPath()

template<class Protocol >

int join::BasicTlsSocket< Protocol >::setCaPath ( const std::string & caPath )

inline

set the location of the trusted CA certificates.

Parameters

caPath path of the trusted CA certificates.

Returns: 0 on success, -1 on failure.

◆ setCertificate()

template<class Protocol >

int join::BasicTlsSocket< Protocol >::setCertificate	(	const std::string &	cert,
		const std::string &	key = "" )

inline

set the certificate and the private key.

Parameters

cert	certificate path.
key	private key path.

Returns: 0 on success, -1 on failure.

◆ setCipher()

template<class Protocol >

int join::BasicTlsSocket< Protocol >::setCipher ( const std::string & cipher )

inline

set the cipher list (TLSv1.2 and below).

Parameters

cipher the cipher list.

Returns: 0 on success, -1 on failure.

◆ setCipher_1_3()

template<class Protocol >

int join::BasicTlsSocket< Protocol >::setCipher_1_3 ( const std::string & cipher )

inline

set the cipher list (TLSv1.3).

Parameters

cipher the cipher list.

Returns: 0 on success, -1 on failure.

◆ setVerify()

template<class Protocol >

void join::BasicTlsSocket< Protocol >::setVerify	(	bool	verify,
		int	depth = -1 )

inline

Enable/Disable the verification of the peer certificate.

Parameters

verify	Enable peer verification if set to true, false otherwise.
depth	The maximum certificate verification depth (default: no limit).

◆ startEncryption()

template<class Protocol >

int join::BasicTlsSocket< Protocol >::startEncryption ( )

inline

start socket encryption (perform TLS handshake).

Returns: 0 on success, -1 on failure.

◆ startHandshake()

template<class Protocol >

int join::BasicTlsSocket< Protocol >::startHandshake ( )

inlineprotected

Start SSL handshake.

Returns: 0 on success, -1 on failure.

◆ verifyCallback()

template<class Protocol >

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

inlineprotected

trusted CA certificates verification callback.

Parameters

preverified	indicates, whether the verification of the certificate in question was passed or not.
context	pointer to the complete context used for the certificate chain verification.

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

◆ verifyCert()

template<class Protocol >

int join::BasicTlsSocket< 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::BasicTlsSocket< Protocol >::verifyWrapper	(	int	preverified,
		X509_STORE_CTX *	context )

inlinestaticprotected

c style callback wrapper for the Trusted CA certificates verification callback.

Parameters

preverifiedindicates,whether	the verification of the certificate in question was passed or not.
context	pointer to the complete context used for the certificate chain verification.

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

◆ waitEncrypted()

template<class Protocol >

bool join::BasicTlsSocket< Protocol >::waitEncrypted ( int timeout = 0 )

inline

wait until TLS handshake is performed or timeout occur (non blocking socket).

Parameters

timeout timeout in milliseconds (0: infinite). return true on success, false otherwise.

◆ waitReadyRead()

template<class Protocol >

virtual bool join::BasicTlsSocket< Protocol >::waitReadyRead ( int timeout = 0 ) const

inlineoverridevirtualnoexcept

block until new data is available for reading.

Parameters

timeout timeout in milliseconds (0: infinite).

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

Reimplemented from join::BasicSocket< Protocol >.

◆ waitReadyWrite()

template<class Protocol >

virtual bool join::BasicTlsSocket< Protocol >::waitReadyWrite ( int timeout = 0 ) const

inlineoverridevirtualnoexcept

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

Parameters

timeout timeout in milliseconds (0: infinite).

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

Reimplemented from join::BasicSocket< Protocol >.

◆ write()

template<class Protocol >

virtual int join::BasicTlsSocket< Protocol >::write	(	const char *	data,
		unsigned long	maxSize )

inlineoverridevirtualnoexcept

write data on the socket.

Parameters

data	data buffer to send.
maxSize	maximum number of bytes to write.

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

Reimplemented from join::BasicDatagramSocket< Protocol >.

Friends And Related Symbol Documentation

◆ BasicTlsAcceptor< Protocol >

template<class Protocol >

friend class BasicTlsAcceptor< Protocol >

friend

friendship with basic TLS acceptor

Member Data Documentation

◆ _tlsContext

template<class Protocol >

join::SslCtxPtr join::BasicTlsSocket< Protocol >::_tlsContext

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. TLS context.

◆ _tlsHandle

template<class Protocol >

join::SslPtr join::BasicTlsSocket< Protocol >::_tlsHandle

protected

TLS handle.

◆ _tlsState

template<class Protocol >

TlsState join::BasicTlsSocket< Protocol >::_tlsState = TlsState::NonEncrypted

protected

TLS state.

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

core/include/join/protocol.hpp
core/include/join/socket.hpp

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Friends

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ Endpoint

◆ Mode

◆ Option

◆ Ptr

◆ State

Member Enumeration Documentation

◆ TlsState

Constructor & Destructor Documentation

◆ BasicTlsSocket() [1/6]

◆ BasicTlsSocket() [2/6]

◆ BasicTlsSocket() [3/6]

◆ BasicTlsSocket() [4/6]

◆ BasicTlsSocket() [5/6]

◆ BasicTlsSocket() [6/6]

◆ ~BasicTlsSocket()

Member Function Documentation

◆ canRead()

◆ checkHostName()

◆ close()

◆ connectEncrypted()

◆ disconnect()

◆ encrypted()

◆ infoCallback()

◆ infoWrapper()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ read()

◆ setCaFile()

◆ setCaPath()

◆ setCertificate()

◆ setCipher()

◆ setCipher_1_3()

◆ setVerify()

◆ startEncryption()

◆ startHandshake()

◆ verifyCallback()

◆ verifyCert()

◆ verifyWrapper()

◆ waitEncrypted()

◆ waitReadyRead()

◆ waitReadyWrite()

◆ write()

Friends And Related Symbol Documentation

◆ BasicTlsAcceptor< Protocol >

Member Data Documentation

◆ _tlsContext

◆ _tlsHandle

◆ _tlsState