ACE_SSL_Asynch_Stream Class Reference

This class is a factory for initiating asynchronous reads and writes on an SSL stream. More...

#include <SSL_Asynch_Stream.h>

Inheritance diagram for ACE_SSL_Asynch_Stream:

[legend]

Collaboration diagram for ACE_SSL_Asynch_Stream:

[legend]

List of all members.

Public Types
enum	Stream_Type { ST_CLIENT = 0x0001, ST_SERVER = 0x0002 }
Public Member Functions
	ACE_SSL_Asynch_Stream (Stream_Type s_type=ST_SERVER, ACE_SSL_Context *context=0)
	Constructor.
virtual	~ACE_SSL_Asynch_Stream (void)
	Destructor.
int	cancel (void)
int	close (void)
SSL *	ssl (void) const
	Return a pointer to the underlying SSL structure.
int	open (ACE_Handler &handler, ACE_HANDLE handle=ACE_INVALID_HANDLE, const void completion_key=0, ACE_Proactor proactor=0)
int	read (ACE_Message_Block &message_block, size_t num_bytes_to_read, const void *act=0, int priority=0, int signal_number=ACE_SIGRTMIN)
int	write (ACE_Message_Block &message_block, size_t bytes_to_write, const void *act=0, int priority=0, int signal_number=ACE_SIGRTMIN)
Protected Types
enum	Stream_Flag { SF_STREAM_OPEN = 0x0001, SF_REQ_SHUTDOWN = 0x0002, SF_SHUTDOWN_DONE = 0x0004, SF_CLOSE_NTF_SENT = 0x0008, SF_DELETE_ENABLE = 0x0010 }
	Stream state/flags. More...
enum	BIO_Flag { BF_EOS = 0x01, BF_AIO = 0x02 }
Protected Member Functions
virtual ACE_Asynch_Operation_Impl *	implementation (void) const
virtual void	handle_write_stream (const ACE_Asynch_Write_Stream::Result &result)
	virtual from ACE_Handler
virtual void	handle_read_stream (const ACE_Asynch_Read_Stream::Result &result)
virtual void	handle_wakeup (void)
virtual bool	post_handshake_check (void)
void	print_error (int err_ssl, const ACE_TCHAR *pText)
int	pending_BIO_count (void)
int	notify_read (int bytes_transferred, int error)
int	notify_write (int bytes_transferred, int error)
int	notify_close (void)
SSL State Machine

int	do_SSL_state_machine (void)
int	do_SSL_handshake (void)
int	do_SSL_read (void)
int	do_SSL_write (void)
int	do_SSL_shutdown (void)
BIO Helpers

int	ssl_bio_read (char *buf, size_t len, int &errval)
int	ssl_bio_write (const char *buf, size_t len, int &errval)
Protected Attributes
Stream_Type	type_
	Stream Type ST_CLIENT/ST_SERVER.
ACE_Proactor *	proactor_
	The proactor.
ACE_Handler *	ext_handler_
	External,i.e user handler.
ACE_SSL_Asynch_Read_Stream_Result *	ext_read_result_
	External, i.e. read result faked for user.
ACE_SSL_Asynch_Write_Stream_Result *	ext_write_result_
	External, i.e. write result faked for user.
int	flags_
SSL *	ssl_
	The SSL session.
bool	handshake_complete_
	Flag ensures that post_connection_check() is called at most one time.
BIO *	bio_
	The BIO implementation.
ACE_SYNCH_MUTEX	mutex_
	Mutex to protect work.
Internal stream, buffer and info for BIO read

ACE_Asynch_Read_Stream	bio_istream_
ACE_Message_Block	bio_inp_msg_
int	bio_inp_errno_
int	bio_inp_flag_
Internal stream, buffer and info for BIO write

ACE_Asynch_Write_Stream	bio_ostream_
ACE_Message_Block	bio_out_msg_
int	bio_out_errno_
int	bio_out_flag_
Private Member Functions
	ACE_SSL_Asynch_Stream (ACE_SSL_Asynch_Stream const &)
ACE_SSL_Asynch_Stream &	operator= (ACE_SSL_Asynch_Stream const &)
Friends
struct	ACE_SSL_Asynch_Stream_Accessor

Detailed Description

This class is a factory for initiating asynchronous reads and writes on an SSL stream.

Once open() is called, multiple asynchronous read and write operations can be started using this class. The handler object (derived from ACE_Handler) specified in open() will receive completion events for the operations initiated via this class.

Member Enumeration Documentation

enum ACE_SSL_Asynch_Stream::BIO_Flag [protected]

The real streams which work under the ssl connection. BIO performs I/O via this streams

Enumerator:

BF_EOS	End of stream.
BF_AIO	Real AIO in progress.

enum ACE_SSL_Asynch_Stream::Stream_Flag [protected]

Stream state/flags.

Enumerator:

SF_STREAM_OPEN	istream_ open OK
SF_REQ_SHUTDOWN	request to SSL shutdown
SF_SHUTDOWN_DONE	SSL shutdown finished.
SF_CLOSE_NTF_SENT	Close notification sent.
SF_DELETE_ENABLE	Stream can be safely destroyed.

enum ACE_SSL_Asynch_Stream::Stream_Type

Enumerator:

ST_CLIENT
ST_SERVER

Constructor & Destructor Documentation

ACE_SSL_Asynch_Stream::ACE_SSL_Asynch_Stream	(	ACE_SSL_Asynch_Stream::Stream_Type	s_type = `ST_SERVER`,
		ACE_SSL_Context *	context = `0`
	)

Constructor.

context Pointer to an ACE_SSL_Context instance containing the OpenSSL information to be associated with this ACE_SSL_Asynch_Stream. The needed SSL data will be copied before return. Therefore, this object can be reused, modified, or deleted upon return. If a 0 pointer is passed, the ACE_SSL_Context::instance() method will be called to get access to a singleton.

ACE_SSL_Asynch_Stream::~ACE_SSL_Asynch_Stream ( void ) [virtual]

Destructor.

ACE_SSL_Asynch_Stream::ACE_SSL_Asynch_Stream ( ACE_SSL_Asynch_Stream const & ) [private]

Member Function Documentation

int ACE_SSL_Asynch_Stream::cancel ( void )

Reimplemented from ACE_Asynch_Operation.

int ACE_SSL_Asynch_Stream::close ( void )

int ACE_SSL_Asynch_Stream::do_SSL_handshake ( void ) [protected]

int ACE_SSL_Asynch_Stream::do_SSL_read ( void ) [protected]

int ACE_SSL_Asynch_Stream::do_SSL_shutdown ( void ) [protected]

int ACE_SSL_Asynch_Stream::do_SSL_state_machine ( void ) [protected]

int ACE_SSL_Asynch_Stream::do_SSL_write ( void ) [protected]

void ACE_SSL_Asynch_Stream::handle_read_stream ( const ACE_Asynch_Read_Stream::Result & result ) [protected, virtual]

This method is called when BIO read request is completed. It processes the IO completion and calls do_SSL_state_machine().

Reimplemented from ACE_Handler.

void ACE_SSL_Asynch_Stream::handle_wakeup ( void ) [protected, virtual]

This method is called when all SSL sessions are closed and no more pending AIOs exist. It also calls users handle_wakeup().

Reimplemented from ACE_Handler.

void ACE_SSL_Asynch_Stream::handle_write_stream ( const ACE_Asynch_Write_Stream::Result & result ) [protected, virtual]

virtual from ACE_Handler

This method is called when BIO write request is completed. It processes the IO completion and calls do_SSL_state_machine().

Reimplemented from ACE_Handler.

virtual ACE_Asynch_Operation_Impl* ACE_SSL_Asynch_Stream::implementation ( void ) const [inline, protected, virtual]

Virtual from ACE_Asynch_Operation. Since this class is essentially an implementation class, simply return 0.

Implements ACE_Asynch_Operation.

int ACE_SSL_Asynch_Stream::notify_close ( void ) [protected]

This method is called to notify ourself that SSL session is shutdown and that there is no more I/O activity now and in the future.

int ACE_SSL_Asynch_Stream::notify_read	(	int	bytes_transferred,
		int	error
	)			`[protected]`

This method is called to notify user handler when user's read in done.

int ACE_SSL_Asynch_Stream::notify_write	(	int	bytes_transferred,
		int	error
	)			`[protected]`

This method is called to notify user handler when user's write in done.

int ACE_SSL_Asynch_Stream::open	(	ACE_Handler &	handler,
		ACE_HANDLE	handle = `ACE_INVALID_HANDLE`,
		const void *	completion_key = `0`,
		ACE_Proactor *	proactor = `0`
	)

Initializes the factory with information which will be used with each asynchronous call.

handler The ACE_Handler that will be called to handle completions for operations initiated using this factory.
handle The handle that future read/write operations will use.

Return values:

	0	for success.
	-1	for failure; consult `errno` for further information.

Reimplemented from ACE_Asynch_Operation.

ACE_SSL_Asynch_Stream& ACE_SSL_Asynch_Stream::operator= ( ACE_SSL_Asynch_Stream const & ) [private]

int ACE_SSL_Asynch_Stream::pending_BIO_count ( void ) [protected]

bool ACE_SSL_Asynch_Stream::post_handshake_check ( void ) [protected, virtual]

This method will be called after a successful SSL handshake indicating that the peer's certificate chain (if any) has been verified and the key exchange has completed. When a peer certificate is required, this method must be used to perform additional checks beyond the verification performed by OpenSSL.

Check 1:

SSL clients that require a peer certificate must specify SSL_VERIFY_PEER via ACE_SSL_Context::default_verify_mode. If the peer sends an invalid certificate, the SSL handshake will fail; however, if the peer does not send a certificate, the SSL handshake will complete successfully which may not be acceptable. In this case, you must override this method in a subclass and return false if the call to SSL_get_peer_certificate returns null.

Check 2:

An additional post handshake check that you should perform is to verify the certificate's FQDN against the host address you intended to connect to. This check will prevent an attacker from using a certificate signed by your CA to usurp your session. For further info on this check, see the post_connection_check method in Example 5-8 of 'Network Security with OpenSSL' by Viega, et. al.

Return:

false - Terminate the connection. Outstanding IO complete with ERR_CANCELED.

true - Proceed with connection. The default implementation returns true.

void ACE_SSL_Asynch_Stream::print_error	(	int	err_ssl,
		const ACE_TCHAR *	pText
	)			`[protected]`

int ACE_SSL_Asynch_Stream::read	(	ACE_Message_Block &	message_block,
		size_t	num_bytes_to_read,
		const void *	act = `0`,
		int	priority = `0`,
		int	signal_number = `ACE_SIGRTMIN`
	)

Initiates an asynchronous read. If the operation is successfully initiated, the handle_read_stream() method will be called on the ACE_Handler object passed to open() when the operation completes. Data is read into the specified ACE_Message_Block beginning at its write pointer; the block's write pointer is updated to reflect any added data when the operation completes.

message_block The specified ACE_Message_Block will receive any data that is read. Data will be read into the block beginning at the block's write pointer.
num_bytes_to_read The maximum number of bytes to read. The actual amount read may be less.
act ACT which is passed to the completion handler in the result object.
priority Specifies the operation priority. This has an affect on POSIX only. Works like nice in Unix. Negative values are not allowed. 0 means priority of the operation same as the process priority. 1 means priority of the operation is one less than process, and so forth. This parameter has no affect on Win32.
signal_number The POSIX4 real-time signal number to be used for the operation. signal_number ranges from ACE_SIGRTMIN to ACE_SIGRTMAX. This argument is unused on non-POSIX4 systems.

Return values:

	0	for success.
	-1	for failure; consult `errno` for further information.

ACE_BEGIN_VERSIONED_NAMESPACE_DECL ACE_INLINE SSL * ACE_SSL_Asynch_Stream::ssl ( void ) const

Return a pointer to the underlying SSL structure.

int ACE_SSL_Asynch_Stream::ssl_bio_read	(	char *	buf,
		size_t	len,
		int &	errval
	)			`[protected]`

int ACE_SSL_Asynch_Stream::ssl_bio_write	(	const char *	buf,
		size_t	len,
		int &	errval
	)			`[protected]`

int ACE_SSL_Asynch_Stream::write	(	ACE_Message_Block &	message_block,
		size_t	bytes_to_write,
		const void *	act = `0`,
		int	priority = `0`,
		int	signal_number = `ACE_SIGRTMIN`
	)

Initiates an asynchronous write. If the operation is successfully initiated, the handle_write_stream() method will be called on the ACE_Handler object passed to open() when the operation completes. Data is taken from the specified ACE_Message_Block beginning at its read pointer; the block's read pointer is updated to reflect any data successfully sent when the operation completes.

message_block The specified ACE_Message_Block is the source of data that is written. Data will be taken from the block beginning at the block's read pointer.
bytes_to_write The maximum number of bytes to write. The actual amount written may be less.
act ACT which is passed to the completion handler in the result object.
priority Specifies the operation priority. This has an affect on POSIX only. Works like nice in Unix. Negative values are not allowed. 0 means priority of the operation same as the process priority. 1 means priority of the operation is one less than process, and so forth. This parameter has no affect on Win32.
signal_number The POSIX4 real-time signal number to be used for the operation. signal_number ranges from ACE_SIGRTMIN to ACE_SIGRTMAX. This argument is unused on non-POSIX4 systems.

Return values: