Kourier::TlsSocket Class Reference

The TlsSocket class represents a TLS-encrypted data exchange over a TCP socket. More...

Public Member Functions
	TlsSocket (const TlsConfiguration &tlsConfiguration)
	TlsSocket (int64_t socketDescriptor, const TlsConfiguration &tlsConfiguration)
	~TlsSocket () override
size_t	dataToWrite () const override
Signal	encrypted ()
bool	isEncrypted () const
size_t	read (char *pBuffer, size_t maxSize) override
std::string_view	readAll () override
size_t	skip (size_t maxSize) override
const TlsConfiguration &	tlsConfiguration () const
Public Member Functions inherited from Kourier::TcpSocket
	TcpSocket ()
	TcpSocket (int64_t socketDescriptor)
	~TcpSocket () override
void	abort ()
void	connect (std::string_view host, uint16_t port)
Signal	connected ()
Signal	disconnected ()
void	disconnectFromPeer ()
Signal	error ()
std::string_view	errorMessage () const
int	getSocketOption (SocketOption option) const
std::string_view	localAddress () const
uint16_t	localPort () const
std::string_view	peerAddress () const
std::string_view	peerName () const
uint16_t	peerPort () const
size_t	read (char *pBuffer, size_t maxSize) override
std::string_view	readAll () override
size_t	readBufferCapacity () const
void	setBindAddressAndPort (std::string_view address, uint16_t port=0)
bool	setReadBufferCapacity (size_t capacity)
void	setSocketOption (SocketOption option, int value)
size_t	skip (size_t maxSize) override
State	state () const
size_t	write (const char *pData, size_t maxSize) override
Public Member Functions inherited from Kourier::IOChannel
	IOChannel (const size_t readBufferCapacity=0)
	~IOChannel () override=default
void	clear ()
virtual size_t	dataAvailable () const
virtual size_t	dataToWrite () const
std::string_view	peekAll ()
char	peekChar (size_t index) const
virtual size_t	read (char *pBuffer, size_t maxSize)
virtual std::string_view	readAll ()
size_t	readBufferCapacity () const
Signal	receivedData ()
bool	reset ()
Signal	sentData (size_t count)
bool	setReadBufferCapacity (size_t capacity)
virtual size_t	skip (size_t maxSize)
std::string_view	slice (size_t pos, size_t count)
virtual size_t	write (const char *pData, size_t count)
size_t	write (std::string_view data)
Public Member Functions inherited from Kourier::Object
	Object ()
virtual	~Object ()
void	disconnect ()
template<class T_PtrToReceiverOrSignal >
void	disconnect (T_PtrToReceiverOrSignal pReceiverOrSignal)
void	scheduleForDeletion ()
template<class T >
T	tryCast ()
template<class T >
T	tryCast () const

Additional Inherited Members
Public Types inherited from Kourier::TcpSocket
enum class	SocketOption {   LowDelay ,   KeepAlive ,   SendBufferSize ,   ReceiveBufferSize }
	Specifies the socket options that can be set and retrived. More...
enum class	State {   Unconnected ,   Connecting ,   Connected ,   Disconnecting }
	Connection state of TcpSocket. More...
Static Public Member Functions inherited from Kourier::Object
template<class T_PtrToSignal , class T_PtrToSlot >
static void	connect (MetaInvocable< T_PtrToSignal >::T_Class *pSender, T_PtrToSignal pSignal, MetaInvocable< T_PtrToSlot >::T_Class *pReceiver, T_PtrToSlot pSlot)
template<class T_PtrToSignal , class T_PtrToSlot >
static void	connect (MetaInvocable< T_PtrToSignal >::T_Class *pSender, T_PtrToSignal pSignal, Object *pReceiver, T_PtrToSlot pSlot)
template<class T_PtrToSignal , class T_PtrToSlot >
static void	connect (MetaInvocable< T_PtrToSignal >::T_Class *pSender, T_PtrToSignal pSignal, T_PtrToSlot pSlot)
template<class T_PtrToSignal , class T_PtrToSlot >
static void	disconnect (Object *pSender, T_PtrToSignal pSignal, Object *pReceiver, T_PtrToSlot pSlot)

Detailed Description

The TlsSocket class represents a TLS-encrypted data exchange over a TCP socket.

TlsSocket is a subclass of TcpSocket and represents TLS-encrypted TCP sockets. You can use encrypted TlsSockets as channels for exchanging stream-oriented data with the connected peer.

All TlsSocket constructors require a TlsConfiguration, which TlsSocket uses to set up TLS encryption. TlsSocket configures TLS encryption in the first TLS handshake right after the TlsSocket establishes the TCP connection and emits the connected signal.

You can call connect to start connecting to the peer. TlsSocket emits the connected signal when it successfully establishes a TCP connection. After connecting to the peer and emitting the connected signal, TlsSocket starts the TLS handshake. When the TLS handshake finishes, TlsSocket emits the encrypted signal and can start encrypting and decrypting data. TlsSocket emits the error signal if it fails to connect to the peer or the TLS handshake fails. TlsSocket waits 60 seconds for the connection to be established and 60 seconds for the TLS handshake to complete before aborting. You can call errorMessage to fetch the last error that occurred in TlsSocket. Before calling connect to start a connection, you can call setBindAddressAndPort to specify an address and, optionally, a port that TlsSocket should bind to before connecting to the peer.

You can call write to write data to a connected TlsSocket. You can start writing data after TlsSocket emits the connected signal. TlsSocket buffers all data you write to it until the TLS handshake finishes, and TlsSocket emits the encrypted signal. TlsSocket emits the sentData signal when it writes encrypted data to the channel. You can call dataToWrite to know how much data is still waiting to be encrypted and written to the channel.

TlsSocket emits the receivedData signal when it decrypts data from the channel. You can call read to read unencrypted data from the TlsSocket and dataAvailable to know how much data has been decrypted from the channel and is available for reading.

An encrypted TlsSocket emits the disconnected signal when the connection finishes.

You can start a connection anytime by calling connect, even on slots connected to the error signal.

You can call disconnectFromPeer on an encrypted TlsSocket to start disconnecting from the peer. An encrypted TlsSocket always performs a graceful shutdown when disconnecting by first encrypting and writing all pending data to the channel, then performing the TLS shutdown by sending a close_notify shutdown alert to the peer and waiting for the peer's close_notify shutdown alert. After shutting down TLS, TlsSocket turns off further send operations (by calling shutdown with SHUT_WR) and waits for the peer to close the connection. TlsSocket only emits the disconnected signal for graceful shutdowns. If any error occurs while disconnecting, TlsSocket emits the error signal. TlsSocket waits 10 seconds for a graceful shutdown before aborting the connection.

TlsSocket uses custom memory BIOs to limit OpenSSL to TLS computations only, while keeping all connection-related work under TlsSocket's control. Custom memory BIOs enable TlsSocket to provide leading performance on TLS-encrypted connections. Also, TlsSocket integrates epoll into Qt's event system and uses it to detect when the TlsSocket is available for IO operations. Kourier can handle millions of sockets even on modest machines, as TlsSocket is very lightweight memory-wise.

Constructor & Destructor Documentation

TlsSocket() [1/2]

Kourier::TlsSocket::TlsSocket

(

const TlsConfiguration &

tlsConfiguration

)

Creates a TlsSocket with the given tlsConfiguration, which TlsSocket uses to configure TLS encryption after TlsSocket establishes the TCP connection. The socket is created in the Unconnected state. You can call connect to connect to a peer.

TlsSocket() [2/2]

Kourier::TlsSocket::TlsSocket	(	int64_t	socketDescriptor,
		const TlsConfiguration &	tlsConfiguration
	)

Creates a connected TlsSocket with socketDescriptor and uses tlsConfiguration to configure TLS encryption. TlsSocket aborts and closes the given descriptor if it does not represent a connected socket. You can call state to check if the TlsSocket instance is in the Connected state.

Because TlsSocket takes ownership of the given socketDescriptor, disregarding whether the connection succeeded, you should not close the given descriptor.

~TlsSocket()

Kourier::TlsSocket::~TlsSocket ( )

override

Destroys the object and aborts the connection if TlsSocket is not in the Unconnected state.

Member Function Documentation

dataToWrite()

size_t Kourier::TlsSocket::dataToWrite ( ) const

overridevirtual

returns the size of the data IOChannel has to write to the channel.

Reimplemented from Kourier::IOChannel.

encrypted()

Signal Kourier::TlsSocket::encrypted

(

)

After TlsSocket establishes the TCP connection and emits the connected signal, the TLS handshake starts. TlsSocket emits the encrypted signal when the TLS handshake is complete, and the TlsSocket can start encrypting and decrypting data. TlsSocket waits 60 seconds for the TLS handshake to complete before aborting and emits the error signal if the TLS handshake fails.

You can start writing data to TlsSocket after it emits the connected signal, as TlsSocket buffers all data written to it until it configures TLS encryption.

isEncrypted()

bool Kourier::TlsSocket::isEncrypted

(

)

const

Returns true if TlsSocket has setup TLS encryption and can encrypt and decrypt data.

read()

size_t Kourier::TlsSocket::read ( char *  pBuffer, size_t  maxSize  )

overridevirtual

reads up to maxSize from the read buffer into the buffer pointed by pBuffer. Returns the number of bytes read from the read buffer.

Reimplemented from Kourier::TcpSocket.

readAll()

std::string_view Kourier::TlsSocket::readAll ( )

overridevirtual

returns all data in the read buffer. Writing to IOChannel after calling this method invalidates the returned data.

Reimplemented from Kourier::TcpSocket.

skip()

size_t Kourier::TlsSocket::skip ( size_t  maxSize )

overridevirtual

removes up to maxSize from the beginning of the read buffer. Returns the number of bytes removed.

Reimplemented from Kourier::TcpSocket.

tlsConfiguration()

const TlsConfiguration & Kourier::TlsSocket::tlsConfiguration

(

)

const

Returns the tlsConfiguration given in the TlsSocket constructor, which will be used to set up TLS encryption.