Represents a TCP socket using the SSL/TLS protocols for secure communication. More...

#include <rw/secsock/RWSecureSocket.h>

Inherited by RWSecureSocketPortalImp.

Public Member Functions
	RWSecureSocket (void)

	RWSecureSocket (const RWSockType &type)

	RWSecureSocket (const RWSecureSocketContext &context)

	RWSecureSocket (const RWSecureSocketContext &context, const RWSockType &type)

	RWSecureSocket (const RWSocket &sock, const RWSecureSocketContext &context, const RWSecureSocketSession &session)

	RWSecureSocket (const RWSecureSocketContext &context, const RWSecureSocketSession &session)

	RWSecureSocket (const RWSecureSocket &second)

	~RWSecureSocket (void)

RWSecureSocket	accept (RWSockAddr *addr=0) const

void	bind (const RWSockAddrBase &address)

void	bind (const RWSockAddrBase &address, const RWSecureSocketContext &context)

bool	checkPrivateKey (void) const

void	close (void)

void	closesocket (void)

void	connect (const RWSockAddrBase &addr)

void	connect (const RWSockAddrBase &addr, const RWSecureSocketSession &session)

void	connect (const RWSockAddrBase &addr, const RWSecureSocketContext &context)

void	connect (const RWSockAddrBase &addr, const RWSecureSocketSession &session, const RWSecureSocketContext &context)

RWX509Certificate	getCertificate (void) const

RWSecureSocketConnectionRep	getConnection (void) const

const RWSecureSocketContext &	getContext (void) const

RWInfoCallback	getInfoCallback (void) const

RWX509Certificate	getPeerCertificate (void) const

RWSockAddr	getpeername (void) const

RWSecureSocketSession	getSession (void) const

RWSSLShutdownMode	getShutdownMode (void) const

SOCKET	getSocket (void) const

RWSockAddr	getsockname (void) const

void	getsockopt (int level, int option, void optval, RWSockLenType optlen) const

int	getsockopt (int option) const

RWCString	id (unsigned level=0) const

void	ioctl (long cmd, void *arg) const

void	ioctl (long cmd, int arg) const

int	ioctl (long cmd) const

void	ioctlsocket (long cmd, void *arg) const

void	ioctlsocket (long cmd, int arg) const

int	ioctlsocket (long cmd) const

bool	isValid (void) const

void	listen (const RWSockAddrBase &addr, int backlog=5)

void	listen (const RWSockAddrBase &addr, const RWSecureSocketContext &context, int backlog=5)

void	listen (int backlog=5) const

bool	operator< (const RWSecureSocket &s) const

RWSecureSocket &	operator= (const RWSecureSocket &second)

bool	operator== (const RWSecureSocket &s) const

RWNetBuf	recv (int flags=0) const

int	recv (char buf, int len, int flags=0, RWNetBuf::State state=0) const

RWNetBuf	recvAtLeast (int n) const

int	recvAtLeast (char buf, int len, int n, RWNetBuf::State s=0) const

int	send (const RWCString &buf) const

int	send (const char *buf, int len) const

void	sendAtLeast (const RWCString &buf) const

int	sendAtLeast (const RWCString &buf, int n) const

void	sendAtLeast (const char *buf, int n) const

int	sendAtLeast (const char *buf, int bufLen, int n) const

void	setCertificate (const RWX509Certificate &cert)

void	setCertificateVerifyMode (int mode)

void	setContext (const RWSecureSocketContext &context)

void	setIdentity (const RWX509Certificate &cert, const RWPrivateKey &key)

void	setInfoCallback (RWInfoCallback fun)

void	setPrivateKey (const RWPrivateKey &pkey)

void	setSession (const RWSecureSocketSession &session)

void	setShutdownMode (RWSSLShutdownMode mode)

void	setsockopt (int level, int option, void *optval, int optlen) const

void	setsockopt (int option, int optval) const

void	shutdown (void) const

Related Functions
(Note that these are not member functions.)
typedef void(*	RWInfoCallback) (const SSL *conn, int what, int good)

typedef SSL *	RWSecureSocketConnectionRep

Detailed Description

RWSecureSocket is an abstraction of a TCP socket using the SSL/TLS protocols for secure communication. It was designed to operate similarly to the non-secure RWSocket class.

Constructor & Destructor Documentation

RWSecureSocket::RWSecureSocket ( void )

inline

Sets the socket to an invalid state. You must initialize the instance with a call to connect() or bind() before it can be used.

RWSecureSocket::RWSecureSocket ( const RWSockType & type )

inline

Constructs the underlying socket given the provided socket type. The underlying context is not initialized. You must initialize it with a call to setContext(), or by calling an overload of connect() or bind() that takes an RWSecureSocketContext.

RWSecureSocket::RWSecureSocket ( const RWSecureSocketContext & context )

Creates an RWSecureSocket from an existing secure socket context.

Exceptions

RWSecureSocketUnderlyingAllocationError Thrown if the cryptographic library cannot allocate memory.

RWSecureSocket::RWSecureSocket	(	const RWSecureSocketContext &	context,
		const RWSockType &	type
	)

Creates an RWSecureSocket from an existing secure socket context, and initializes the underlying socket from the provided type.

RWSecureSocket::RWSecureSocket	(	const RWSocket &	sock,
		const RWSecureSocketContext &	context,
		const RWSecureSocketSession &	session
	)

Creates an RWSecureSocket from an RWSocket and an RWSecureSocketSession. Assumes the socket is already connected. Closes the socket on error.

Note: sock should not be used directly after constructing an RWSecureSocket with it. If an error occurs while constructing the RWSecureSocket, the underlying socket will be closed.

Exceptions

RWSecureSocketUnderlyingAllocationError Thrown if the cryptographic library cannot allocate memory.

RWSecureSocket::RWSecureSocket	(	const RWSecureSocketContext &	context,
		const RWSecureSocketSession &	session
	)

Creates an RWSecureSocket from an existing session and secure socket context.

Exceptions

RWSecureSocketUnderlyingAllocationError Thrown if the cryptographic library cannot allocate memory.

RWSecureSocket::RWSecureSocket ( const RWSecureSocket & second )

Performs a shallow copy – new memory is not allocated, only the pointer addresses are copied.

RWSecureSocket::~RWSecureSocket ( void )

Destructor.

Member Function Documentation

RWSecureSocket RWSecureSocket::accept ( RWSockAddr * addr = 0 ) const

Accepts a connection that is waiting at this socket. A queue for incoming connections must first be created using listen(). If addr is non-null, returns the peer's address in addr. You can also get the peer's address by calling getpeername() on the returned RWSecureSocket.

If the socket is set to block (the default), accept() blocks until a connection request arrives. If the socket is set to be non-blocking, accept() returns directly. If no connections were available, the returned socket is invalid and *addr is unchanged. Use isValid() to check the returned socket.

Exceptions

RWSecureSocketUnderlyingAllocationError Thrown if the cryptographic library cannot allocate memory.

void RWSecureSocket::bind ( const RWSockAddrBase & address )

Assigns an address to an as-yet unnamed socket. Used primarily by servers, which need to specify the port on which they wait for connections.

Note: When the bind() member function is invoked on an uninitialized socket, the function initializes the socket and sets the SO_REUSEADDR option on the socket. If you do not want this option to be set, call the RWSecureSocket(const RWSockType&) member function to initialize the socket before you invoke bind(). See section "Socket Security" under Chapter 8, "The Windows Socket Adapter" in the Essential Networking Module User's Guide for more information.

void RWSecureSocket::bind	(	const RWSockAddrBase &	address,
		const RWSecureSocketContext &	context
	)

Assigns an address to an as-yet unnamed socket. Used primarily by servers, which need to specify the port on which they wait for connections.

Note: When the bind() member function is invoked on an uninitialized socket, the function initializes the socket and sets the SO_REUSEADDR option on the socket. If you do not want this option to be set, call the RWSecureSocket(const RWSockType&) member function to initialize the socket before you invoke bind(). See section "Socket Security" under Chapter 8, "The Windows Socket Adapter" in the Essential Networking Module User's Guide for more information.

bool RWSecureSocket::checkPrivateKey ( void ) const

inline

Checks that the certificate and the private key set against the SSL connection match. Returns true if the keys match, false otherwise.

void RWSecureSocket::close ( void )

Terminates this connection and removes the socket. If an SSL connection was ever established, close() blocks until the SSL connection is shut down. The underlying socket is then set to an invalid state. If this is the only file descriptor in the process using this socket, the resources used to maintain the socket are deallocated and any unread data is discarded.

Exceptions

RWSocketError	Thrown if the underlying socket is not connected or does not refer to a valid socket.
RWSecureSocketShutdownError	Thrown if an error has occurred at the protocol level or a connection failure occurred.
RWSecureSocketError	Thrown if the underlying secure socket is not connected or does not refer to a valid secure socket.

void RWSecureSocket::closesocket ( void )

Alias for close().

void RWSecureSocket::connect ( const RWSockAddrBase & addr )

Connects this socket to the remote address addr, using context if specified, and attempting to reuse session if specified. If the socket has not been initialized, connect() initializes it.

Exceptions

RWSecureSocketUnderlyingAllocationError Thrown if the cryptographic library cannot allocate memory.

Note: Any failure causes a bound socket to be closed.

void RWSecureSocket::connect	(	const RWSockAddrBase &	addr,
		const RWSecureSocketSession &	session
	)

Connects this socket to the remote address addr, using context if specified, and attempting to reuse session if specified. If the socket has not been initialized, connect() initializes it.

Exceptions

RWSecureSocketUnderlyingAllocationError Thrown if the cryptographic library cannot allocate memory.

Note: Any failure causes a bound socket to be closed.

void RWSecureSocket::connect	(	const RWSockAddrBase &	addr,
		const RWSecureSocketContext &	context
	)

Connects this socket to the remote address addr, using context if specified, and attempting to reuse session if specified. If the socket has not been initialized, connect() initializes it.

Exceptions

RWSecureSocketUnderlyingAllocationError Thrown if the cryptographic library cannot allocate memory.

Note: Any failure causes a bound socket to be closed.

void RWSecureSocket::connect	(	const RWSockAddrBase &	addr,
		const RWSecureSocketSession &	session,
		const RWSecureSocketContext &	context
	)

Connects this socket to the remote address addr, using context if specified, and attempting to reuse session if specified. If the socket has not been initialized, connect() initializes it.

Exceptions

RWSecureSocketUnderlyingAllocationError Thrown if the cryptographic library cannot allocate memory.

Note: Any failure causes a bound socket to be closed.

RWX509Certificate RWSecureSocket::getCertificate ( void ) const

After establishing a connection, returns the certificate presented by the application at the other end of the SSL connection.

Exceptions

RWSecureSocketNullCertificateError Thrown when the underlying function fails.

RWSecureSocketConnectionRep RWSecureSocket::getConnection ( void ) const

inline

Returns the connection pointer.

const RWSecureSocketContext& RWSecureSocket::getContext ( void ) const

Returns a reference to the context used to create the secure socket connection.

Exceptions

RWSecureSocketInvalidSocketError Thrown when the socket is invalid.

RWInfoCallback RWSecureSocket::getInfoCallback ( void ) const

Returns the current information callback for the current connection.

RWX509Certificate RWSecureSocket::getPeerCertificate ( void ) const

If a connection is established, returns the certificate the peer is using. A peer certificate does not exist if the process is a server and is not performing client authentication.

Exceptions

RWSecureSocketNullCertificateError Thrown when the underlying function fails.

RWSockAddr RWSecureSocket::getpeername ( void ) const

Returns the address of the peer connected to this socket.

RWSecureSocketSession RWSecureSocket::getSession ( void ) const

Returns one of the following:

If an SSL connection is active (connect has been called), getSession(), returns the active session associated with this RWSecureSocket.
- TLSv1.3 sessions are not established until after main handshake. A valid session ticket is obtained by the client after recv() has been called.
If an SSL connection is not active and this RWSecureSocket has never been connected, getSession(), returns an invalid session.
If an SSL connection is not active but this RWSecureSocket has been connected before, getSession(), returns the session used for the previous connection.

Applications should check the returned RWSecureSocketSession for validity using RWSecureSocketSession::isValid().

RWSSLShutdownMode RWSecureSocket::getShutdownMode ( void ) const

Gets the current shutdown mode for this RWSecureSocket.

SOCKET RWSecureSocket::getSocket ( void ) const

inline

Returns the C API socket descriptor encapsulated by this RWSecureSocket.

RWSockAddr RWSecureSocket::getsockname ( void ) const

Returns the address that the socket is bound to.

void RWSecureSocket::getsockopt	(	int	level,
		int	option,
		void *	optval,
		RWSockLenType *	optlen
	)		const

Returns the socket option setting. The single-argument version is intended for the usual case, which is the SOL_SOCKET level and an integer option.

int RWSecureSocket::getsockopt ( int option ) const

Returns the socket option setting. The single-argument version is intended for the usual case, which is the SOL_SOCKET level and an integer option.

RWCString RWSecureSocket::id ( unsigned level = 0 ) const

Returns a string identifying the local and (if applicable) foreign addresses of this socket. Increasing level increases the amount of detail in the output. The returned string format depends on the underlying address types.

void RWSecureSocket::ioctl	(	long	cmd,
		void *	arg
	)		const

Gets or retrieves socket operating parameters.

void RWSecureSocket::ioctl	(	long	cmd,
		int	arg
	)		const

Gets or retrieves socket operating parameters. This overload is useful for commands that expect an integer argument and return nothing (such as FIONBIO).

This function is commonly used to set blocking or non-blocking mode on a socket. To set a socket to non-blocking, use ioctl(FIONBIO,1). To set to blocking, use ioctl(FIONBIO,0).

Note: You can also use the global functions rwSetBlocking() and rwSetNonBlocking() to set the blocking mode on an RWSecureSocket.

int RWSecureSocket::ioctl ( long cmd ) const

Gets or sets socket operating parameters. This overload is useful for commands that return ints (like FIONREAD or SIOCATMARK).

void RWSecureSocket::ioctlsocket	(	long	cmd,
		void *	arg
	)		const

Alias for ioctl().

void RWSecureSocket::ioctlsocket	(	long	cmd,
		int	arg
	)		const

Alias for ioctl()

int RWSecureSocket::ioctlsocket ( long cmd ) const

Alias for ioctl()

bool RWSecureSocket::isValid ( void ) const

Checks if the socket is ready for use. Returns true if ready, false if otherwise void.

void RWSecureSocket::listen	(	const RWSockAddrBase &	addr,
		int	backlog = `5`
	)

Prepares a socket to accept incoming connections. The backlog parameter sets the number of incoming connection requests that the protocol software will enqueue while a connection is being processed.

Note: When the listen() member function is invoked on an uninitialized socket, the function initializes the socket and sets the SO_REUSEADDR option on the socket. If you do not want this option to be set, call the RWSecureSocket(const RWSockType&) member function to initialize the socket before you invoke listen(). See section "Socket Security" under Chapter 8, "The Windows Socket Adapter" in the Essential Networking Module User's Guide for more information.

void RWSecureSocket::listen	(	const RWSockAddrBase &	addr,
		const RWSecureSocketContext &	context,
		int	backlog = `5`
	)

Prepares a socket to accept incoming connections. The backlog parameter sets the number of incoming connection requests that the protocol software will enqueue while a connection is being processed.

Note: When the listen() member function is invoked on an uninitialized socket, the function initializes the socket and sets the SO_REUSEADDR option on the socket. If you do not want this option to be set, call the RWSecureSocket(const RWSockType&) member function to initialize the socket before you invoke listen(). See section "Socket Security" under Chapter 8, "The Windows Socket Adapter" in the Essential Networking Module User's Guide for more information.

void RWSecureSocket::listen ( int backlog = 5 ) const

Prepares a bound socket to accept incoming connections. The backlog parameter sets the number of incoming connection requests that the protocol software will enqueue while a connection is being processed.

bool RWSecureSocket::operator< ( const RWSecureSocket & s ) const

Does nothing; declared but not defined. Causes a linker error if the call is attempted. Included to accommodate compilers that resolve all template instantiation at compile time.

RWSecureSocket& RWSecureSocket::operator= ( const RWSecureSocket & second )

Assignment operator.

bool RWSecureSocket::operator== ( const RWSecureSocket & s ) const

Returns true if the two sockets refer to the same underlying communications channel.

RWNetBuf RWSecureSocket::recv ( int flags = 0 ) const

Reads data from a connected socket. The flags parameter must be either 0 or MSG_PEEK; other flags do not apply to secure sockets.

The variant using an explicit buffer, or buf, returns the number of bytes actually received, which may be 0 for a non-blocking socket with no data waiting or for an end of file. The optional state parameter is set to RWNetBuf::eof when end of file is detected, RWNetBuf::normal otherwise. You must use this parameter to detect end of file when using an explicit buffer. You can only "return" in a return value, not a parameter.

Exceptions

RWSecureSocketError Thrown if the flags parameter is set to something other than 0 or MSG_PEEK.

int RWSecureSocket::recv	(	char *	buf,
		int	len,
		int	flags = `0`,
		RWNetBuf::State *	state = `0`
	)		const

Reads data from a connected socket. The flags parameter must be either 0 or MSG_PEEK; other flags do not apply to secure sockets.

The variant using an explicit buffer, or buf, returns the number of bytes actually received, which may be 0 for a non-blocking socket with no data waiting or for an end of file. The optional state parameter is set to RWNetBuf::eof when end of file is detected, RWNetBuf::normal otherwise. You must use this parameter to detect end of file when using an explicit buffer. You can only "return" in a return value, not a parameter.

Exceptions

RWSecureSocketError Thrown if the flags parameter is set to something other than 0 or MSG_PEEK.

RWNetBuf RWSecureSocket::recvAtLeast ( int n ) const

Guaranteed either to receive n characters or throw an exception. This call is only valid for stream sockets. Implemented as a loop calling recv() until all data has been received. If an error is returned from the underlying recv() call, a RWSecureSocketError is thrown. If no data is read, a RWNetCantRecvError is thrown.

int RWSecureSocket::recvAtLeast	(	char *	buf,
		int	len,
		int	n,
		RWNetBuf::State *	s = `0`
	)		const

Guaranteed either to receive n characters or throw an exception. This call is only valid for stream sockets. Implemented as a loop calling recv() until all data has been received. If an error is returned from the underlying recv() call, a RWSecureSocketError is thrown. If no data is read, a RWNetCantRecvError is thrown.

int RWSecureSocket::send ( const RWCString & buf ) const

Sends data from a connected socket, and returns the number of bytes sent. The number of bytes is 0 if the socket is non-blocking and the internal buffer for the socket is full.

int RWSecureSocket::send	(	const char *	buf,
		int	len
	)		const

Sends data from a connected socket, and returns the number of bytes sent. The number of bytes is 0 if the socket is non-blocking and the internal buffer for the socket is full.

void RWSecureSocket::sendAtLeast ( const RWCString & buf ) const

Guaranteed to send at least n characters or the entire buffer, if your application does not specify n. This call is only valid for stream sockets. Implemented as a loop calling send() to send the data.

int RWSecureSocket::sendAtLeast	(	const RWCString &	buf,
		int	n
	)		const

Guaranteed to send at least n characters or the entire buffer, if your application does not specify n. This call is only valid for stream sockets. Implemented as a loop calling send() to send the data.

void RWSecureSocket::sendAtLeast	(	const char *	buf,
		int	n
	)		const

Guaranteed to send at least n characters or the entire buffer, if your application does not specify n. This call is only valid for stream sockets. Implemented as a loop calling send() to send the data.

int RWSecureSocket::sendAtLeast	(	const char *	buf,
		int	bufLen,
		int	n
	)		const

Guaranteed to send at least n characters or the entire buffer, if your application does not specify n. This call is only valid for stream sockets. Implemented as a loop calling send() to send the data.

void RWSecureSocket::setCertificate ( const RWX509Certificate & cert )

Binds a certificate to the secure socket connection. A certificate loaded via this function is used to identify the owner of the secure socket connection. The certificate must be loaded before the SSL connection can successfully respond to a certificate request.

Exceptions

RWSecureSocketUseCertificateError Thrown when the underlying call fails.

Note: If the setCertificate() function is called before setPrivateKey(), the cryptographic library automatically compares the key and the certificate. If the key does not match the certificate, setPrivateKey() throws RWSecureSocketUsePrivateKeyError. This exception is not thrown if setPrivateKey() is called before setCertificate(), even if the key does not match the certificate. In any case, if the key does not match the certificate, checkPrivateKey() returns false.

void RWSecureSocket::setCertificateVerifyMode ( int mode )

Sets the certificate verify mode. Options may be combined with the bitwise-or operator. Allowable values for the mode parameter are shown in the table below.

Value	Description
`SSL_VERIFY_NONE`	Ignores results of certificate verification (Not Recommended)
`SSL_VERIFY_PEER`	Verify the other end of the connection
`SSL_VERIFY_CLIENT_ONCE`	Ensures that when attempting to reuse a session, a client certificate will not be re-requested if one has previously been sent to the server.
`SSL_VERIFY_FAIL_IF_NO_PEER_CERT`	Ensures that the verification fails if the peer does not provide a certificate. (This option is most often used by servers requesting client verification)

void RWSecureSocket::setContext ( const RWSecureSocketContext & context )

Sets the secure socket context for the socket. A socket must be associated with a context before it can be used.

Exceptions

RWSecureSocketUnderlyingAllocationError Thrown if the cryptographic library is unsuccessful in allocating memory.

void RWSecureSocket::setIdentity	(	const RWX509Certificate &	cert,
		const RWPrivateKey &	key
	)

A convenience function that should be used by the side of the SSL/TLS protocol that is being authenticated. Normally this function is called by the server. If client authentication is used, this function is also called by the client to establish its own identity. Calling setIdentity() is equivalent to calling setPrivateKey(pkey), setCertificate(cert), and checkPrivateKey().

Exceptions

RWCertificateKeyMismatchError Thrown if checkPrivateKey() returns false.

void RWSecureSocket::setInfoCallback ( RWInfoCallback fun )

Sets the current information callback for the current connection. For more information, see the Secure Communication Module User's Guide.

void RWSecureSocket::setPrivateKey ( const RWPrivateKey & pkey )

Sets the private key to use for a given secure socket connection.

void RWSecureSocket::setSession ( const RWSecureSocketSession & session )

Sets the current session.

void RWSecureSocket::setShutdownMode ( RWSSLShutdownMode mode )

Sets the shutdown mode. When an SSL/TLS connection is about to be shut down and the shutdown mode is RWSSLShutdownMode::RW_SSL_SHUTDOWN_NORMAL (the default), the side of the protocol initiating the shutdown sends a CloseVerify message to its peer and waits for the peer to respond with a CloseVerify message.

See also: RWSSLShutdownMode.

Some SSL/TLS libraries incorrectly implement the shutdown protocol. To enable interoperability with these libraries, set the shutdown mode to RWSSLShutdownMode::RW_SSL_SHUTDOWN_QUIET. This mode instructs the libraries to ignore the CloseVerify portion of the protocol.

The shutdown mode set with this function applies to all sockets and portals created with this RWSecureSocket.

void RWSecureSocket::setsockopt	(	int	level,
		int	option,
		void *	optval,
		int	optlen
	)		const

Sets a socket option setting. The two-argument function is intended for the usual case, which is the SOL_SOCKET level and an integer option.

void RWSecureSocket::setsockopt	(	int	option,
		int	optval
	)		const

Sets a socket option setting. The two-argument function is intended for the usual case, which is the SOL_SOCKET level and an integer option.

void RWSecureSocket::shutdown ( void ) const

Shuts down the SSL connection. The socket is not shut down or closed and resources are not deallocated. Use close() or closesocket() to deallocate these resources.

Exceptions

RWSocketError	Thrown if the underlying socket is not connected or does not refer to a valid socket.
RWSecureSocketShutdownError	Thrown if an error has occurred at the protocol level or a connection failure occurred.
RWSecureSocketError	Thrown if the underlying secure socket is not connected or does not refer to a valid secure socket.

Friends And Related Function Documentation

typedef void(* RWInfoCallback) (const SSL *conn, int what, int good)

Parameters

conn	The secure socket connection.
what	The current SSL protocol state.
good	The condition of the connection within the given protocol state.

typedef SSL* RWSecureSocketConnectionRep

SourcePro® API Reference Guide

Public Member Functions

Related Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation