RSA Security logo

RSA BSAFE Cert-C
API Reference

service.h File Reference

This file defines the types and interfaces for manipulating Cert-C service providers.

#include "basetype.h"
#include "surrspi.h"
#include "logspi.h"
#include "cryptspi.h"
#include "iospi.h"
#include "dbspi.h"
#include "statspi.h"
#include "pathspi.h"
#include "pkispi.h"

Go to the source code of this file.

Data Structures

union  SERVICE_FUNCS
 Specifies a set of function pointers. More...

struct  SERVICE_HANDLER
 Contains service provider information and the service provider initialization function. More...


Functions

int C_RegisterService (CERTC_CTX ctx, SERVICE_HANDLER *handler, POINTER params, int order)
 Registers additional service providers subsequent to Cert-C initialization. More...

void C_UnregisterService (CERTC_CTX ctx, int type, char *name)
 Unregisters a previously registered service provider. More...

int C_BindService (CERTC_CTX ctx, int type, char *name, SERVICE *service)
 Binds a single currently registered service provider to a SERVICE handle. More...

int C_BindServices (CERTC_CTX ctx, int type, char **names, unsigned int nameCount, SERVICE *service)
 Binds one or more currently registered service providers, of a single type, to a SERVICE handle. More...

int C_UnbindService (SERVICE *service)
 Undoes a previous binding of service providers to the specified handle. More...

int C_GetProviderNames (SERVICE service, char **names)
 Gets the names of providers bound with a SERVICE by C_BindService() or C_BindServices(). More...

int C_GetProviderCount (SERVICE service, unsigned int *count)
 Gets the number of providers bound with a SERVICE by C_BindService() or C_BindServices(). More...

Function Documentation

int C_BindService (  CERTC_CTX    ctx,
int    type,
char *    name,
SERVICE *    service
)  ;
 

Binds a single currently registered service provider to a SERVICE handle. A SERVICE handle can be used as a parameter to Cert-C functions that use a specific service provider or a set of service providers. Call C_BindService() (as opposed to C_BindServices()) in situations where you want the application to bind to a single service provider.

Parameters:
ctx This input parameter points to an initialized Cert-C context.
type This input parameter denotes the service provider type. It should contain one of the following SPT_* constants.

Service Provider Type Description
SPT_SURRENDER Text Surrender service provider
SPT_LOG Status Log service provider
SPT_CRYPTO Cryptographic service provider
SPT_IO Stream service provider
SPT_DATABASE2 Database service provider (Cert-C v2)
SPT_DATABASE Database service provider (Cert-C v1)
SPT_CERT_STATUS Certificate Revocation Status service provider
SPT_CERT_PATH Certificate Path Processing service provider
SPT_PKI PKI service provider

If you attempt to register another service provider of type SPT_CRYPTO or SPT_SURRENDER, C_Initialize() and C_RegisterService() will return E_DUPLICATE_SERVICE.
name This input parameter points to a NUL-terminated string giving the service provider instance name. The function uses this string to identify the specific service provider instance to be bound to the service handle. The application may pass NULL_PTR in place of the service name. This causes C_BindService() to bind to the first service provider of the given type.
service This output parameter points to the location where C_BindService() stores the resulting service handle.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_BindServices (  CERTC_CTX    ctx,
int    type,
char **    names,
unsigned int    nameCount,
SERVICE *    service
)  ;
 

Binds one or more currently registered service providers, of a single type, to a SERVICE handle. A service handle is required for some Cert-C API functions that can be directed to a particular service provider or to a set of service providers. Some service-provider types (for example, SPT_DATABASE and SPT_DATABASE2) allow an ordered list of instances to be specified in the service name array. If NULL_PTR is specified for names, all of the service-provider instances of the given type are bound in registration order.

Parameters:
ctx This input parameter points to an initialized Cert-C context.
type This input parameter denotes the service-provider type. It should contain one of the following SPT_* constants.

Service Provider Type Description
SPT_SURRENDER Text Surrender service provider
SPT_LOG Status Log service provider
SPT_CRYPTO Cryptographic service provider
SPT_IO Stream service provider
SPT_DATABASE2 Database service provider (Cert-C v2)
SPT_DATABASE Database service provider (Cert-C v1)
SPT_CERT_STATUS Certificate Revocation Status service provider
SPT_CERT_PATH Certificate Path Processing service provider
SPT_PKI PKI service provider

If you attempt to register another service provider of type SPT_CRYPTO or SPT_SURRENDER, C_Initialize() and C_RegisterService() return E_DUPLICATE_SERVICE. If you are using a database service provider that implements the C_SelectCertByAttributes() function, you must use the SPT_DATABASE2 type. This function and service type were introduced in Cert-C v2. If you are using a database service provider that does not implement this function, you can continue to use the SPT_DATABASE type.
names This input parameter points to an array of pointers that point to NUL-terminated strings that contain the service provider instance names. The function uses this array to identify the specific service-provider instances to be bound to the service handle, and the order in which functions that reference this handle should call them.
The application can pass NULL_PTR instead of a service names array. In this case, the nameCount parameter should also be set to 0 (zero). This causes C_BindServices() to bind to all of the service providers of the given type, in the order in which the service providers were registered.
nameCount This input parameter gives the number of entries in the service instance names array. The application can pass 0 (zero) as the nameCount value to indicate that C_BindServices() should bind to all service providers of the given type, in the order in which the service providers were registered.
service This output parameter points to the location where C_BindServices() stores the resulting service handle.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetProviderCount (  SERVICE    service,
unsigned int *    count
)  ;
 

Gets the number of providers bound with a SERVICE by C_BindService() or C_BindServices(). This function is typically used with C_GetProviderNames(). The following example shows how it is used: 

    C_GetProviderCount(service, &count);
    names = (char *) T_malloc(count * sizeof(char *));
    C_GetProviderNames(service, names);
    ....
    for (int i=0; i < count; i++)
      T_free(names[i]);
    T_free((char *)names);

Parameters:
service This is an input parameter.
count This output parameter holds the number of providers bound with the service.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetProviderNames (  SERVICE    service,
char **    names
)  ;
 

Gets the names of providers bound with a SERVICE by C_BindService() or C_BindServices(). This function allocates memory for each provider name and makes a copy of the name. It is the responsibilty of the applications to free the memories.

Parameters:
service This is an input parameter.
names This is an array of char pointers. The array size should be big enough to hold all providers' names in the service.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_RegisterService (  CERTC_CTX    ctx,
SERVICE_HANDLER *    handler,
POINTER    params,
int    order
)  ;
 

Registers additional service providers subsequent to Cert-C initialization. The function calls the service provider's initialization function and adds an entry for the service provider in the context's internal list of service providers.

Parameters:
ctx This input parameter points to an initialized Cert-C context.
handler This input parameter points to the handler that defines the service provider to register.
params This input parameter points to the service-provider initialization parameters.
order This input parameter specifies whether the service provider should be placed before or after other service providers of the same type in the context's internal service table. The valid order types are:

Service Provider Order Description
SERVICE_ORDER_FIRST This constant indicates the service provider should be inserted before others of the same type.
SERVICE_ORDER_LAST This constant indicates the service provider should be inserted after others of the same type.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_UnbindService (  SERVICE *    service )  ;
 

Undoes a previous binding of service providers to the specified handle. The function frees any memory allocated by the corresponding call to C_BindService() or C_BindServices().

Parameters:
service This is both an input and an output parameter. As an input parameter, it points to a service handle returned by a previous call to C_BindService() or C_BindServices(). As an output parameter, the specified location is set to NULL_PTR.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

void C_UnregisterService (  CERTC_CTX    ctx,
int    type,
char *    name
)  ;
 

Unregisters a previously registered service provider. The service handler with the specified type and name is removed from the context, the service provider's finalize function is called, and the memory associated with the context's copy of the service handler is freed. Cert-C automatically unregisters all currently registered service providers when the Cert-C library is shut down, so the application does not need to call C_UnregisterService() if the next Cert-C call is C_FinalizeCertC(). The application must ensure that the service provider being unregistered is not bound to any service handles. Using a service handle that includes an unregistered service may cause the application to crash.

Parameters:
ctx This input parameter points to an initialized Cert-C context.
type This input parameter denotes the service provider type. It should contain one of the following SPT_* constants.

Service Provider Type Description
SPT_SURRENDER Text Surrender service provider
SPT_LOG Status Log service provider
SPT_CRYPTO Cryptographic service provider
SPT_IO Stream service provider
SPT_DATABASE2 Database service provider (Cert-C v2)
SPT_DATABASE Database service provider (Cert-C v1)
SPT_CERT_STATUS Certificate Revocation Status service provider
SPT_CERT_PATH Certificate Path Processing service provider
SPT_PKI PKI service provider

If you attempt to register another service provider of type SPT_CRYPTO or SPT_SURRENDER, C_Initialize() and C_RegisterService() will return E_DUPLICATE_SERVICE.
name This input parameter points to a NUL-terminated string giving the service provider instance name. The function uses this string to identify the specific service-provider instance to unregister.
Returns:
None.


RSA BSAFE® Cert-C 2.7 API Reference