#include <connectiontls.h>

Inheritance diagram for ConnectionTLS:

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)
virtual void	setSubject (const std::string &subject)
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 ConnectionTCP( 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 Schroeter 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	(	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 20 of file connectiontls.cpp.

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 29 of file connectiontls.cpp.

~ConnectionTLS ( )

virtual

Virtual Destructor.

Definition at line 37 of file connectiontls.cpp.

Member Function Documentation

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 123 of file connectiontls.cpp.

ConnectionError connect ( )

virtual

Used to initiate the connection.

Returns: Returns the connection state.

Implements ConnectionBase.

Definition at line 54 of file connectiontls.cpp.

void disconnect ( )

virtual

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

Implements ConnectionBase.

Definition at line 115 of file connectiontls.cpp.

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.

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 133 of file connectiontls.cpp.

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 191 of file connectiontls.h.

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 153 of file connectiontls.cpp.

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 173 of file connectiontls.cpp.

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 159 of file connectiontls.cpp.

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 167 of file connectiontls.cpp.

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 183 of file connectiontls.cpp.

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 147 of file connectiontls.cpp.

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 139 of file connectiontls.cpp.

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 107 of file connectiontls.cpp.

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 84 of file connectiontls.cpp.

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 141 of file connectiontls.h.

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 98 of file connectiontls.cpp.

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.

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.

Definition at line 107 of file connectiontls.h.

void setConnectionImpl ( ConnectionBase * connection )

Sets the transport connection.

Parameters

connection The transport connection to use.

Definition at line 43 of file connectiontls.cpp.

virtual void setSubject ( const std::string & subject )

inlinevirtual

Sets the subject/common name to search the system certificate store for. Used only by the SChannel implementation (Windows). Required for SChannel server, optional for SChannel client. The system 'MY' certificate store will be searched for the subject (substring match) for a private key/certificate pair which will be used.

Note: On the server-side, initialization (init()) will fail if subject is not set or if no associated key/certificate could be found. On the client-side initialization will fail if a subject was set for which no key/certificate pair could be found. Setting no subject on the client-side is fine.; setSubject() must be called before init() to be effective.

Parameters

subject The to use.

Definition at line 125 of file connectiontls.h.

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

Member Function Documentation