gloox  1.0.20
Public Member Functions | Protected Member Functions | List of all members
ConnectionTLS Class Reference

#include <connectiontls.h>

Inheritance diagram for ConnectionTLS:
Inheritance graph
[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 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)
 
- 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 TLSBasegetTLSBase (TLSHandler *th, const std::string server)
 

Additional Inherited Members

- Protected Attributes inherited from ConnectionBase
ConnectionDataHandlerm_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
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 22 of file connectiontls.cpp.

◆ ConnectionTLS() [2/2]

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 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
totalInThe total number of bytes received.
totalOutThe 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
connectionThe 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
baseThe encryption implementation which called this function.
dataThe 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
connectionThe connection.
reasonThe 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
baseThe encryption implementation which called this function.
dataThe 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
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 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
connectionThe connection that received the data.
dataThe 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
timeoutThe 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
thThe 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
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 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
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.

◆ 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
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.

◆ setConnectionImpl()

void setConnectionImpl ( ConnectionBase connection)

Sets the transport connection.

Parameters
connectionThe 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: