RSA BSAFE Cert-C API Reference

context.h File Reference

This file defines the Cert-C context-management routines.

#include "basetype.h"
#include "service.h"

Go to the source code of this file.

Functions
int	C_InitializeCertC (SERVICE_HANDLER *handlers, POINTER *handlerParams, unsigned int handlerCount, CERTC_CTX *ctx)
	Creates the Cert-C context. More...
void	C_FinalizeCertC (CERTC_CTX *ctx)
	Unregisters all currently registered service providers. More...
int	C_SetCertCFlags (CERTC_CTX ctx, UINT4 flags)
	Sets the current set of behavior flags for this CERTC_CTX to the specified values. More...
int	C_GetCertCFlags (CERTC_CTX ctx, UINT4 *pFlags)
	Gets the current set of behavior flags for this CERTC_CTX. More...

---

Function Documentation

void C_FinalizeCertC (  CERTC_CTX *    ctx )  ;

Unregisters all currently registered service providers. It frees all memory associated with the context and sets the context to (CERTC_CTX)0. Parameters: ctx This is both an input and an output parameter. On input, this parameter points to an initialized Cert-C context. On output, this function sets the context to (CERTC_CTX)0 before it returns. If it is already (CERTC_CTX)0, then no action is taken. Returns: None.

int C_GetCertCFlags (  CERTC_CTX    ctx, UINT4 *    pFlags )  ;

Gets the current set of behavior flags for this CERTC_CTX. This function is not generally needed by applications. Parameters: ctx This input parameter points to the initialized Cert-C context from which the current set of behavioral flags are retrieved. pFlags This output parameter points to the location where the flags bitmask is to be stored. Returns: If successful, returns 0. If not, returns a Cert-C error code.

int C_InitializeCertC (  SERVICE_HANDLER *    handlers, POINTER *    handlerParams, unsigned int    handlerCount, CERTC_CTX *    ctx )  ;

Creates the Cert-C context. The application should call this function before calling any other Cert-C function. This function allocates the Cert-C context, and initializes the specified service providers and the internal fields of the context. The service providers are initialized in order of type and in the specified order within each type. The service-provider type order is SPT_SURRENDER, SPT_LOG, SPT_CRYPTO, SPT_IO, SPT_DATABASE2, SPT_DATABASE, SPT_CERT_STATUS, SPT_CERT_PATH, and SPT_PKI. Note that only a single instance of the SPT_SURRENDER or SPT_CRYPTO service-provider types can be registered at a given time. Note: Cert-C is threadsafe but not multi-threaded. You can use Cert-C in multi-threaded applications if you are careful not to use the objects created by Cert-C in multiple threads at the same time. This will result in corrupted data or other errors. Cert-C does not spawn off threads of its own. Each thread must call C_InitializeCertC(), which in turn calls the initialization functions of all of the service providers. The Cert-C context (which bundles all of the service-provider handles) is assumed to be thread-specific. Parameters: handlers This input parameter points to an array of service handlers. Each entry in the array defines a service provider to be initialized. The number of entries in the array is defined by the handlerCount parameter. handlerParams This input parameter points to an array of service-handler initialization parameters. Each entry in the array is a pointer to the initialization parameters of the corresponding entry in the handlers array. The data type of the initialization parameters is defined by the service provider. If all of the initialization parameters to the service providers are zero, the application can pass (POINTER *)0 for the array instead of having to construct an array of NULL_PTRs. handlerCount This input parameter specifies the number of entries in the handlers and handlerParams arrays. ctx This output parameter points to the location where the Cert-C context pointer will be stored. Returns: If successful, returns 0. If not, returns a Cert-C error code.

int C_SetCertCFlags (  CERTC_CTX    ctx, UINT4    flags )  ;

Sets the current set of behavior flags for this CERTC_CTX to the specified values. These flags may be necessary to indicate desired code behaviors for backwards-compatability purposes. The flags may be any not-mutually-incompatible set of CERTC_CTX_FLAG_* values. All undefined bits in the flags bitmask must be cleared. Calls to this API should generally be performed immediately after the CERTC_CTX is initialized with C_InitializeCertC. After that, the behavior of the toolkit is undefined. Parameters: ctx This is both an input and an output parameter. On input, this parameter points to an initialized Cert-C context. On output, it is the context containing the current behavioral flags set. flags This input parameter the a bitmask of CERTC_CTX_FLAG_* behavioral flags to be set. Returns: If successful, returns 0. If not, returns a Cert-C error code.

---

RSA BSAFE^® Cert-C 2.7 API Reference