SourcePro® API Reference Guide

 
Classes | Macros | Typedefs | Enumerations | Functions

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< RWSecureSocketRWSecureSocketAttribute
 

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< RWSecureSocketAttributerwSecureSocketSelect (const RWTValOrderedVector< RWSecureSocketAttribute > &attributes)
 
RWTValOrderedVector< RWSecureSocketAttributerwSecureSocketSelect (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:

1 #if defined(RW_CANNOT_USE_LOW_LEVEL_FUNCTIONS)
2  #warning This program uses cryptographic library functions \
3  directly and it probably should not
4 #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:

1 #if defined (RW_SECSOCK_RNG_NEEDS_SEEDING)
2  RWSecureSocketPackageInit::seedRNGFromFile("seedfile.dat");
3 #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

1 RWSecureSocketPackageInit(WindowsSeedScreen, ErrorStringsFlag)

and the function

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

1 #if defined (RW_SECSOCK_RNG_NEEDS_SEEDING)
2  #if defined (RW_SECSOCK_SEEDRNGFROMSCREEN)
3  RWSecureSocketPackageInit::seedRNGFromScreen();
4  #else
5  RWSecureSocketPackageInit::seedRNGFromFile("seeddata.dat");
6  #endif
7 #endif
#define RW_USE_OPENSSL_LIBRARY

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

Typedef Documentation

A synonym for RWAsymmetricKey.

A synonym for RWAsymmetricKey.

Enumeration Type Documentation

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)

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.

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

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.

Copyright © 2023 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved.