#include <connectiontls.h>

Inheritance diagram for ConnectionTLS:

[legend]

Public Member Functions
	ConnectionTLS (ConnectionDataHandler cdh, ConnectionBase conn, const LogSink &log)

	ConnectionTLS (ConnectionBase *conn, const LogSink &log)

virtual	~ConnectionTLS ()

void	setCACerts (const StringList &cacerts)

const CertInfo &	fetchTLSInfo () const

void	setClientCert (const std::string &clientKey, const std::string &clientCerts)

void	setConnectionImpl (ConnectionBase *connection)

void	registerTLSHandler (TLSHandler *th)

virtual ConnectionError	connect ()

virtual ConnectionError	recv (int timeout=-1)

virtual bool	send (const std::string &data)

virtual ConnectionError	receive ()

virtual void	disconnect ()

virtual void	cleanup ()

virtual void	getStatistics (long int &totalIn, long int &totalOut)

virtual void	handleReceivedData (const ConnectionBase *connection, const std::string &data)

virtual void	handleConnect (const ConnectionBase *connection)

virtual void	handleDisconnect (const ConnectionBase *connection, ConnectionError reason)

virtual ConnectionBase *	newInstance () const

virtual void	handleEncryptedData (const TLSBase *, const std::string &data)

virtual void	handleDecryptedData (const TLSBase *, const std::string &data)

virtual void	handleHandshakeResult (const TLSBase *base, bool success, CertInfo &certinfo)

Public Member Functions inherited from TLSHandler
virtual	~TLSHandler ()

Public Member Functions inherited from ConnectionBase
	ConnectionBase (ConnectionDataHandler *cdh)

virtual	~ConnectionBase ()

ConnectionState	state () const

void	registerConnectionDataHandler (ConnectionDataHandler *cdh)

void	setServer (const std::string &server, int port=-1)

const std::string &	server () const

int	port () const

virtual int	localPort () const

virtual const std::string	localInterface () const

Public Member Functions inherited from ConnectionDataHandler
virtual	~ConnectionDataHandler ()

Protected Member Functions
virtual TLSBase *	getTLSBase (TLSHandler *th, const std::string server)

Additional Inherited Members
Protected Attributes inherited from ConnectionBase
ConnectionDataHandler *	m_handler

ConnectionState	m_state

std::string	m_server

int	m_port

Detailed Description

This is an implementation of a TLS/SSL connection.

You should not need to use this function directly. However, you can use it to connect to the legacy Jabber SSL port, 5223.

Usage:

Client *c = new Client( ... );
c->setConnectionImpl( new ConnectionTLS( c,
                               new ConnectionTCPClient( c->logInstance(), server, 5223 ),
                               c->logInstance()) );

Due to the need for handshaking data to be sent/received before the connection is fully established, be sure not to use the connection until ConnectionDataHandler::handleConnect() of the specified ConnectionDataHandler is called.

Author: Jakob Schröter js@ca.nosp@m.maya.nosp@m..net; Matthew Wild mwild.nosp@m.1@gm.nosp@m.ail.c.nosp@m.om

Since: 1.0

Definition at line 51 of file connectiontls.h.

Constructor & Destructor Documentation

◆ ConnectionTLS() [1/2]

ConnectionTLS	(	ConnectionDataHandler *	cdh,
		ConnectionBase *	conn,
		const LogSink &	log
	)

Constructs a new ConnectionTLS object.

Parameters

cdh	The ConnectionDataHandler that will be notified of events from this connection
conn	A transport connection. It should be configured to connect to the server and port you wish to make the encrypted connection to. ConnectionTLS will own the transport connection and delete it in its destructor.
log	The log target. Obtain it from ClientBase::logInstance().

Definition at line 22 of file connectiontls.cpp.

◆ ConnectionTLS() [2/2]

ConnectionTLS	(	ConnectionBase *	conn,
		const LogSink &	log
	)

Constructs a new ConnectionTLS object.

Parameters

conn	A transport connection. It should be configured to connect to the server and port you wish to make the encrypted connection to. ConnectionTLS will own the transport connection and delete it in its destructor.
log	The log target. Obtain it from ClientBase::logInstance().

Definition at line 31 of file connectiontls.cpp.

◆ ~ConnectionTLS()

~ConnectionTLS ( )

virtual

Virtual Destructor.

Definition at line 39 of file connectiontls.cpp.

Member Function Documentation

◆ cleanup()

void cleanup ( )

virtual

This function is called after a disconnect to clean up internal state. It is also called by ConnectionBase's destructor.

Reimplemented from ConnectionBase.

Definition at line 120 of file connectiontls.cpp.

◆ connect()

ConnectionError connect ( )

virtual

Used to initiate the connection.

Returns: Returns the connection state.

Implements ConnectionBase.

Definition at line 59 of file connectiontls.cpp.

◆ disconnect()

void disconnect ( )

virtual

Disconnects an established connection. NOOP if no active connection exists.

Implements ConnectionBase.

Definition at line 112 of file connectiontls.cpp.

◆ fetchTLSInfo()

const CertInfo& fetchTLSInfo ( ) const

inline

This function is used to retrieve certificate and connection info of a encrypted connection.

Returns: Certificate information.

Note: This funcztion is a wrapper around TLSBase::fetchTLSInfo().

Definition at line 94 of file connectiontls.h.

◆ getStatistics()

void getStatistics	(	long int &	totalIn,
		long int &	totalOut
	)

virtual

Returns current connection statistics.

Parameters

totalIn	The total number of bytes received.
totalOut	The total number of bytes sent.

Implements ConnectionBase.

Definition at line 130 of file connectiontls.cpp.

◆ getTLSBase()

virtual TLSBase* getTLSBase	(	TLSHandler *	th,
		const std::string	server
	)

inlineprotectedvirtual

Returns a TLS object (client). Reimplement to change the type of the object.

Returns: A TLS object.

Reimplemented in ConnectionTLSServer.

Definition at line 179 of file connectiontls.h.

◆ handleConnect()

void handleConnect ( const ConnectionBase * connection )

virtual

This function is called when e.g. the raw TCP connection was established.

Parameters

connection The connection.

Implements ConnectionDataHandler.

Definition at line 150 of file connectiontls.cpp.

◆ handleDecryptedData()

void handleDecryptedData	(	const TLSBase *	base,
		const std::string &	data
	)

virtual

Reimplement this function to receive decrypted data from a TLSBase implementation.

Parameters

base	The encryption implementation which called this function.
data	The decrypted data (e.g. to parse).

Implements TLSHandler.

Definition at line 170 of file connectiontls.cpp.

◆ handleDisconnect()

void handleDisconnect	(	const ConnectionBase *	connection,
		ConnectionError	reason
	)

virtual

This connection is called when e.g. the raw TCP connection was closed.

Parameters

connection	The connection.
reason	The reason for the disconnect.

Implements ConnectionDataHandler.

Definition at line 156 of file connectiontls.cpp.

◆ handleEncryptedData()

void handleEncryptedData	(	const TLSBase *	base,
		const std::string &	data
	)

virtual

Reimplement this function to receive encrypted data from a TLSBase implementation.

Parameters

base	The encryption implementation which called this function.
data	The encrypted data (e.g. to send over the wire).

Implements TLSHandler.

Definition at line 164 of file connectiontls.cpp.

◆ handleHandshakeResult()

void handleHandshakeResult	(	const TLSBase *	base,
		bool	success,
		CertInfo &	certinfo
	)

virtual

Reimplement this function to receive the result of a TLS handshake.

Parameters

base	The encryption implementation which called this function.
success	Whether or not the handshake was successful.
certinfo	Information about the server's certificate.

Implements TLSHandler.

Definition at line 180 of file connectiontls.cpp.

◆ handleReceivedData()

void handleReceivedData	(	const ConnectionBase *	connection,
		const std::string &	data
	)

virtual

This function is called for received from the underlying transport.

Parameters

connection	The connection that received the data.
data	The data received.

Implements ConnectionDataHandler.

Definition at line 144 of file connectiontls.cpp.

◆ newInstance()

ConnectionBase * newInstance ( ) const

virtual

This function returns a new instance of the current ConnectionBase-derived object. The idea is to be able to 'clone' ConnectionBase-derived objects without knowing of what type they are exactly.

Returns: A new Connection* instance.

Implements ConnectionBase.

Reimplemented in ConnectionTLSServer.

Definition at line 136 of file connectiontls.cpp.

◆ receive()

ConnectionError receive ( )

virtual

Use this function to put the connection into 'receive mode', i.e. this function returns only when the connection is terminated.

Returns: Returns a value indicating the disconnection reason.

Implements ConnectionBase.

Definition at line 104 of file connectiontls.cpp.

◆ recv()

ConnectionError recv ( int timeout = -1 )

virtual

Use this periodically to receive data from the socket.

Parameters

timeout The timeout to use for select in microseconds. Default of -1 means blocking.

Returns: The state of the connection.

Implements ConnectionBase.

Definition at line 90 of file connectiontls.cpp.

◆ registerTLSHandler()

void registerTLSHandler ( TLSHandler * th )

inline

Registers an TLSHandler derived object. Only the handleHandshakeResult() function will be used after a handshake took place. You can review certificate info there.

Parameters

th	The TLSHandler to register.

Note: If no handler is set, ConnectionTLS will accept any certificate and continue with the connection.

Definition at line 129 of file connectiontls.h.

◆ send()

bool send ( const std::string & data )

virtual

Use this function to send a string of data over the wire. The function returns only after all data has been sent.

Parameters

data	The data to send.

Returns: True if the data has been sent (no guarantee of receipt), false in case of an error.

Implements ConnectionBase.

Definition at line 95 of file connectiontls.cpp.

◆ setCACerts()

void setCACerts ( const StringList & cacerts )

inline

Use this function to set a number of trusted root CA certificates which shall be used to verify a servers certificate.

Parameters

cacerts A list of absolute paths to CA root certificate files in PEM format.

Note: This function is a wrapper for TLSBase::setCACerts().

Definition at line 84 of file connectiontls.h.

◆ setClientCert()

void setClientCert	(	const std::string &	clientKey,
		const std::string &	clientCerts
	)

inline

Use this function to set the user's certificate and private key. The certificate will be presented to the server upon request and can be used for SASL EXTERNAL authentication. The user's certificate file should be a bundle of more than one certificate in PEM format. The first one in the file should be the user's certificate, each cert following that one should have signed the previous one.

Note: These certificates are not necessarily the same as those used to verify the server's certificate.

Parameters

clientKey	The absolute path to the user's private key in PEM format.
clientCerts	A path to a certificate bundle in PEM format.

Note: This function is a wrapper around TLSBase::setClientCert().

Definition at line 108 of file connectiontls.h.

◆ setConnectionImpl()

void setConnectionImpl ( ConnectionBase * connection )

Sets the transport connection.

Parameters

connection The transport connection to use. A potentially previously set connection will be deleted.

Definition at line 45 of file connectiontls.cpp.

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

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ConnectionTLS() [1/2]

◆ ConnectionTLS() [2/2]

◆ ~ConnectionTLS()

Member Function Documentation

◆ cleanup()

◆ connect()

◆ disconnect()

◆ fetchTLSInfo()

◆ getStatistics()

◆ getTLSBase()

◆ handleConnect()

◆ handleDecryptedData()

◆ handleDisconnect()

◆ handleEncryptedData()

◆ handleHandshakeResult()

◆ handleReceivedData()

◆ newInstance()

◆ receive()

◆ recv()

◆ registerTLSHandler()

◆ send()

◆ setCACerts()

◆ setClientCert()

◆ setConnectionImpl()