RSA BSAFE Cert-C

In this case, they are the Cert-C Default Cryptographic service provider's functions. Use S_InitializeDefaultCSP() or S_InitializeDefaultCSP2() to initialize funcs's crypto function pointer to the Cert-C Default Cryptographic service provider's implementation of CRYPTO_FUNCS.

00100 typedef struct crypto_funcs {
00110   void (*Finalize) (
00111     CERTC_CTX       ctx,                /* Cert-C context */
00112     POINTER         handle);            /* provider handle */
00113 
00114   /* This function returns the crypto service-provider's Crypto-C "chooser."
00115      Typically this will be a session chooser created during provider
00116      initialization by calling B_CreateSessionChooser.
00117   */
00159   int (*GetChooser) (
00160     CERTC_CTX            ctx,           /* Cert-C context */
00161     POINTER              handle,        /* provider handle */
00162     B_ALGORITHM_CHOOSER *chooser);      /* Crypto-C chooser */
00163 
00164   /* This function returns an initialized random object. The application
00165      can call B_GenerateRandomBytes immediately. */
00224   int (*GetRandomObject) (
00225     CERTC_CTX       ctx,                /* Cert-C context */
00226     POINTER         handle,             /* provider handle */
00227     B_ALGORITHM_OBJ *randomObj);        /* Crypto-C random algorithm object */
00228 
00229   /* This function is called periodically by Cert-C. It gives the crypto
00230      service-provider an opportunity to gather "random" bits of information
00231      from the operating environment. A software emulation of a "harware" random
00232      number generator might add the collected "random" bits to an internal
00233      pool. A true hardware random number generator would probably ignore calls
00234      to this routine.
00235 
00236      This routine is called relatively frequently, and must return quickly. to
00237      avoid introducing undue overhead to Cert-C operations.
00238   */
00268   void (*UpdateRandom) (
00269     CERTC_CTX       ctx,                /* Cert-C context */
00270     POINTER         handle);            /* provider handle */
00271 
00272 } CRYPTO_FUNCS;

Field Documentation (alphabetical)

void(* crypto_funcs::Finalize)( CERTC_CTX ctx, POINTER handle)

Cleans up resources associated with the specified service provider handle, including freeing memory allocated during service provider initialization. This function is implemented by the Cert-C Default Cryptographic Service Provider.

int(* crypto_funcs::GetChooser)( CERTC_CTX ctx, POINTER handle, B_ALGORITHM_CHOOSER *chooser)

Obtains the service provider's Crypto-C session chooser. Typically, Cert-C creates this session chooser by calling the B_CreateSessionChooser function during the service provider's initialization.

The session chooser contains the bindings between high-level cryptographic operations, such as signing with MD5 and RSA, and the low-level algorithm methods, such as MD5 digest operations and RSA private key operations. The session chooser also binds in cryptographic hardware so it can be used by the high-level operations. On some Intel platforms, this includes a hardware random number generator. On some Microsoft platforms (for example, Windows NT and Windows 95/98 with IE 4.01 or later), this includes the ability to use keys and certificates that reside in the Microsoft CryptoAPI subsystem. Do not destroy or free the session chooser parameter; it will be destroyed and freed when you call the C_FinalizeCertC() function.

This function is implemented by the Cert-C Default Cryptographic Service Provider.

Parameters:

ctx	This input parameter points to an initialized Cert-C context handle.
handle	This input parameter points to a copy of the handle returned by the service provider's initialization function.
chooser	This output parameter returns an initialized Crypto-C algorithm method.

Returns:: This function returns zero if it is successful; otherwise, it returns a Cert-C error code.

int(* crypto_funcs::GetRandomObject)( CERTC_CTX ctx, POINTER handle, B_ALGORITHM_OBJ *randomObj)

Returns an initialized random object. The random object returned has been seeded, if necessary. Cert-C calls GetRandomObject periodically to give the service provider an opportunity to gather random bits of information from the operating environment.

Call the B_GenerateRandomBytes function immediately after calling the GetRandomObject function.
Do not destroy the random object returned in randomObj; it will be destroyed and freed when you call C_FinalizeCertC().

The random number object uses the AI_X962Random_V0 pseudo-random number generation algorithm. If a seed is supplied in the initialization parameters, the Cert-C Default Cryptographic service provider uses this seed to initialize the pseudo-random number object. If a seed is not provided, and if the OS platform supports the Intel random number generator, the service provider initializes the pseudo-random number object with 128 bytes generated by the hardware. If a seed is not provided, and no hardware random number generator is available, the service provider collects platform-specific OS information (for example, from a number of timers, performance counters, window and input cursor statistics) and uses this information to seed the pseudo-random number generator.

This function is implemented by the Cert-C Default Cryptographic Service Provider.

Parameters:

ctx	This input parameter points to an initialized Cert-C context handle.
handle	This input parameter points to a copy of the handle returned by the service provider's initialization function.
randomObj	This output parameter is the initialized Crypto-C random object. The GetRandomObject function initializes this object with a suitable random number generation algorithm. The service provider is also responsible for updating the object with any random seed information required by the random number generation algorithm.

Returns:: This function returns zero if it is successful; otherwise, it returns a Cert-C error code.

void(* crypto_funcs::UpdateRandom)( CERTC_CTX ctx, POINTER handle)

Gathers unpredictable information from the operating environment and uses the information to update an internal pseudo-random number generator. Use the C_GetRandomObject() function to call the Cert-C Default Cryptographic service provider's UpdateRandom function.

If the random number seed is obtained from platform- specific OS information, UpdateRandom collects a subset of that information and updates the pseudo-random object with the new data. The information subset is chosen from the data that is most likely to have changed since the last call to UpdateRandom.

This function is implemented by the Cert-C Default Cryptographic Service Provider.

Parameters:

ctx	This input parameter points to an initialized Cert-C context handle.
handle	This input parameter points to a copy of the handle returned by the service provider's initialization function.

Returns:: None.

Data Fields
void(*	Finalize )(CERTC_CTX ctx, POINTER handle)
	Cleans up resources associated with the specified service provider handle, including freeing memory allocated during service provider initialization. More...
int(*	GetChooser )(CERTC_CTX ctx, POINTER handle, B_ALGORITHM_CHOOSER *chooser)
	Obtains the service provider's Crypto-C session chooser. More...
int(*	GetRandomObject )(CERTC_CTX ctx, POINTER handle, B_ALGORITHM_OBJ *randomObj)
	Returns an initialized random object. More...
void(*	UpdateRandom )(CERTC_CTX ctx, POINTER handle)
	Gathers unpredictable information from the operating environment and uses the information to update an internal pseudo-random number generator. More...

CRYPTO_FUNCS Reference

Data Fields

Field Documentation (alphabetical)