RWSecureSocketPackageInit Class Reference

Handles the initialization and cleanup of the underlying cryptographic library. More...

#include <rw/secsock/RWSecureSocketPackageInit.h>

Public Types
enum	ErrorStringsFlag { errorStringsOff , errorStringsOn }
enum	SeedCheck { enableSeedCheck , disableSeedCheck }
enum	WindowsSeedScreen { seedFromScreen }

Public Member Functions
	RWSecureSocketPackageInit (const RWCString &randFile, int nBytes=-1, ErrorStringsFlag errFlag=errorStringsOn)
	RWSecureSocketPackageInit (ErrorStringsFlag errFlag=errorStringsOn, SeedCheck s=enableSeedCheck)
	RWSecureSocketPackageInit (WindowsSeedScreen s, ErrorStringsFlag errFlag=errorStringsOn)
	~RWSecureSocketPackageInit ()

Static Public Member Functions
static void	seedRNGFromFile (const RWCString &randFile, int nBytes=-1)
static void	seedRNGFromMemory (const unsigned char *m, size_t nBytes)
static void	seedRNGFromScreen ()

Detailed Description

RWSecureSocketPackageInit handles the initialization and cleanup of the underlying cryptographic library. Applications must maintain an active instance of this class during all calls to the Secure Sockets package. The easiest way to do this is to create an instance of RWSecureSocketPackageInit at the beginning of main().

Note

RWSecureSocketPackageInit is not multithread-safe. Multiple threads should not need to access this class. If any thread initializes the package, the initialization is valid across threads.

If you are creating a global instance of RWSecureSocketPackageInit, you must take steps to be sure that the constructor of the global RWSecureSocketPackageInit is called before any other global or static objects that use functions in the Secure Sockets package.

Note

If an instance of RWSecureSocketPackageInit is not in scope when the constructor for class RWSecureSocketContext is called, the Secure Sockets package throws RWSecureSocketPackageNotInitializedError.

Member Enumeration Documentation

ErrorStringsFlag

enum RWSecureSocketPackageInit::ErrorStringsFlag

Specifies the style of error messages generated by the secure socket library.

Enumerator
errorStringsOff	Error messages will contain numeric error codes.
errorStringsOn	Error messages will contain human readable error strings.

SeedCheck

enum RWSecureSocketPackageInit::SeedCheck

Checks RWSecureSocketContext to find out if the internal random number generator has been seeded before performing operations.

Enumerator
enableSeedCheck	The library will verify that the random number generator has been seeded before constructing RWSecureSocketContext object instances.
disableSeedCheck	The library will avoid checking that the random number generator has been seeded.

WindowsSeedScreen

enum RWSecureSocketPackageInit::WindowsSeedScreen

Selects the constructor that seeds the random number generator with the contents of the screen.

Condition:

Available only on the Windows platform if RW_SECSOCK_SEEDRNGFROMSCREEN is defined.

Enumerator
seedFromScreen

Constructor & Destructor Documentation

RWSecureSocketPackageInit() [1/3]

RWSecureSocketPackageInit::RWSecureSocketPackageInit	(	ErrorStringsFlag	errFlag = errorStringsOn,
		SeedCheck	s = enableSeedCheck )

Calls the cryptographic library's initialization functions.

The ErrorStringsFlag parameter determines whether error strings are loaded. If this flag is set to errorStringsOff, only the numeric code for an error is returned to the application. If this flag is set to errorStringsOn (the default), a detailed error message is returned. The SeedCheck parameter specifies whether or not the Secure Sockets package should verify that the internal random number generator is properly seeded.

The constructor for RWSecureSocketContext throws RWSecureSocketRNGNotSeededError unless one of the Secure Sockets package random number generator seeding functions or constructors was used before the construction of the RWSecureSocketContext.

If SeedCheck is set to disableSeedCheck, the check is disabled. The only time this is acceptable is when you intend to seed the random number generator directly using the underlying cryptographic library's functions. If you use the disableSeedCheck flag, but do not seed the random number generator, all secure socket handshakes will fail.

Only users familiar with the cryptographic library should disable the seed check. If you do not fully understand the consequences of disabling seed check, leave it enabled.

Exceptions

RWSecureSocketPackageInitError

Thrown if the cryptographic library's initialization fails.

RWSecureSocketPackageInit() [2/3]

RWSecureSocketPackageInit::RWSecureSocketPackageInit	(	const RWCString &	randFile,
		int	nBytes = -1,
		ErrorStringsFlag	errFlag = errorStringsOn )

Calls the cryptographic library's initialization functions. Also seeds the random number generator with the data in the file named in randFilePath. nBytes bytes of the file are used to seed the random number generator except when this parameter is set to -1. In that case, the entire file is used.

The parameter randFile must be encoded as UTF-8.

The ErrorStringsFlag parameter determines whether or not error strings are loaded. If this flag is set to errorStringsOff, only the numeric code for an error is returned to the application. If this flag is set to errorStringsOn, a detailed error message is returned. The parameter defaults to errorStringsOn.

Exceptions

RWSecureSocketPackageInitError	Thrown if the cryptographic library's initialization fails.
RWSecureSocketInvalidFileError	Thrown if the file supplied does not exist or is otherwise invalid.

~RWSecureSocketPackageInit()

RWSecureSocketPackageInit::~RWSecureSocketPackageInit

(

)

Calls the cryptographic library's cleanup function.

Exceptions

RWSecureSocketPackageCleanupError

Thrown if the cryptographic library's cleanup function fails.

RWSecureSocketPackageInit() [3/3]

RWSecureSocketPackageInit::RWSecureSocketPackageInit	(	WindowsSeedScreen	s,
		ErrorStringsFlag	errFlag = errorStringsOn )

Calls the cryptographic library's initialization functions. Also seeds the random number generator with the contents of the screen. Do not use this constructor in applications that do not use a video display.

The ErrorStringsFlag parameter determines whether error strings are loaded. If this flag is set to errorStringsOff, only the numeric code for an error is returned to the application. If this flag is set to errorStringsOn, a detailed error message is returned. The parameter defaults to errorStringsOn.

Condition:

Available only on the Windows platform if RW_SECSOCK_SEEDRNGFROMSCREEN is defined.

Member Function Documentation

seedRNGFromFile()

static void RWSecureSocketPackageInit::seedRNGFromFile ( const RWCString & randFile, int nBytes = -1 )

static

Seeds the random number generator with the data in the file named in randFile. nBytes bytes of the file are used to seed the random number generator except when this parameter is set to -1. In that case, the entire file is used.

Exceptions

RWSecureSocketInvalidFileError

Thrown if the file supplied does not exist or is otherwise invalid. It is a good idea to pick a file that changes frequently, such as a log file. The RWCString must be encoded as UTF-8.

seedRNGFromMemory()

static void RWSecureSocketPackageInit::seedRNGFromMemory ( const unsigned char * m, size_t nBytes )

static

Seeds the random number generator with nBytes of memory starting at address m.

Exceptions

RWSecureSocketBadMemoryReferenceError

Thrown if a null pointer is passed to the function.

seedRNGFromScreen()

static void RWSecureSocketPackageInit::seedRNGFromScreen ( )

static

Seeds the random number generator with the contents of the screen. Do not use this function in applications that do not use a video display.

Condition:

Available only on the Windows platform if RW_SECSOCK_SEEDRNGFROMSCREEN is defined.