Home

C-Bits Package Documentation

Main Page Namespace List Class Hierarchy Compound List File List Namespace Members Compound Members File Members

cbits::SSLSocket Class Reference

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

#include <SSLSocket.h>

Inheritance diagram for cbits::SSLSocket:

[legend]Collaboration diagram for cbits::SSLSocket:[legend]List of all members.

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)
	Complete (establish) the network connection. More...
virtual const ssize_t	read (char const buffer, const int buflen, int const error=0, const long int msec=0) throw ( SocketException )
	Read data from the network connection into a user-supplied buffer. More...
virtual const ssize_t	receive (char const buffer, const int buflen, const long int msec=0, int const error=0) throw ( SocketException )
	Synonym for cbits::Socket::read with the error* and msec argument positions reversed.* More...
virtual const ssize_t	readLine (std::string &buffer, const std::string &delim, int *const error=0, const long int msec=0) throw ( SocketException )
	Read from the network connection until a specified delimiter string is encountered. More...
virtual const ssize_t	write (const char buffer, const long buflen, int const error=0, const long int msec=0) throw ( SocketException )
	Write a buffer of data to the network connection. More...
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...
virtual const ssize_t	send (const char buffer, const long buflen, const long int msec=0, int const error=0) throw ( SocketException )
	Synonym for cbits::Socket::write with the error* and msec argument positions reversed.* More...
const socket_t	getHandle () const
	Get a handle to the underlying BSD socket connection. More...
std::iostream &	get_iostream () throw (SocketException)
	Get a std::iostream instance that can be used to write to or read from the socket. More...
const struct sockaddr_in &	get_addr () const
	Access the socket address that this cbits::Socket is bound to. More...
virtual const bool	isError () const
	Check the error status of thenetwork connection. More...
const std::string &	getError () const
	Access a human readable description of the socket error condition, if any. More...
virtual const bool	isReadable (long int msec=0, int const error=0) const
	Determine if the socket has data. More...
virtual const bool	isWritable (long int msec=0, int const error=0) const
	Determine if the socket can accept data. More...
	operator std::ostream & ()
	Type conversion operator for when cbits::Socket needs to be used as a std::ostream instance. More...
	operator std::istream & ()
	Type conversion operator for when cbits::Socket needs to be used as a std::istream instance. More...
virtual const bool	set_blocking_on ()
	Configure the network connection such that calls to read data will block if none is available and calls to write data will block if the network connection can not immediately accept the data. More...
virtual const bool	set_blocking_off ()
	set_blocking_off. More...
virtual const int	getSockOpt (const int level, const int op_name, char buffer, int buflen) const
	Access the value of a socket option. More...
std::ostream *	getLogger () const
	Access this Socket's debug logging stream. More...
std::ostream *	getLocalLogger () const
	Access this Sockets individual logging stream, set via cbits::setLocalLogger, if any. More...
void	setLocalLogger (std::ostream *os) const
	Set a instance debug logging stream for this Socket. More...
void	closeLocalLogger () const
	Close this Socket's individually set debug log stream, set via cbits::Socket::setLocalLogger, if any. 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...
Socket *	create (const socket_t s)
	Wrap a pre-existing low-level BSD socket in a cbits::Socket. More...
std::ostream *	getGlobalLogger ()
	Access the global debug logging stream for all Socket instances that don't have an individual logging stream. More...
void	setGlobalLogger (std::ostream *os)
	Set a global debug logging stream to be used by all Socket instances. More...
void	closeGlobalLogger ()
	Close the globally set debug log stream, set via cbits::Socket::setGlobalLogger, if any. 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...
const bool	isAvailable (fd_set rd, fd_set wr, long int msec=0, int error=0) const
	Use the 'select' system call to determine if any of a set of file descriptors are available for reading or writing. More...
Protected Attributes
bool	_ssl_is_connected
	A state flag that is set to true* after the SSL handshake has successfully completed.* More...
socket_t	_sockfd
	The BSD socket descriptor. More...
sockaddr_in	_host
	Address of remote host. More...
int	_port
	Port of remote host application. More...
std::iostream *	_iostream
	<iostream> rep of this Socket. More...
bool	_error
	Last error that occurred. More...
std::string	_errstr
	Human readable descripton of _error. More...
bool	_is_connected
	true if socket is connected. More...
bool	_is_bound
std::ostream *	_llogr
	instance-scoped logging stream. More...
Static Protected Attributes
std::ostream *	_glogr = 0
	class-scoped logging stream. 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
	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

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

virtual cbits::SSLSocket::~SSLSocket ( ) [virtual]

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

cbits::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 Socket::closeGlobalLogger ( ) [static, inherited]

Close the globally set debug log stream, set via cbits::Socket::setGlobalLogger, if any.
Since the output stream supplied to cbits::Socket::setGlobalLogger is externally created, the output stream itself is not closed by this action.

void Socket::closeLocalLogger ( ) const [inherited]

Close this Socket's individually set debug log stream, set via cbits::Socket::setLocalLogger, if any.
Since the output stream supplied to cbits::Socket::setLocalLogger is externally created, the output stream itself is not closed by this action.

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

Complete (establish) the network connection.

Exceptions:

SocketException if the connection could not be established.

Reimplemented from cbits::Socket.

Socket * Socket::create ( const socket_t s ) [static, inherited]

Wrap a pre-existing low-level BSD socket in a cbits::Socket.

Returns:
A pointer to a new cits::Socket instance.
Parameters:

s Pre-existing BSD socket.

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 struct sockaddr_in& cbits::Socket::get_addr ( ) const [inline, inherited]

Access the socket address that this cbits::Socket is bound to.

Returns:
reference to sockaddr_in structure.

std::iostream & Socket::get_iostream ( ) throw (SocketException) [inherited]

Get a std::iostream instance that can be used to write to or read from the socket.
All of the rules related to use of a std::iostream instance apply, including the need to check the stream flags for errors.

Returns:
a std:iostream instance.
Exceptions:

SocketException

FIXME Socket.h why does Socket::get_iostream throw SocketException?

const std::string& cbits::Socket::getError ( ) const [inline, inherited]

Access a human readable description of the socket error condition, if any.
@Returns A non-empty string if an error exists on the socket; otherwise an empty string is returned.

std::ostream * Socket::getGlobalLogger ( ) [static, inherited]

Access the global debug logging stream for all Socket instances that don't have an individual logging stream.
This only accesses the logging stream that is used by Socket instances that haven't been individually configured with their own logging stream via cbits::Socket::setLocalLogger.

Returns:
pointer to std::ostream instance or 0 if no global logger has been set.

const socket_t Socket::getHandle ( ) const [inherited]

Get a handle to the underlying BSD socket connection.

Returns:
socket handle.

std::ostream * Socket::getLocalLogger ( ) const [inherited]

Access this Sockets individual logging stream, set via cbits::setLocalLogger, if any.

Returns:
a pointer to std::ostream, or 0 if not set.

std::ostream * Socket::getLogger ( ) const [inherited]

Access this Socket's debug logging stream.
A pointer to a stream is always returned. Logging statements that use this method should perform runtime checks to determine if application debug logging is enabled.

Returns:
pointer to std::ostream instance.

If the Socket has been configured with an individual logging stream, via cbits::Socket::setLocalLogger, then that logging stream is returned.
If the Socket has no local logger but has a global logging stream, set via setGlobalLogger, then the global stream is returned.
If the socket has neither a local nor a global logging stream set then a pointer to std::cerr is returned.

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

Access information about the SSL peer.

Returns:
reference to a SSLPeer instance.

const int Socket::getSockOpt ( const int level,

const int op_name,

char * buffer,

int * buflen

) const [virtual, inherited]

Access the value of a socket option.

Returns:
0 if successful; otherwise an error code is returned. Under Windows, consult the WINSOCK documentation, and under Unix, consult the 'getsockopt' manpage.
Parameters:

level SOL_SOCKET or IPPROTO_TCP

op_name option value to retrieve

buffer result buffer to save value

buflen length of result buffer

const bool Socket::isAvailable ( fd_set * rd,

fd_set * wr,

long int * msec = 0,

int * error = 0

) const [protected, inherited]

Use the 'select' system call to determine if any of a set of file descriptors are available for reading or writing.

Returns:
true if the socket is available for the action (read or write) specified by the input file descriptor sets.
Parameters:

rdset File descriptor set to check for readability

wrset file descriptor set to check for writability

mmsec The maximum number of milliseconds to wait for any of the descriptors to become available. zero or a negative number is interpreted to mean 'wait forever'.

error An optional pointer to an integer that may hold the errno value of an error that occcurred, if any.

const bool Socket::isError ( ) const [virtual, inherited]

Check the error status of thenetwork connection.
Generally, any error on a cbits::Socket should invalidate it.

Returns:
true if the network is not readable or writable due to an error condition. cbits::Socket::getError may be used to retrieve a human readable description of the error.

virtual const bool cbits::Socket::isReadable ( long int * msec = 0,

int *const error = 0

) const [virtual, inherited]

Determine if the socket has data.
Arguments: -----------
error - optional pointer to an error flag that is updated to a non-zero value if an error occurs during the call.
Returns: ------------ true if the socket is readble (as determined by 'select'); otherwise, false.
Exceptions: ----------- none.
Parameters:

msec An optional pointer to the maximum time to wait for the socket to become readable, in milliseconds. If provided, the method will not block for longer than the time specified and is adjusted for the time remaining (if any) when the call returns. If not specified, the method will block until the socket becomes readable.

error An optional pointer to an integer that may hold the errno value of an error (if any) that occurred during the read.

virtual const bool cbits::Socket::isWritable ( long int * msec = 0,

int *const error = 0

) const [virtual, inherited]

Determine if the socket can accept data.

Returns:
true if the socket is writable; otherwise, false.
Parameters:

msec An optional pointer to the maximum time to wait for the socket to become writable, in milliseconds. If provided, the method will not block for longer than the time specified and is adjusted for the time remaining (if any) when the call returns. If not specified, the method will block until the socket becomes writable.

error An optional pointer to an integer that may hold the errno value of an error (if any) that occurred during the read.

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.

cbits::Socket::operator std::istream & ( ) [inline, inherited]

Type conversion operator for when cbits::Socket needs to be used as a std::istream instance.

cbits::Socket::operator std::ostream & ( ) [inline, inherited]

Type conversion operator for when cbits::Socket needs to be used as a std::ostream instance.

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

const int buflen,

int *const error = 0,

const long int msec = 0

) throw ( SocketException ) [virtual]

Read data from the network connection into a user-supplied buffer.

Returns:
0 if call timed out waiting for data; negative if an error occurred and no data was read (see error argument); otherwise, a positive integer indicating the number of bytes read. Even if data was successfully read from the socket, the error argument should be checked for errors.
Exceptions:

SocketException if any invalid arguments are passed in.

Reimplemented from cbits::Socket.

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

const std::string & delim,

int *const error = 0,

const long int msec = 0

) throw ( SocketException ) [virtual]

Read from the network connection until a specified delimiter string is encountered.
For instance, readLine("\r
") would read from the socket up to the next CR-LF sequence.
set to the specific 'errno' value returned by the OS.

Returns:
0 if no data was read or the call timed out; a negative number if no bytes were read and an error occurred (if so, use the error parameter to determine the error); otherwise, a positive integer is returned indicating the number of bytes read.
Exceptions:

SocketException if an error occurred while reading from the socket.

FIXME Socket.h readLine is not implemented. FIXME Socket.h Is it really necessary for readLine to throw a SocketException?
Reimplemented from cbits::Socket.

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

const int buflen,

const long int msec = 0,

int *const error = 0

) throw ( SocketException ) [virtual]

Synonym for cbits::Socket::read with the error and msec argument positions reversed.

Reimplemented from cbits::Socket.

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

const long buflen,

const long int msec = 0,

int *const error = 0

) throw ( SocketException ) [virtual, inherited]

Synonym for cbits::Socket::write with the error and msec argument positions reversed.

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

const long buflen,

int *const error = 0,

const long int msec = 0

) throw ( SocketException ) [virtual]

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

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

const bool Socket::set_blocking_off ( ) [virtual, inherited]

set_blocking_off.
Configure the network connection such that calls to read data will not block if none is available and calls to write data will not block if the network connection can not immediately accept the data.

Returns:
true if the socket was configured to not block.

const bool Socket::set_blocking_on ( ) [virtual, inherited]

Configure the network connection such that calls to read data will block if none is available and calls to write data will block if the network connection can not immediately accept the data.

Returns:
true if the socket was configured to block.

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

void Socket::setGlobalLogger ( std::ostream * os ) [static, inherited]

Set a global debug logging stream to be used by all Socket instances.
This does not override a Socket instance's specific logging stream if any.
This method is a useful way to provide a default logging stream to all Socket instances, without having to configure each instance separately, but still be able to set the logging stream for specific Socket instances.

void Socket::setLocalLogger ( std::ostream * os ) const [inherited]

Set a instance debug logging stream for this Socket.

Parameters:

os output stream to log to.

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

const long buflen,

int *const error = 0,

const long int msec = 0

) throw ( SocketException ) [virtual]

Write a buffer of data to the network connection.

Returns:
the number of bytes written or a negative number if an error occurred,
Exceptions:

SocketException

FIXME Socket.h does write() really need to throw a SocketException?
Reimplemented from cbits::Socket.

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.

Reimplemented from cbits::Socket.

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

The SSL context for this SSL connection.

bool cbits::Socket::_error [protected, inherited]

Last error that occurred.

std::string cbits::Socket::_errstr [protected, inherited]

Human readable descripton of _error.

SSLContext* cbits::SSLSocket::_global_ctxt [static, private]

The global, default SSL context, if set.

std::ostream * Socket::_glogr = 0 [static, protected, inherited]

class-scoped logging stream.

struct sockaddr_in cbits::Socket::_host [protected, inherited]

Address of remote host.

std::iostream* cbits::Socket::_iostream [protected, inherited]

<iostream> rep of this Socket.

bool cbits::Socket::_is_bound [protected, inherited]

bool cbits::Socket::_is_connected [protected, inherited]

true if socket is connected.

std::ostream* cbits::Socket::_llogr [protected, inherited]

instance-scoped logging stream.

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

The SSL peer if the SSL connection is complete.

int cbits::Socket::_port [protected, inherited]

Port of remote host application.

CriticalSection cbits::SSLSocket::_read_csect [private]

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

Reimplemented from cbits::Socket.

socket_t cbits::Socket::_sockfd [protected, inherited]

The BSD socket descriptor.

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.

Reimplemented from cbits::Socket.

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

SSLSocket.h

Generated by

Hosted by

cbits::SSLSocket Class Reference

Public Types

Public Methods

Static Public Methods

Protected Methods

Protected Attributes

Static Protected Attributes

Private Methods

Private Attributes

Static Private Attributes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation