decaf::internal::net::ssl::openssl::OpenSSLSocket Class Reference

Wraps a a Normal Socket object and extends or overrides functions in that class to make use of the OpenSSL Socket API. More...

#include <src/main/decaf/internal/net/ssl/openssl/OpenSSLSocket.h>

Inheritance diagram for decaf::internal::net::ssl::openssl::OpenSSLSocket:

[legend]

Public Member Functions
	OpenSSLSocket (OpenSSLParameters *parameters)
	OpenSSLSocket (OpenSSLParameters *parameters, const decaf::net::InetAddress *address, int port)
	OpenSSLSocket (OpenSSLParameters *parameters, const decaf::net::InetAddress *address, int port, const decaf::net::InetAddress *localAddress, int localPort)
	OpenSSLSocket (OpenSSLParameters *parameters, const std::string &host, int port)
	OpenSSLSocket (OpenSSLParameters *parameters, const std::string &host, int port, const decaf::net::InetAddress *localAddress, int localPort)
virtual	~OpenSSLSocket ()
virtual void	connect (const std::string &host, int port, int timeout)
	Connects to the specified destination, with a specified timeout value.If a connection to the remote host is not established within the specified timeout interval than an SocketTimeoutException is thrown. A timeout value of zero is treated as an inifinite timeout. Parameters: host  The host name or IP address of the remote host to connect to. port  The port on the remote host to connect to. timeout  The number of Milliseconds to wait before treating the connection as failed. Exceptions: IOException  Thrown if a failure occurred in the connect. SocketTimeoutException  if the timeout for connection is exceeded. IllegalArguementException  if the timeout value is negative or the endpoint is invalid.
virtual void	close ()
	Closes the Socket.Once closed a Socket cannot be connected or otherwise operated upon, a new Socket instance must be created. Exceptions: IOException  if an I/O error occurs while closing the Socket.
virtual decaf::io::InputStream *	getInputStream ()
	Gets the InputStream for this socket if its connected.The pointer returned is the property of the associated Socket and should not be deleted by the caller.When the returned InputStream is performing a blocking operation and the underlying connection is closed or otherwise broker the read calls will normally throw an exception to indicate the failure.Closing the InputStream will also close the underlying Socket. Returns: The InputStream for this socket. Exceptions: IOException  if an error occurs during creation of the InputStream, also if the Socket is not connected or the input has been shutdown previously.
virtual decaf::io::OutputStream *	getOutputStream ()
	Gets the OutputStream for this socket if it is connected.The pointer returned is the property of the Socket instance and should not be deleted by the caller.Closing the returned Socket will also close the underlying Socket. Returns: the OutputStream for this socket. Exceptions: IOException  if an error occurs during the creation of this OutputStream, or if the Socket is closed or the output has been shutdown previously.
virtual void	shutdownInput ()
	Shuts down the InputStream for this socket essentially marking it as EOF.The stream returns EOF for any calls to read after this method has been called. Exceptions: IOException  if an I/O error occurs while performing this operation.
virtual void	shutdownOutput ()
	Shuts down the OutputStream for this socket, any data already written to the socket will be sent, any further calls to OuputStream::write will throw an IOException. Exceptions: IOException  if an I/O error occurs while performing this operation.
virtual void	setOOBInline (bool value)
	Sets the value of the OOBINLINE for this socket, by default this option is disabled.If enabled the urgent data is read inline on the Socket's InputStream, no notification is give. Returns: true if OOBINLINE is enabled, false otherwise. Exceptions: SocketException  if an error is encountered while performing this operation.
virtual void	sendUrgentData (int data)
	Sends on byte of urgent data to the Socket. Parameters: data  The value to write as urgent data, only the lower eight bits are sent. Exceptions: IOException  if an I/O error occurs while performing this operation.
virtual decaf::net::ssl::SSLParameters	getSSLParameters () const
	Returns an SSLParameters object for this SSLSocket instance.The cipherSuites and protocols vectors in the returned SSLParameters reference will never be empty. Returns: an SSLParameters object with the settings in use for the SSLSocket.
virtual void	setSSLParameters (const decaf::net::ssl::SSLParameters &value)
	Sets the SSLParameters for this SSLSocket using the supplied SSLParameters instance.If the cipherSutes vector in the SSLParameters instance is not empty them the setEnabledCipherSuites method is called with that vector, if the protocols vector in the SSLParameters instance is not empty then the setEnabledProtocols method is called with that vector. If the needClientAuth value or the wantClientAuth value is true then the setNeedClientAuth and setWantClientAuth methods are called respectively with a value of true, otherwise the setWantClientAuth method is called with a value of false. Parameters: value  The SSLParameters instance that is used to update this SSLSocket's settings. Exceptions: IllegalArgumentException  if an error occurs while calling setEnabledCipherSuites or setEnabledProtocols.
virtual std::vector< std::string >	getSupportedCipherSuites () const
	Gets a vector containing the names of all the cipher suites that are supported by this SSLSocket.Normally not all of these cipher suites will be enabled on the Socket. Returns: a vector containing the names of all the supported cipher suites.
virtual std::vector< std::string >	getSupportedProtocols () const
	Gets a vector containing the names of all the protocols that could be enabled for this SSLSocket instance. Returns: a vector containing the names of all the supported protocols.
virtual std::vector< std::string >	getEnabledCipherSuites () const
	Returns a vector containing the names of all the currently enabled Cipher Suites for this SSL Socket. Returns: vector of the names of all enabled Cipher Suites.
virtual void	setEnabledCipherSuites (const std::vector< std::string > &suites)
	Sets the Cipher Suites that are to be enabled on the SSL Socket connection.Each of the named Cipher Suites must appear in the list of supported cipher suites for this connection or an exception will be thrown. Parameters: suites  An Vector of names for all the Cipher Suites that are to be enabled. Exceptions: IllegalArgumentException  if the vector is empty or one of the names is invalid.
virtual std::vector< std::string >	getEnabledProtocols () const
	Returns a vector containing the names of all the currently enabled Protocols for this SSL Socket. Returns: vector of the names of all enabled Protocols.
virtual void	setEnabledProtocols (const std::vector< std::string > &protocols)
	Sets the Protocols that are to be enabled on the SSL Socket connection.Each of the named Protocols must appear in the list of supported protocols suites for this connection or an exception will be thrown. Parameters: protocols  An Vector of names for all the Protocols that are to be enabled. Exceptions: IllegalArgumentException  if the vector is empty or one of the names is invalid.
virtual void	startHandshake ()
	Initiates a handshake for this SSL Connection, this can be necessary for several reasons such as using new encryption keys, or starting a new session.When called for the first time after the socket connects this method blocks until the handshake is completed. The provider is not require to support multiple handshakes and can throw an IOException to indicate an error. Exceptions: IOException  if an I/O error occurs while performing the Handshake
virtual void	setUseClientMode (bool value)
	Determines the mode that the socket uses when a handshake is initiated, client or server.This method must be called prior to any handshake attempts on this Socket, once a handshake has be initiated this socket remains the the set mode; client or server, for the life of this object. Parameters: value  The mode setting, true for client or false for server. Exceptions: IllegalArguementException  if the handshake process has begun and mode is lcoked.
virtual bool	getUseClientMode () const
	Gets whether this Socket is in Client or Server mode, true indicates that the mode is set to Client. Returns: true if the Socket is in Client mode, false otherwise.
virtual void	setNeedClientAuth (bool value)
	Sets the Socket to require that a client authenticate itself by sending a valid Certificate that is trusted by this Server mode socket.This option only applies to sockets in the Server mode.If the option is enabled an the client does not provide a certificate then the handshake is considered failed and the connection is refused. Calling this method resets any previous value for this option as well as clears any value set in the setWantClientAuth method. Parameters: value  The value indicating if a client is required to authenticate itself or not.
virtual bool	getNeedClientAuth () const
	Returns if this socket is configured to require client authentication, true means that is has and that clients that failed to authenticate will be rejected.This option is only useful when the socket is operating in server mode. Returns: true if client authentication is required.
virtual void	setWantClientAuth (bool value)
	Sets the Socket to request that a client authenticate itself by sending a valid Certificate that is trusted by this Server mode socket.This option only applies to sockets in the Server mode.If the option is enabled an the client does not provide a certificate then the handshake is considered to have succeeded, if it does send a certificate and that certificate is invalid the the handshake will fail. Calling this method resets any previous value for this option as well as clears any value set in the setNeedClientAuth method. Parameters: value  The value indicating if a client is requested to authenticate itself or not.
virtual bool	getWantClientAuth () const
	Returns if this socket is configured to request client authentication, true means that is has and that clients that failed to authenticate will be rejected but that cleints that do not send a certificate are not considered to have failed authentication.This option is only useful when the socket is operating in server mode. Returns: true if client authentication is required.
int	read (unsigned char *buffer, int size, int offset, int length)
	Reads the requested data from the Socket and write it into the passed in buffer.
void	write (const unsigned char *buffer, int size, int offset, int length)
	Writes the specified data in the passed in buffer to the Socket.
int	available ()
	Gets the number of bytes in the Socket buffer that can be read without blocking.

---

Detailed Description

Wraps a a Normal Socket object and extends or overrides functions in that class to make use of the OpenSSL Socket API.

Since:

1.0

---

Constructor & Destructor Documentation

decaf::internal::net::ssl::openssl::OpenSSLSocket::OpenSSLSocket

(

OpenSSLParameters *

parameters

)

decaf::internal::net::ssl::openssl::OpenSSLSocket::OpenSSLSocket	(	OpenSSLParameters *	parameters,
		const decaf::net::InetAddress *	address,
		int	port
	)

decaf::internal::net::ssl::openssl::OpenSSLSocket::OpenSSLSocket	(	OpenSSLParameters *	parameters,
		const decaf::net::InetAddress *	address,
		int	port,
		const decaf::net::InetAddress *	localAddress,
		int	localPort
	)

decaf::internal::net::ssl::openssl::OpenSSLSocket::OpenSSLSocket	(	OpenSSLParameters *	parameters,
		const std::string &	host,
		int	port
	)

decaf::internal::net::ssl::openssl::OpenSSLSocket::OpenSSLSocket	(	OpenSSLParameters *	parameters,
		const std::string &	host,
		int	port,
		const decaf::net::InetAddress *	localAddress,
		int	localPort
	)

virtual decaf::internal::net::ssl::openssl::OpenSSLSocket::~OpenSSLSocket

(

)

[virtual]

---

Member Function Documentation

int decaf::internal::net::ssl::openssl::OpenSSLSocket::available

(

)

Gets the number of bytes in the Socket buffer that can be read without blocking.

Returns:

the number of bytes that can be read from the Socket without blocking.

Exceptions:

IOException

if an I/O error occurs while performing this operation.

virtual void decaf::internal::net::ssl::openssl::OpenSSLSocket::close

(

)

[virtual]

Closes the Socket.Once closed a Socket cannot be connected or otherwise operated upon, a new Socket instance must be created.

Exceptions:

IOException

if an I/O error occurs while closing the Socket.

Reimplemented from decaf::net::Socket.

virtual void decaf::internal::net::ssl::openssl::OpenSSLSocket::connect	(	const std::string &	host,
		int	port,
		int	timeout
	)			[virtual]

Connects to the specified destination, with a specified timeout value.If a connection to the remote host is not established within the specified timeout interval than an SocketTimeoutException is thrown. A timeout value of zero is treated as an inifinite timeout.

Parameters:

	host	The host name or IP address of the remote host to connect to.
	port	The port on the remote host to connect to.
	timeout	The number of Milliseconds to wait before treating the connection as failed.

Exceptions:

	IOException	Thrown if a failure occurred in the connect.
	SocketTimeoutException	if the timeout for connection is exceeded.
	IllegalArguementException	if the timeout value is negative or the endpoint is invalid.

Reimplemented from decaf::net::Socket.

virtual std::vector<std::string> decaf::internal::net::ssl::openssl::OpenSSLSocket::getEnabledCipherSuites

(

)

const [virtual]

Returns a vector containing the names of all the currently enabled Cipher Suites for this SSL Socket.

Returns:

vector of the names of all enabled Cipher Suites.

Implements decaf::net::ssl::SSLSocket.

virtual std::vector<std::string> decaf::internal::net::ssl::openssl::OpenSSLSocket::getEnabledProtocols

(

)

const [virtual]

Returns a vector containing the names of all the currently enabled Protocols for this SSL Socket.

Returns:

vector of the names of all enabled Protocols.

Implements decaf::net::ssl::SSLSocket.

virtual decaf::io::InputStream* decaf::internal::net::ssl::openssl::OpenSSLSocket::getInputStream

(

)

[virtual]

Gets the InputStream for this socket if its connected.The pointer returned is the property of the associated Socket and should not be deleted by the caller.When the returned InputStream is performing a blocking operation and the underlying connection is closed or otherwise broker the read calls will normally throw an exception to indicate the failure.Closing the InputStream will also close the underlying Socket.

Returns:

The InputStream for this socket.

Exceptions:

IOException

if an error occurs during creation of the InputStream, also if the Socket is not connected or the input has been shutdown previously.

Reimplemented from decaf::net::Socket.

virtual bool decaf::internal::net::ssl::openssl::OpenSSLSocket::getNeedClientAuth

(

)

const [virtual]

Returns if this socket is configured to require client authentication, true means that is has and that clients that failed to authenticate will be rejected.This option is only useful when the socket is operating in server mode.

Returns:

true if client authentication is required.

Implements decaf::net::ssl::SSLSocket.

virtual decaf::io::OutputStream* decaf::internal::net::ssl::openssl::OpenSSLSocket::getOutputStream

(

)

[virtual]

Gets the OutputStream for this socket if it is connected.The pointer returned is the property of the Socket instance and should not be deleted by the caller.Closing the returned Socket will also close the underlying Socket.

Returns:

the OutputStream for this socket.

Exceptions:

IOException

if an error occurs during the creation of this OutputStream, or if the Socket is closed or the output has been shutdown previously.

Reimplemented from decaf::net::Socket.

virtual decaf::net::ssl::SSLParameters decaf::internal::net::ssl::openssl::OpenSSLSocket::getSSLParameters

(

)

const [virtual]

Returns an SSLParameters object for this SSLSocket instance.The cipherSuites and protocols vectors in the returned SSLParameters reference will never be empty.

Returns:

an SSLParameters object with the settings in use for the SSLSocket.

Reimplemented from decaf::net::ssl::SSLSocket.

virtual std::vector<std::string> decaf::internal::net::ssl::openssl::OpenSSLSocket::getSupportedCipherSuites

(

)

const [virtual]

Gets a vector containing the names of all the cipher suites that are supported by this SSLSocket.Normally not all of these cipher suites will be enabled on the Socket.

Returns:

a vector containing the names of all the supported cipher suites.

Implements decaf::net::ssl::SSLSocket.

virtual std::vector<std::string> decaf::internal::net::ssl::openssl::OpenSSLSocket::getSupportedProtocols

(

)

const [virtual]

Gets a vector containing the names of all the protocols that could be enabled for this SSLSocket instance.

Returns:

a vector containing the names of all the supported protocols.

Implements decaf::net::ssl::SSLSocket.

virtual bool decaf::internal::net::ssl::openssl::OpenSSLSocket::getUseClientMode

(

)

const [virtual]

Gets whether this Socket is in Client or Server mode, true indicates that the mode is set to Client.

Returns:

true if the Socket is in Client mode, false otherwise.

Implements decaf::net::ssl::SSLSocket.

virtual bool decaf::internal::net::ssl::openssl::OpenSSLSocket::getWantClientAuth

(

)

const [virtual]

Returns if this socket is configured to request client authentication, true means that is has and that clients that failed to authenticate will be rejected but that cleints that do not send a certificate are not considered to have failed authentication.This option is only useful when the socket is operating in server mode.

Returns:

true if client authentication is required.

Implements decaf::net::ssl::SSLSocket.

int decaf::internal::net::ssl::openssl::OpenSSLSocket::read	(	unsigned char *	buffer,
		int	size,
		int	offset,
		int	length
	)

Reads the requested data from the Socket and write it into the passed in buffer.

Parameters:

	buffer	The buffer to read into
	size	The size of the specified buffer
	offset	The offset into the buffer where reading should start filling.
	length	The number of bytes past offset to fill with data.

Returns:

the actual number of bytes read or -1 if at EOF.

Exceptions:

	IOException	if an I/O error occurs during the read.
	NullPointerException	if buffer is Null.
	IndexOutOfBoundsException	if offset + length is greater than buffer size.

virtual void decaf::internal::net::ssl::openssl::OpenSSLSocket::sendUrgentData

(

int

data

)

[virtual]

Sends on byte of urgent data to the Socket.

Parameters:

data

The value to write as urgent data, only the lower eight bits are sent.

Exceptions:

IOException

if an I/O error occurs while performing this operation.

Reimplemented from decaf::net::Socket.

virtual void decaf::internal::net::ssl::openssl::OpenSSLSocket::setEnabledCipherSuites

(

const std::vector< std::string > &

suites

)

[virtual]

Sets the Cipher Suites that are to be enabled on the SSL Socket connection.Each of the named Cipher Suites must appear in the list of supported cipher suites for this connection or an exception will be thrown.

Parameters:

suites

An Vector of names for all the Cipher Suites that are to be enabled.

Exceptions:

IllegalArgumentException

if the vector is empty or one of the names is invalid.

Implements decaf::net::ssl::SSLSocket.

virtual void decaf::internal::net::ssl::openssl::OpenSSLSocket::setEnabledProtocols

(

const std::vector< std::string > &

protocols

)

[virtual]

Sets the Protocols that are to be enabled on the SSL Socket connection.Each of the named Protocols must appear in the list of supported protocols suites for this connection or an exception will be thrown.

Parameters:

protocols

An Vector of names for all the Protocols that are to be enabled.

Exceptions:

IllegalArgumentException

if the vector is empty or one of the names is invalid.

Implements decaf::net::ssl::SSLSocket.

virtual void decaf::internal::net::ssl::openssl::OpenSSLSocket::setNeedClientAuth

(

bool

value

)

[virtual]

Sets the Socket to require that a client authenticate itself by sending a valid Certificate that is trusted by this Server mode socket.This option only applies to sockets in the Server mode.If the option is enabled an the client does not provide a certificate then the handshake is considered failed and the connection is refused. Calling this method resets any previous value for this option as well as clears any value set in the setWantClientAuth method.

Parameters:

value

The value indicating if a client is required to authenticate itself or not.

Implements decaf::net::ssl::SSLSocket.

virtual void decaf::internal::net::ssl::openssl::OpenSSLSocket::setOOBInline

(

bool

value

)

[virtual]

Sets the value of the OOBINLINE for this socket, by default this option is disabled.If enabled the urgent data is read inline on the Socket's InputStream, no notification is give.

Returns:

true if OOBINLINE is enabled, false otherwise.

Exceptions:

SocketException

if an error is encountered while performing this operation.

Reimplemented from decaf::net::Socket.

virtual void decaf::internal::net::ssl::openssl::OpenSSLSocket::setSSLParameters

(

const decaf::net::ssl::SSLParameters &

value

)

[virtual]

Sets the SSLParameters for this SSLSocket using the supplied SSLParameters instance.If the cipherSutes vector in the SSLParameters instance is not empty them the setEnabledCipherSuites method is called with that vector, if the protocols vector in the SSLParameters instance is not empty then the setEnabledProtocols method is called with that vector. If the needClientAuth value or the wantClientAuth value is true then the setNeedClientAuth and setWantClientAuth methods are called respectively with a value of true, otherwise the setWantClientAuth method is called with a value of false.

Parameters:

value

The SSLParameters instance that is used to update this SSLSocket's settings.

Exceptions:

IllegalArgumentException

if an error occurs while calling setEnabledCipherSuites or setEnabledProtocols.

Reimplemented from decaf::net::ssl::SSLSocket.

virtual void decaf::internal::net::ssl::openssl::OpenSSLSocket::setUseClientMode

(

bool

value

)

[virtual]

Determines the mode that the socket uses when a handshake is initiated, client or server.This method must be called prior to any handshake attempts on this Socket, once a handshake has be initiated this socket remains the the set mode; client or server, for the life of this object.

Parameters:

value

The mode setting, true for client or false for server.

Exceptions:

IllegalArguementException

if the handshake process has begun and mode is lcoked.

Implements decaf::net::ssl::SSLSocket.

virtual void decaf::internal::net::ssl::openssl::OpenSSLSocket::setWantClientAuth

(

bool

value

)

[virtual]

Sets the Socket to request that a client authenticate itself by sending a valid Certificate that is trusted by this Server mode socket.This option only applies to sockets in the Server mode.If the option is enabled an the client does not provide a certificate then the handshake is considered to have succeeded, if it does send a certificate and that certificate is invalid the the handshake will fail. Calling this method resets any previous value for this option as well as clears any value set in the setNeedClientAuth method.

Parameters:

value

The value indicating if a client is requested to authenticate itself or not.

Implements decaf::net::ssl::SSLSocket.

virtual void decaf::internal::net::ssl::openssl::OpenSSLSocket::shutdownInput

(

)

[virtual]

Shuts down the InputStream for this socket essentially marking it as EOF.The stream returns EOF for any calls to read after this method has been called.

Exceptions:

IOException

if an I/O error occurs while performing this operation.

Reimplemented from decaf::net::Socket.

virtual void decaf::internal::net::ssl::openssl::OpenSSLSocket::shutdownOutput

(

)

[virtual]

Shuts down the OutputStream for this socket, any data already written to the socket will be sent, any further calls to OuputStream::write will throw an IOException.

Exceptions:

IOException

if an I/O error occurs while performing this operation.

Reimplemented from decaf::net::Socket.

virtual void decaf::internal::net::ssl::openssl::OpenSSLSocket::startHandshake

(

)

[virtual]

Initiates a handshake for this SSL Connection, this can be necessary for several reasons such as using new encryption keys, or starting a new session.When called for the first time after the socket connects this method blocks until the handshake is completed. The provider is not require to support multiple handshakes and can throw an IOException to indicate an error.

Exceptions:

IOException

if an I/O error occurs while performing the Handshake

Implements decaf::net::ssl::SSLSocket.

void decaf::internal::net::ssl::openssl::OpenSSLSocket::write	(	const unsigned char *	buffer,
		int	size,
		int	offset,
		int	length
	)

Writes the specified data in the passed in buffer to the Socket.

Parameters:

	buffer	The buffer to write to the socket.
	size	The size of the specified buffer.
	offset	The offset into the buffer where the data to write starts at.
	length	The number of bytes past offset to write.

Exceptions:

	IOException	if an I/O error occurs during the write.
	NullPointerException	if buffer is Null.
	IndexOutOfBoundsException	if offset + length is greater than buffer size.

---

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

• src/main/decaf/internal/net/ssl/openssl/OpenSSLSocket.h