ConnectionTLS Class Reference

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

#include <connectiontls.h>

Inherits gloox::TLSHandler, gloox::ConnectionBase, and gloox::ConnectionDataHandler.

Inherited by ConnectionTLSServer.

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

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

~ConnectionTLS (  )  [virtual]

Virtual Destructor.

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

ConnectionError connect (  )  [virtual]

Used to initiate the connection.

Returns:
Returns the connection state.

Implements ConnectionBase.

Definition at line 51 of file connectiontls.cpp.

void disconnect (  )  [virtual]

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

Implements ConnectionBase.

Definition at line 113 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 131 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:
connection The connection.

Implements ConnectionDataHandler.

Definition at line 151 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 171 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 157 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 165 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 181 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 145 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 137 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 105 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 82 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 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:
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 96 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.
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:
connection The transport connection to use.

Definition at line 40 of file connectiontls.cpp.


The documentation for this class was generated from the following files:
Generated on Tue Jun 8 23:37:56 2010 for gloox by  doxygen 1.6.3