RSA Security logo

RSA BSAFE Cert-C
API Reference

crs.h File Reference

This file processes initialization data for the CRS provider.

The caller must specify where the configuration data comes from, for example: file:/var/opt/PKI/OnSite/crs.cfg.

Currently, only the "file" protocol is implemented as a file-retrieval mechanism.

The contents of the resource will be in "properties format". The property names recognized by the CRS provider are "dest", "http.proxy" and "profile." All other entries are ignored.

Zero or more destinations may be specified; however, specifying a destination is optional, because there are valid uses of the service provider for which a "destination" is not necessary.

Proxy specifications are optional. If present, one or more URLs must be specified.

The profiles (which are case-sensitive) recognized by the current service provider are "generic", "VeriSign", "Keon" and "KCA6". Its specification is optional and "VeriSign" is the default value if no profile is specified.

As an example, the contents of a configuration file might be:

 dest: http://onsite.verisign.com/cgi-bin/crs.exe
 dest: http://onsite2.verisign.com/cgi-bin/crs.exe
 http.proxy: proxy1.mycompany.com:8080
 http.proxy: proxy2.mycompany.com:8080
 profile: VeriSign

Go to the source code of this file.

Data Structures

struct  CRS_POP_PROVIDE_INFO
 Provides proof-of-possession (POP) for an end-entity's certificate request, where the end-entity does not provide direct access to the private key to be certified. More...

 PKI_CRS_INIT_PARAMS
 Passes initialization parameters to the Cert-C CRS PKI service provider's initialization functions. More...


Typedefs

typedef PKI_CRS_INIT_PARAMS PKI_CRS_INIT_PARAMS
 Passes initialization parameters to the Cert-C CRS PKI service provider's initialization functions. More...

typedef PKI_CRS_INIT_PARAMS * P_PKI_CRS_INIT_PARAMS
 Passes initialization parameters to the Cert-C CRS PKI service provider's initialization functions. More...


Functions

int S_InitializeCRS (POINTER ctx, POINTER params, SERVICE_FUNCS *funcs, POINTER *handle)
 This function is never called directly. More...

int S_CRS_ProvideProofOfPossession (CERTC_CTX ctx, POINTER handle, PKI_MSG_OBJ certRequest, CRS_POP_PROVIDE_INFO *pPopInfo)
 Provides proof-of-possession (POP) for an end-entity's certificate request, where the end-entity does not provide direct access to the private key to be certified. More...

Typedef Documentation

typedef struct PKI_CRS_INIT_PARAMS * P_PKI_CRS_INIT_PARAMS
 

Passes initialization parameters to the Cert-C CRS PKI service provider's initialization functions. When you register the Cert-C CRS PKI service provider, the corresponding handlerParams should point to a PKI_CRS_INIT_PARAMS structure. Or, if you use C_RegisterService() to register the Cert- C CRS PKI service provider, the corresponding params should point to a PKI_CRS_INIT_PARAMS structure.

Parameters:
configURL The data item configURL is a pointer to a NUL-terminated unsigned character array that contains a URL used to locate the configuration information for this service-provider instance. Currently, the only protocol that may be used to specify the location of the configuration data is file. For example, configURL may point to a string such as file:///var/opt/CRS/config/crs.cfg or file:///C:/CRS/config/crs.cfg.

The contents of the resource pointed to by configURL are name=value lines of text. The names that this service provider recognizes are dest, http.proxy, and profile. All other entries are ignored.

dest is used to specify the location of one or more CRS auto-responders.

http.proxy is used to specify an address and port number of a non-transparent HTTP proxy that exists between the application and the CRS auto-responder. This value should be formatted as address:port.

profile is used to specify the particular CRS profile that is implemented by the responder; there may be subtle differences between one CRS implementation and another. This service provider has been tested with VeriSign OnSite, RSA Keon Certificate Server 5.5, and RSA Keon Certificate Authority 6.0 responders. If this optional entry is left unspecified, it defaults to VeriSign.

For example, the contents of the configuration file located at file:///var/opt/CRS/config/crs.cfg might be: 
      dest=http://onsite.verisign.com/cgi-bin/crs.exe
      http.proxy = proxy1.mycompany.com:80
      http.proxy = proxy2.mycompany.com:80
      profile = VeriSign
handle Upon return, contains a service-provider handle for optional use with the S_CRS_ProvideProofOfPossession() function.

typedef struct PKI_CRS_INIT_PARAMS PKI_CRS_INIT_PARAMS
 

Passes initialization parameters to the Cert-C CRS PKI service provider's initialization functions. When you register the Cert-C CRS PKI service provider, the corresponding handlerParams should point to a PKI_CRS_INIT_PARAMS structure. Or, if you use C_RegisterService() to register the Cert- C CRS PKI service provider, the corresponding params should point to a PKI_CRS_INIT_PARAMS structure.

Parameters:
configURL The data item configURL is a pointer to a NUL-terminated unsigned character array that contains a URL used to locate the configuration information for this service-provider instance. Currently, the only protocol that may be used to specify the location of the configuration data is file. For example, configURL may point to a string such as file:///var/opt/CRS/config/crs.cfg or file:///C:/CRS/config/crs.cfg.

The contents of the resource pointed to by configURL are name=value lines of text. The names that this service provider recognizes are dest, http.proxy, and profile. All other entries are ignored.

dest is used to specify the location of one or more CRS auto-responders.

http.proxy is used to specify an address and port number of a non-transparent HTTP proxy that exists between the application and the CRS auto-responder. This value should be formatted as address:port.

profile is used to specify the particular CRS profile that is implemented by the responder; there may be subtle differences between one CRS implementation and another. This service provider has been tested with VeriSign OnSite, RSA Keon Certificate Server 5.5, and RSA Keon Certificate Authority 6.0 responders. If this optional entry is left unspecified, it defaults to VeriSign.

For example, the contents of the configuration file located at file:///var/opt/CRS/config/crs.cfg might be: 
      dest=http://onsite.verisign.com/cgi-bin/crs.exe
      http.proxy = proxy1.mycompany.com:80
      http.proxy = proxy2.mycompany.com:80
      profile = VeriSign
handle Upon return, contains a service-provider handle for optional use with the S_CRS_ProvideProofOfPossession() function.

Function Documentation

int S_CRS_ProvideProofOfPossession (  CERTC_CTX    ctx,
POINTER    handle,
PKI_MSG_OBJ    certRequest,
CRS_POP_PROVIDE_INFO *    pPopInfo
)  ;
 

Provides proof-of-possession (POP) for an end-entity's certificate request, where the end-entity does not provide direct access to the private key to be certified. Examples of such entities are secure Web servers, routers, and IPSec firewalls.

Parameters:
ctx This input parameter points to an initialized Cert-C context handle.
handle This input parameter points to the service provider's handle.
certRequest This is both an input and output parameter. As an input parameter, it points to an allocated and initialized PKI_MSG_OBJ. As an output parameter, it points to a PKI_MSG_OBJ that contains the provided POP information.
pPopInfo This input parameter points to a structure that contains the PKI transaction's POP information.

int S_InitializeCRS (  POINTER    ctx,
POINTER    params,
SERVICE_FUNCS *    funcs,
POINTER *    handle
)  ;
 

This function is never called directly. To initialize or register the Cert-C CRS PKI service provider, call the C_InitializeCertC() or C_RegisterService() function. Both functions take SERVICE_HANDLER and a POINTER to a parameters structure as parameters. SERVICE_HANDLER's Initialize parameter points to the S_InitializeCRS() function, and the corresponding POINTER should point to a PKI_CRS_INIT_PARAMS structure, or it should be set to NULL_PTR.

Cert-C uses S_InitializeCRS() to initialize the Cert-C CRS PKI service provider's functions and initialization parameters. S_InitializeCRS() stores pointers to the Cert-C CRS PKI service provider's functions in funcs's pki member, which is a PKI_FUNCS structure. S_InitializeCRS() uses the Cert-C CRS PKI service provider's initialization parameters in params, which points to an instance of a PKI_CRS_INIT_PARAMS structure.

Parameters:
ctx This input parameter points to an initialized Cert-C context handle.
params This input parameter is a pointer to a PKI_CRS_INIT_PARAMS structure.
funcs This is both an input and output parameter. As an input parameter, it points to an allocated but uninitialized SERVICE_FUNCS union. As an output parameter, it contains the PKI_FUNCS function pointers for the Cert-C CRS PKI service provider.
handle This output parameter points to the service provider handle for this instance of the Cert-C CRS PKI service provider.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.


RSA BSAFE® Cert-C 2.7 API Reference