ConnectionTLS Class Reference

`#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()) );
gloox::ClientBase::logInstance
LogSink & logInstance()
Definition clientbase.h:599
gloox::ClientBase::setConnectionImpl
void setConnectionImpl(ConnectionBase *cb)
Definition clientbase.cpp:1199
gloox::Client
This class implements a basic Jabber/XMPP Client.
Definition client.h:117
gloox::ConnectionBase::server
const std::string & server() const
Definition connectionbase.h:115
gloox::ConnectionTCPClient
This is an implementation of a simple TCP connection.
Definition connectiontcpclient.h:37
gloox::ConnectionTLS::ConnectionTLS
ConnectionTLS(ConnectionDataHandler *cdh, ConnectionBase *conn, const LogSink &log)
Definition connectiontls.cpp:22

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 )

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

- connectiontls.h
- connectiontls.cpp