RSA BSAFE Cert-C

Certificate Components for C

Crypto-C 6.2.1 Developer's Guide
Search

service.h File Reference

This file contains 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)
 Retrieves 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 this function (as opposed to C_BindServices()) in situations where you want the application to bind to a single service provider.

Parameters:
ctx [In] A pointer to an initialized Cert-C context.
type [In] 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 [In] A pointer to a NULL-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 [Out] The location where the function stores the resulting service handle.
Returns:
0 indicates success.
See Errors for error information.
Samples:
chain.c, cmp.c, cmpku.c, cmpreq.c, cmprev.c, cms.c, datamsg.c, dbutil.c, imdbcert.c, imdbpvt.c, kcscrs.c, kcsscep.c, ldap.c, ldap2.c, mscapicert.c, ocsp.c, p11dbimp.c, p12memio.c, p7stream.c, pkcs11db.c, pkcs11msg.c, pkcs12.c, pkcs12exp.c, rsadbcert.c, rsadbpvt.c, scepdb.c, scepreq.c, and verisign.c.

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 [In] A pointer to an initialized Cert-C context.
type [In] 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 C_SelectCertByAttributes(), 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 [In] A pointer to an array of pointers that point to NULL-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 [In] 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 [Out] The location where the resulting service handle is stored.
Returns:
0 indicates success.
See Errors for error information.
Samples:
mscapiroots.c, and validate.c.

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 [In] The SERVICE code.
count [Out] The number of providers bound with the service.
Returns:
0 indicates success.
See Errors for error information.

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

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

Parameters:
service [In] 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:
0 indicates success.
See Errors for error information.

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

Registers additional service providers subsequent to Cert-C initialization. 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 [In] A pointer to an initialized Cert-C context.
handler [In] A pointer to the handler that defines the service provider to register.
params [In] A pointer to the service-provider initialization parameters.
order [In] 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:
0 indicates success.
See Errors for error information.
Samples:
asn1.c, attrib.c, cert.c, certsonly.c, cftest.c, chain.c, cmp.c, cmpku.c, cmpreq.c, cmprev.c, cms.c, critical.c, crl.c, crmf.c, datamsg.c, dhcert.c, exten.c, extract.c, imdbcert.c, imdbpvt.c, kcscrs.c, kcsscep.c, keypair.c, keywrap.c, ldap.c, ldap2.c, mscapicert.c, mscapiroots.c, name.c, ocsp.c, p11dbimp.c, p11dblist.c, p12memio.c, p7stream.c, pkcs10.c, pkcs11db.c, pkcs11msg.c, pkcs12.c, pkcs12exp.c, rsadbcert.c, rsadbpvt.c, saltname.c, scepdb.c, scepreq.c, sslcpvt.c, validate.c, and verisign.c.

int C_UnbindService (  SERVICE *    service )  ;
 

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

Parameters:
service [In, Out] 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:
0 indicates success.
See Errors for error information.
Samples:
chain.c, cmp.c, cmpku.c, cmpreq.c, cmprev.c, cms.c, datamsg.c, dbutil.c, imdbcert.c, imdbpvt.c, kcscrs.c, kcsscep.c, ldap.c, ldap2.c, mscapicert.c, mscapiroots.c, ocsp.c, p11dbimp.c, p12memio.c, p7stream.c, pkcs11db.c, pkcs11msg.c, pkcs12.c, pkcs12exp.c, rsadbcert.c, rsadbpvt.c, scepdb.c, scepreq.c, validate.c, and verisign.c.

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 this function 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 [In] A pointer to an initialized Cert-C context.
type [In] 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 [In] A pointer 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.
Samples:
keywrap.c.

Copyright (c) 1999-2005 RSA Security Inc. All rights reserved. 067-001001-2720-001-000 - 2.7.2