gloox 1.0
Public Member Functions | Protected Member Functions

ConnectionTLS Class Reference

This is an implementation of a TLS/SSL connection. More...

#include <connectiontls.h>

Inheritance diagram for ConnectionTLS:
Inheritance graph
[legend]

List of all members.

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 CertInfofetchTLSInfo () 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 ConnectionBasenewInstance () 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)

Protected Member Functions

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

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@camaya.net>
Matthew Wild <mwild1@gmail.com>
Since:
1.0

Definition at line 51 of file connectiontls.h.


Constructor & Destructor Documentation

build buildd gloox src connectiontls cpp ConnectionTLS ( ConnectionDataHandler cdh,
ConnectionBase conn,
const LogSink log 
)

Constructs a new ConnectionTLS object.

Parameters:
cdhThe ConnectionDataHandler that will be notified of events from this connection
connA 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.
logThe log target. Obtain it from ClientBase::logInstance().

Definition at line 21 of file connectiontls.cpp.

ConnectionTLS ( ConnectionBase conn,
const LogSink log 
)

Constructs a new ConnectionTLS object.

Parameters:
connA 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.
logThe log target. Obtain it from ClientBase::logInstance().

Definition at line 30 of file connectiontls.cpp.

~ConnectionTLS ( ) [virtual]

Virtual Destructor.

Definition at line 38 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 125 of file connectiontls.cpp.

ConnectionError connect ( ) [virtual]

Used to initiate the connection.

Returns:
Returns the connection state.

Implements ConnectionBase.

Definition at line 55 of file connectiontls.cpp.

void disconnect ( ) [virtual]

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

Implements ConnectionBase.

Definition at line 117 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:
totalInThe total number of bytes received.
totalOutThe total number of bytes sent.

Implements ConnectionBase.

Definition at line 135 of file connectiontls.cpp.

virtual TLSBase* getTLSBase ( TLSHandler th,
const std::string  server 
) [inline, protected, virtual]

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

Returns:
A TLS object.

Reimplemented in ConnectionTLSServer.

Definition at line 178 of file connectiontls.h.

void handleConnect ( const ConnectionBase connection) [virtual]

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

Parameters:
connectionThe connection.

Implements ConnectionDataHandler.

Definition at line 155 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:
baseThe encryption implementation which called this function.
dataThe decrypted data (e.g. to parse).

Implements TLSHandler.

Definition at line 175 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:
connectionThe connection.
reasonThe reason for the disconnect.

Implements ConnectionDataHandler.

Definition at line 161 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:
baseThe encryption implementation which called this function.
dataThe encrypted data (e.g. to send over the wire).

Implements TLSHandler.

Definition at line 169 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:
baseThe encryption implementation which called this function.
successWhether or not the handshake was successful.
certinfoInformation about the server's certificate.

Implements TLSHandler.

Definition at line 185 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:
connectionThe connection that received the data.
dataThe data received.

Implements ConnectionDataHandler.

Definition at line 149 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 141 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 109 of file connectiontls.cpp.

ConnectionError recv ( int  timeout = -1) [virtual]

Use this periodically to receive data from the socket.

Parameters:
timeoutThe timeout to use for select in microseconds. Default of -1 means blocking.
Returns:
The state of the connection.

Implements ConnectionBase.

Definition at line 86 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:
thThe TLSHandler to register.
Note:
If no handler is set, ConnectionTLS will accept any certificate and continue with the connection.

Definition at line 128 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:
dataThe 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 100 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:
cacertsA 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:
clientKeyThe absolute path to the user's private key in PEM format.
clientCertsA 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.

void setConnectionImpl ( ConnectionBase connection)

Sets the transport connection.

Parameters:
connectionThe transport connection to use.

Definition at line 44 of file connectiontls.cpp.


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