RWSecureSocketPackageInit

Module:  Secure Communication Module   Package:  Secure Sockets

Does not inherit

• Local Index
• Header File
• Description
• Enums
• Macros
• Public Constructors
• Destructor
• Public Member Functions

Members

ErrorStringsFlag RWSecureSocketPackageInit() RW_SECSOCK_RNG_NEEDS_SEEDING

RW_SECSOCK_SEEDRNGFROMSCREEN SeedCheck seedRNGFromFile()

seedRNGFromMemory() seedRNGFromScreen() WindowsSeedScreen

~RWSecureSocketPackageInit()

#include <rw/secsock/RWSecureSocketPackageInit.h>

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 RWSecureSocketPackageNotInitalizedError.

---

enum ErrorStringsFlag { errorStringsOff, errorStringsOn };

Determines whether RWSecureSocketPackageInit returns error strings or numeric error codes.

enum SeedCheck { enableSeedCheck, disableSeedCheck };

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

enum WindowsSeedScreen { seedFromScreen };

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

RW_SECSOCK_RNG_NEEDS_SEEDING

Defined if the random number generator for the cryptographic library must be seeded explicitly.

RW_SECSOCK_SEEDRNGFROMSCREEN 

Defined if the function or constructor that seeds the random number generator from screen data is available. Windows only.

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.

Throws RWSecureSocketPackageInitError if the cryptographic library's initialization fails.

RWSecureSocketPackageInit(const RWCString& randFilePath,
                 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 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.

Throws RWSecureSocketPackageInitError if the cryptographic library's initialization fails. Throws RWSecureSocketInvalidFileError if the file supplied does not exist or is otherwise invalid. The RWCString must be encoded as UTF-8.

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. Windows only.

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.

This constructor is available only when the macro RW_SECSOCK_SEEDRNGFROMSCREEN is defined. This constructor or the previous one should be used when the macro RW_SECSOCK_RNG_NEEDS_SEEDING is defined.

~RWSecureSocketPackageInit();

Calls the cryptographic library's cleanup function. Throws RWSecureSocketPackageCleanupError if the cryptographic library's cleanup functions fail.

---

NOTE -- The following random number generator seeding functions should be called before an RWSecureSocketContext object is constructed. These functions are generally only necessary if a non-seeding constructor is used to construct the RWSecureSocketPackageInit object, and you wish to seed the RNG in main() or elsewhere.

---

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

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. Throws RWSecureSocketInvalidFileError 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 
seedRNGFromMemory(const unsigned char* m, size_t nBytes);

Seeds the random number generator with nBytes of memory starting at address m. Throws RWSecureSocketBadMemoryReferenceError if a null pointer is passed to the function.

static void 
seedRNGFromScreen();

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. Windows only.

© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.