SourcePro® API Reference Guide

 
List of all members | Public Types | Public Member Functions | Static Public Member Functions
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 (ErrorStringsFlag errFlag=errorStringsOn, SeedCheck s=enableSeedCheck)
 
 RWSecureSocketPackageInit (const RWCString &randFile, int nBytes=-1, ErrorStringsFlag errFlag=errorStringsOn)
 
 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

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.

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.

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::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
RWSecureSocketPackageInitErrorThrown if the cryptographic library's initialization fails.
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
RWSecureSocketPackageInitErrorThrown if the cryptographic library's initialization fails.
RWSecureSocketInvalidFileErrorThrown if the file supplied does not exist or is otherwise invalid.
RWSecureSocketPackageInit::~RWSecureSocketPackageInit ( )

Calls the cryptographic library's cleanup function.

Exceptions
RWSecureSocketPackageCleanupErrorThrown if the cryptographic library's cleanup function fails.
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

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
RWSecureSocketInvalidFileErrorThrown 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.
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
RWSecureSocketBadMemoryReferenceErrorThrown if a null pointer is passed to the function.
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.

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