Home

C-Bits Package Documentation

Main Page Namespace List Compound List File List Compound Members File Members

cbits::SSLSocket Class Reference

This class is an SSL-enabled version of cbits::Socket. More...

#include <SSLSocket.h>

Collaboration diagram for cbits::SSLSocket:

Public Types
typedef SSL *	SSL_PTR
	\typedef A type definition used with the cbits::SSLSocket-to- OpenSSL SSL conversion operator. More...
Public Methods
	SSLSocket (const std::string &host, const int port, SSLContext *const ctxt=0, const bool now=true) throw ( SocketException )
	Construct a SSL-enabled socket. More...
	SSLSocket (const char host, const int port, SSLContext const ctxt=0, const bool now=true) throw ( SocketException )
	Construct a SSL-enabled socket. More...
virtual	~SSLSocket ()
	Destructor. More...
virtual void	connect () throw (SocketException)
virtual const ssize_t	read (char const buffer, const int buflen, int const error=0, const long int msec=0) throw ( SocketException )
virtual const ssize_t	receive (char const buffer, const int buflen, const long int msec=0, int const error=0) throw ( SocketException )
virtual const ssize_t	readLine (std::string &buffer, const std::string &delim, int *const error=0, const long int msec=0) throw ( SocketException )
	First try to satisfy the read request from the SSL buffer. More...
virtual const ssize_t	write (const char buffer, const long buflen, int const error=0, const long int msec=0) throw ( SocketException )
virtual const ssize_t	send (const char buffer, const long buflen, int const error=0, const long int msec=0) throw ( SocketException )
const SSLPeer &	getPeer () const throw ( SocketException )
	Access information about the SSL peer. More...
	operator SSL_PTR ()
	Type conversion operator to allow a cbits::SSLSocket instance to be used where an OpenSSL SSL object is required. More...
Static Public Methods
SSLSocket *	create (const socket_t fd, SSLContext *const ctxt=0) throw ( SocketException )
	Create a SSL-enabled socket instance from an existing socket file descriptor. More...
void	setGlobalContext (SSLContext *gctx) throw ( SSLContextException )
	Set a SSL context to be used by ALL new SSLSocket instances. More...
Protected Methods
	SSLSocket (const socket_t fd, SSLContext *const ctxt=0) throw ( SocketException )
	Protected constructor for wrapping a socket descriptor in an cbits::SSLSocket object. More...
Protected Attributes
bool	_ssl_is_connected
	A state flag that is set to true* after the SSL handshake has successfully completed.* More...
Private Methods
void	set_bio (const socket_t fd) throw ( SocketException )
	Wrap the underlying network socket in an OpenSSL socket BIO object. More...
Private Attributes
BIO *	_bio
	The OpenSSL BIO object that wraps the low-level network socket connection. More...
SSLContext *	_ctxt
	The SSL context for this SSL connection. More...
SSL *	_ssl
	The OpenSSL SSL object representing this SSL connection. More...
SSLPeer *	_peer
	The SSL peer if the SSL connection is complete. More...
CriticalSection	_csect
	Critical section used to synchronize access to non-read/write specific code. More...
CriticalSection	_read_csect
	Critical section object used to prevent multiple threads from simultaneously reading from this SSL socket. More...
CriticalSection	_write_csect
	Critical section object used to prevent multiple threads from simultaneously writing to this SSL socket. More...
Static Private Attributes
SSLContext *	_global_ctxt = 0
	The global, default SSL context, if set. More...

Detailed Description

This class is an SSL-enabled version of cbits::Socket.

The OpenSSL library (http://www.openssl.org) is used to provide SSL-related functionality and X.509 certificate handling.

The current version of this class is a minimal implementation. Overtime, more of the power available via OpenSSL will become visible in its interface.

From the user's perspective, a cbits::SSLSocket is (in principle) identical to a cbits::Socket in terms of functionality after the network connection has been established and the SSL handshake has succeeded.

However, all SSL sockets have to be created within a particular SSL context that defines parameters and data used during the SSL handshake, such as what ciphers are allowed (or not) and the location of relevant X.509 certificates.

The cbits::SSLContext class is used to represent an SSL security context for establishing SSL network connections. An instance of cbits::SSLContext should be provided to the cbits::SSLSocket constructor or set globally, in advance, for all (future) SSLSocket instances via the cbits::SSLSocket::setGlobalContext method.

Other methods in cbits::SSLSocket not inherited from cbits::Socket include those related to accessing the security credentials of the SSL peer (e.g. see cbits::SSLPeer).

Member Typedef Documentation

typedef SSL* cbits::SSLSocket::SSL_PTR

\typedef A type definition used with the cbits::SSLSocket-to- OpenSSL SSL conversion operator.

Constructor & Destructor Documentation

SSLSocket::SSLSocket ( const std::string & host,

const int port,

SSLContext *const ctxt = 0,

const bool now = true

) throw ( SocketException )

Construct a SSL-enabled socket.

Exceptions:

SocketException - if the IP of the specified hostname can not be found, or an OS-level error occurs during the construction of the underlying TCP socket.

Parameters:

host see cbits::Socket::Socket

port see cbits::Socket::Socket

now SSL context to use for this connection. If not specified, then a global context should have already been set. see cbits::Socket::Socket

cbits::SSLSocket::SSLSocket ( const char * host,

const int port,

SSLContext *const ctxt = 0,

const bool now = true

) throw ( SocketException )

Construct a SSL-enabled socket.

Exceptions:

SocketException - if the IP of the specified hostname can not be found, or an OS-level error occurs during the construction of the underlying TCP socket.

Parameters:

host see cbits::Socket::Socket

port see cbits::Socket::Socket

now SSL context to use for this connection. If not specified, then a global context should have already been set. see cbits::Socket::Socket

SSLSocket::~SSLSocket ( ) [virtual]

Destructor.
Close the network connection and destroy this socket instance.

SSLSocket::SSLSocket ( const socket_t fd,

SSLContext *const ctxt = 0

) throw ( SocketException ) [protected]

Protected constructor for wrapping a socket descriptor in an cbits::SSLSocket object.

Parameters:

fd socket descriptor

ctxt SSL context to use for this connection. If not specified, then a global context should have already been set.

Member Function Documentation

void SSLSocket::connect ( ) throw (SocketException) [virtual]

SSLSocket* cbits::SSLSocket::create ( const socket_t fd,

SSLContext *const ctxt = 0

) throw ( SocketException ) [static]

Create a SSL-enabled socket instance from an existing socket file descriptor.
An SSL context must be specified for the new socket.

Returns:
A pointer to a new SSLSocket instance.
Parameters:

fd socket file descriptor

ctxt SSL context to use for this connection. If not specified, then a global context should have already been set.

const SSLPeer & SSLSocket::getPeer ( ) const throw ( SocketException )

Access information about the SSL peer.

Returns:
reference to a SSLPeer instance.

cbits::SSLSocket::operator SSL_PTR ( ) [inline]

Type conversion operator to allow a cbits::SSLSocket instance to be used where an OpenSSL SSL object is required.

const ssize_t SSLSocket::read ( char *const buffer,

const int buflen,

int *const error = 0,

const long int msec = 0

) throw ( SocketException ) [virtual]

const ssize_t SSLSocket::readLine ( std::string & buffer,

const std::string & delim,

int *const error = 0,

const long int msec = 0

) throw ( SocketException ) [virtual]

First try to satisfy the read request from the SSL buffer.
If no data or not enough is returned, then enter the loop below to wait for data on the socket before calling SSL_read again.

const ssize_t SSLSocket::receive ( char *const buffer,

const int buflen,

const long int msec = 0,

int *const error = 0

) throw ( SocketException ) [virtual]

const ssize_t SSLSocket::send ( const char * buffer,

const long buflen,

int *const error = 0,

const long int msec = 0

) throw ( SocketException ) [virtual]

void SSLSocket::set_bio ( const socket_t fd ) throw ( SocketException ) [private]

Wrap the underlying network socket in an OpenSSL socket BIO object.

void SSLSocket::setGlobalContext ( SSLContext * gctx ) throw ( SSLContextException ) [static]

Set a SSL context to be used by ALL new SSLSocket instances.
This may be overridden for individual SSLSocket instances by supplying a different context to the SSLSocket constructor when the SSLSocket is created.
Exceptions:

if an invalid SSL context is supplied.

Parameters:

gctx Global SSL context

const ssize_t SSLSocket::write ( const char * buffer,

const long buflen,

int *const error = 0,

const long int msec = 0

) throw ( SocketException ) [virtual]

Member Data Documentation

BIO* cbits::SSLSocket::_bio [private]

The OpenSSL BIO object that wraps the low-level network socket connection.
This BIO object is in turn wrapped by an OpenSSL SSL object.

CriticalSection cbits::SSLSocket::_csect [private]

Critical section used to synchronize access to non-read/write specific code.

SSLContext* cbits::SSLSocket::_ctxt [private]

The SSL context for this SSL connection.

SSLContext * SSLSocket::_global_ctxt = 0 [static, private]

The global, default SSL context, if set.

SSLPeer* cbits::SSLSocket::_peer [private]

The SSL peer if the SSL connection is complete.

CriticalSection cbits::SSLSocket::_read_csect [private]

Critical section object used to prevent multiple threads from simultaneously reading from this SSL socket.

SSL* cbits::SSLSocket::_ssl [private]

The OpenSSL SSL object representing this SSL connection.

bool cbits::SSLSocket::_ssl_is_connected [protected]

A state flag that is set to true after the SSL handshake has successfully completed.

CriticalSection cbits::SSLSocket::_write_csect [private]

Critical section object used to prevent multiple threads from simultaneously writing to this SSL socket.

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

Generated by

Hosted by

cbits::SSLSocket Class Reference

Public Types

Public Methods

Static Public Methods

Protected Methods

Protected Attributes

Private Methods

Private Attributes

Static Private Attributes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation