Secure Sockets

Module Description

These classes provide a C++ interface to the SSL/TLS protocols implemented by the Open SSL libraries.

Classes
class	RWAsymmetricKey
	Encapsulates the underlying cryptographic library's representation of the asymmetric key. More...
class	RWCertificateKeyMismatchError
	Thrown when the provided RWX509Certificate is not valid for the given RWPrivateKey. More...
class	RWCertificateNotValidError
	Thrown when a provided certificate is not valid. More...
class	RWCertificateOrKeyTooLargeError
	Deprecated. Thrown when the key data is too large to be used. More...
class	RWSecureSocket
	Represents a TCP socket using the SSL/TLS protocols for secure communication. More...
class	RWSecureSocketBadMemoryReferenceError
	Thrown when NULL is passed to a function that needs a valid pointer. More...
class	RWSecureSocketContext
	Represents an SSL/TLS context and is an adapter for the underlying cryptographic library's representation of a secure socket context. More...
class	RWSecureSocketError
	Thrown when a problem occurs while trying to use an RWSecureSocket. More...
class	RWSecureSocketInvalidFileError
	Thrown when a named file does not exist or is invalid. More...
class	RWSecureSocketInvalidMethodError
	Thrown when NULL is passed to the RWSecureSocketMethod constructor. More...
class	RWSecureSocketInvalidSessionId
	Thrown when a session ID that exceeds the maximum allowable length is set. More...
class	RWSecureSocketInvalidSocketError
	Thrown when an invalid socket is used. More...
class	RWSecureSocketListener
	Creates a secure socket listener, which waits on a user-defined socket address for incoming connections. More...
class	RWSecureSocketMethod
	Deprecated. Encapsulates the various TLS/SSL protocol versions. An instance of this class is required to construct an RWSecureSocketContext object. More...
class	RWSecureSocketNoCallbackSpecifiedError
	Thrown when an RWAsymmetricKey is constructed with encrypted key data but no RWPasswordCallback is provided to decrypt the key. More...
class	RWSecureSocketNullCertificateError
	Thrown when the library is unable to provide a valid certificate. More...
class	RWSecureSocketPackageCleanupError
	Thrown when RWSecureSocketPackageInit fails to cleanup the underlying cryptographic library. More...
class	RWSecureSocketPackageInit
	Handles the initialization and cleanup of the underlying cryptographic library. More...
class	RWSecureSocketPackageInitError
	Thrown when RWSecureSocketPackageInit fails to initialize the underlying cryptographic library. More...
class	RWSecureSocketPackageNotInitializedError
	Thrown when there is no valid RWSecureSocketPackageInit instance and an RWSecureSocketContext is constructed. More...
class	RWSecureSocketPortal
	An access point of a reliable byte stream communication channel that utilizes the SSL/TLS protocols for information security. More...
class	RWSecureSocketRNGNotSeededError
	Thrown when the application attempts to construct an RWSecureSocketContext without first initializing the random number generator or disabling seed checking. More...
class	RWSecureSocketSelectError
	Thrown when a problem occurs inside rwSecureSocketSelect(). More...
class	RWSecureSocketSession
	Represents a secure socket session and is used the client side of the SSL/TLS protocol for session reuse. More...
class	RWSecureSocketShutdownError
	Thrown when an attempt to shutdown the SSL/TLS connection fails. More...
class	RWSecureSocketUnderlyingAllocationError
	Thrown when the underlying library fails to allocate memory. More...
class	RWSecureSocketUseCertificateError
	Thrown when the provided RWX509Certificate cannot be set. More...
class	RWSecureSocketUsePrivateKeyError
	Thrown when the provided RWPrivateKey cannot be set or if the RWPrivateKey does not match the provided RWX509Certificate. More...
class	RWSecureSocketVersionError
	Thrown when a specified version number is not valid. More...
class	RWSSLContextLoadVerifyLocationsError
	Thrown when the provided verify locations file exists but cannot be loaded. More...
class	RWSSLContextUnableToSetCipherListError
	Thrown when the provided cypher list cannot be used by the underlying library. More...
class	RWUnableToReadCertificateError
	Thrown when an RWX509Certificate could not be created from the provided data. More...
class	RWUnableToReadPrivateKeyError
	Thrown when an RWAsymmetricKey could not be created from the provided data. More...
class	RWX509Certificate
	Adapter class for the cryptographic library's representation of an X.509 certificate. More...

Macros
#define	RW_CANNOT_USE_LOW_LEVEL_FUNCTIONS
#define	RW_SECSOCK_PRESERVE_ERROR_STACK
#define	RW_SECSOCK_RNG_NEEDS_SEEDING
#define	RW_SECSOCK_SEEDRNGFROMSCREEN
#define	RW_USE_OPENSSL_LIBRARY

Typedefs
typedef RWAsymmetricKey	RWPrivateKey
typedef RWAsymmetricKey	RWPublicKey
typedef RWTSocketAttribute< RWSecureSocket >	RWSecureSocketAttribute

Enumerations
enum	RWSecureSocketProtocolVersion {   RW_UNBOUNDED_VERSION, RW_SSLv2, RW_SSLv3, RW_TLSv1,   RW_TLSv1_1, RW_TLSv1_2, RW_TLSv1_3 }
enum	RWSecureSocketSide { RW_CLIENT_ONLY, RW_SERVER_ONLY, RW_CLIENT_OR_SERVER }
enum	RWSSLShutdownMode { RW_SSL_SHUTDOWN_NORMAL, RW_SSL_SHUTDOWN_QUIET }

Functions
RWTValOrderedVector< RWSecureSocketAttribute >	rwSecureSocketSelect (const RWTValOrderedVector< RWSecureSocketAttribute > &attributes)
RWTValOrderedVector< RWSecureSocketAttribute >	rwSecureSocketSelect (const RWTValOrderedVector< RWSecureSocketAttribute > &, double timeout)

Macro Definition Documentation

#define RW_CANNOT_USE_LOW_LEVEL_FUNCTIONS

Note

This macro is defined only for users whose underlying cryptography library is built as an archive (static) library and who built the Secure Sockets package as a shared (DLL) library. Some users of OpenSSL may have this macro defined. Most OpenSSL users who wish to use dynamic libraries will build both OpenSSL and the Secure Sockets package as dynamic libraries, thus avoiding the definition of this macro, and the problem discussed in "Handling Errors from the Cryptographic Library" section in the Secure Communication Module User's Guide.

This macro is defined automatically when the Secure Sockets package determines that your application should not use the underlying Secure Sockets library simultaneously with the Secure Sockets package. For more information, see "Mixing Calls to the Secure Sockets Package with Calls to the Cryptographic Library" in the Secure Communication Module User's Guide.

This macro should be tested in every program that uses the cryptographic library functions directly:

#if defined(RW_CANNOT_USE_LOW_LEVEL_FUNCTIONS)
  #warning This program uses cryptographic library functions \
           directly and it probably should not
#endif

#define RW_SECSOCK_PRESERVE_ERROR_STACK

This macro can be defined as part of a build configuration to prevent Secure Sockets Package exception classes from clearing the error stack.

#define RW_SECSOCK_RNG_NEEDS_SEEDING

Deprecated:

As of SourcePro 13, RW_SECSOCK_RNG_NEEDS_SEEDING is no longer defined.

This macro is defined automatically when the Secure Sockets package determines that your application must explicitly seed the random number generator.

The seeding function call can be wrapped with this macro to aid in cross-platform software development.

For example, seed the RNG from the file seedfile.dat only if it is necessary:

#if defined (RW_SECSOCK_RNG_NEEDS_SEEDING)
  RWSecureSocketPackageInit::seedRNGFromFile("seedfile.dat");
#endif

#define RW_SECSOCK_SEEDRNGFROMSCREEN

This macro is defined automatically on Windows when the Secure Sockets package determines that your application can seed the random number generator from screen data. This means that your application can call the constructor

RWSecureSocketPackageInit(WindowsSeedScreen, ErrorStringsFlag)

and the function

RWSecureSocketPackageInit::seedRNGFromScreen()

When you use this seeding functionality in your applications, wrap it in RW_SECSOCK_SEEDRNGFROMSCREEN for maximum portability.

If an application must seed the RNG, programs compiled for MS Windows will use screen data, and other platforms will use the file seeddata.dat. The following code block outlines the previously mentioned example:

#if defined (RW_SECSOCK_RNG_NEEDS_SEEDING)
  #if defined (RW_SECSOCK_SEEDRNGFROMSCREEN)
    RWSecureSocketPackageInit::seedRNGFromScreen();
  #else
    RWSecureSocketPackageInit::seedRNGFromFile("seeddata.dat");
  #endif
#endif

#define RW_USE_OPENSSL_LIBRARY

This macro is defined automatically when the underlying cryptographic library is the OpenSSL library.

Typedef Documentation

typedef RWAsymmetricKey RWPrivateKey

A synonym for RWAsymmetricKey.

typedef RWAsymmetricKey RWPublicKey

A synonym for RWAsymmetricKey.

typedef RWTSocketAttribute<RWSecureSocket> RWSecureSocketAttribute

This is a typedef for RWTSocketAttribute<RWSecureSocket>.

See also

rwSecureSocketSelect()

Enumeration Type Documentation

enum RWSecureSocketProtocolVersion

Specifies the SSL/TLS protocol version to use when creating an RWSecureSocketContext.

See also

RWSecureSocketContext::RWSecureSocketContext(RWSecureSocketProtocolVersion, RWSecureSocketProtocolVersion, RWSecureSocketSide)

Enumerator
RW_UNBOUNDED_VERSION	The minimum or maximum supported SSL/TLS version.
RW_SSLv2	SSLv2
RW_SSLv3	SSLv3
RW_TLSv1	TLSv1
RW_TLSv1_1	TLSv1_1
RW_TLSv1_2	TLSv1_2
RW_TLSv1_3	TLSv1_3 (Since OpenSSL 1.1.1)

enum RWSecureSocketSide

Specifies the protocol method to use when creating an RWSecureSocketContext.

See also

RWSecureSocketContext::RWSecureSocketContext(RWSecureSocketProtocolVersion, RWSecureSocketProtocolVersion, RWSecureSocketSide)

Enumerator
RW_CLIENT_ONLY	Indicates the RWSecureSocketContext will call the client method.
RW_SERVER_ONLY	Indicates the RWSecureSocketContext will call the server method.
RW_CLIENT_OR_SERVER	Indicates the RWSecureSocketContext will call the generic method.

enum RWSSLShutdownMode

Specifies whether SSL/TLS connections wait for or ignore the CloseVerify message when shutting down.

See also

RWSecureSocket::setShutdownMode()

Enumerator
RW_SSL_SHUTDOWN_NORMAL	This mode instructs the libraries to send a CloseVerify message to the peer and wait for the peer to respond with a CloseVerify message.
RW_SSL_SHUTDOWN_QUIET	This mode instructs the libraries to ignore the CloseVerify portion of the protocol.

Function Documentation

RWTValOrderedVector<RWSecureSocketAttribute> rwSecureSocketSelect

(

const RWTValOrderedVector< RWSecureSocketAttribute > &

attributes

)

This function helps to perform asynchronous socket input/output operations. It waits for one of the conditions in the user-defined attributes vector to occur, and returns a vector of the conditions that have occurred. If any of the conditions has already occurred when the function is called, it returns immediately.

The attributes parameter is a vector of secure socket attributes. If empty, the program may sleep indefinitely. If one of the attributes refers to an invalid socket, an RWSecureSocketInvalidSocketError exception is thrown. If more than FD_SETSIZE attributes are in the attributes vector, an exception is thrown.

Note

This function operates on the TCP socket underlying the SSL/TLS connection. As a result, you may receive unexpected results. Please see the Secure Communication Module User's Guide for more information.

RWTValOrderedVector<RWSecureSocketAttribute> rwSecureSocketSelect	(	const RWTValOrderedVector< RWSecureSocketAttribute > &	,
		double	timeout
	)

This function helps to perform asynchronous socket input/output operations. It waits for one of the conditions in the user-defined attributes vector to occur, and returns a vector of the conditions that have occurred. If any of the conditions has already occurred when the function is called, it returns immediately.

The attributes parameter is a vector of secure socket attributes. If empty, the program may sleep indefinitely. If one of the attributes refers to an invalid socket, an RWSecureSocketInvalidSocketError exception is thrown. If more than FD_SETSIZE attributes are in the attributes vector, an exception is thrown.

This function is guaranteed to block up to timeout seconds while waiting for a condition to become true. If the parameter has a value less than 0, the method blocks indefinitely waiting for a condition to become true. If the value is greater than LONG_MAX, it will be truncated to LONG_MAX. Note that when using large timeout values, the fractional part may change due to rounding.

Note

This function operates on the TCP socket underlying the SSL/TLS connection. As a result, you may receive unexpected results. Please see the Secure Communication Module User's Guide for more information.