RSA Security logo

RSA BSAFE Cert-C
API Reference

PKI_FUNCS Reference

Stores pointers to a Cert-C PKI service provider's functions.

Use the S_InitializeCRS(), S_InitializeSCEPPKI(), or S_InitializeCMP() function to initialize funcs's pki function pointer to the Cert-C CRS, Cert-C SCEP, or Cert-C CMP PKI service provider's implementation of PKI_FUNCS.

Note: The following SPIs in this structure are deprecated in Cert-C 2.5: ReadCertResponseMsg, WriteCertRequestMsg, RequestCert, SendMsg, GenerateProofOfPossession, and ValidateProofOfPossession.

#include <pkispi.h> 

00041 typedef struct pki_funcs {
00050   void (*Finalize) (
00051     CERTC_CTX         ctx,          /* (mod) Cert-C context                 */
00052     POINTER           handle        /* (mod) provider handle                */
00053   );
00054 
00078  int (*GeneratePKIMsgProofOfPossession) (
00079     CERTC_CTX         ctx,           /* (in)  Cert-C context                 */
00080     POINTER           handle,        /* (in)  SP-specific data handle        */
00081     PKI_MSG_OBJ       pkiMsgObj,     /* (mod) PKI message object             */
00082     unsigned int      index,         /* (in)  index of request in message
00083                                               object                         */
00084     B_KEY_OBJ         privateKey,    /* (in)  private key                    */
00085     PKI_POP_GEN_INFO *popGenInfo     /* (in)  determined by POP type         */
00086   );
00087 
00112   int (*ValidatePKIMsgProofOfPossession) (
00113     CERTC_CTX         ctx,           /* (in)  Cert-C context                 */
00114     POINTER           handle,        /* (in)  SP-specific data handle        */
00115     PKI_MSG_OBJ       msg,           /* (in)  PKI message object             */
00116     unsigned int      index,         /* (in)  index of request or response in
00117                                               message object                 */
00118     PKI_POP_VAL_INFO *popValInfo,    /* (in)  private info to open response  */
00119     B_KEY_OBJ         privateKey     /* (out) subject's private key          */
00120   );
00121 
00144   int (*SendPKIRequest) (
00145     CERTC_CTX            ctx,              /* (in)  Cert-C context           */
00146     POINTER              handle,           /* (in)  SP-specific data handle  */
00147     ITEM                *encodedRequest,   /* (in)  encoded request message  */
00148     ITEM                *encodedResponse,  /* (out) encoded response message */
00149     PKI_STATUS_INFO_OBJ  statusInfo        /* (out) out-of-band status info  */
00150   );
00151 
00178   int (*RequestPKIMsg) (
00179     CERTC_CTX            ctx,            /* (in)  Cert-C context                 */
00180     POINTER              handle,         /* (in)  SP-specific data handle        */
00181     PKI_MSG_OBJ          pkiRequest,     /* (in)  request object                 */
00182     PKI_PROTECT_INFO    *protectInfo,    /* (in)  protection/integrity info      */
00183     SERVICE              db,             /* (out) where to put keys, certs, crls */
00184     PKI_MSG_OBJ          response        /* (out) response message object        */
00185   );
00186 
00210   int (*GetPKIMsgDER) (
00211     CERTC_CTX         ctx,            /* (in)  Cert-C context               */
00212     POINTER           handle,         /* (in)  SP-specific data handle      */
00213     PKI_MSG_OBJ       request,        /* (in)  certification request object */
00214     PKI_PROTECT_INFO *protectInfo,    /* (in)  protection/integrity info    */
00215     ITEM             *encodedMsg      /* (out) serialized request           */
00216   );
00217 
00239   int (*SetPKIMsgBER) (
00240     CERTC_CTX         ctx,            /* (in)  Cert-C context            */
00241     POINTER           handle,         /* (in)  SP-specific data handle   */
00242     ITEM             *encodedMsg,     /* (in)  serialized response       */
00243     PKI_PROTECT_INFO *protectInfo,    /* (in)  protection/integrity info */
00244     PKI_MSG_OBJ       response        /* (out) response message object   */
00245   );
00246 
00247   /* --- DEPRECATED FUNCTIONS BEGIN --- */
00248 
00288   int (*ReadCertResponseMsg) (
00289     CERTC_CTX         ctx,            /* (in)  Cert-C context          */
00290     POINTER           handle,         /* (in)  SP-specific data handle */
00291     ITEM             *encodedMsg,     /* (in)  serialized response     */
00292     PKI_PROTECT_INFO *protectInfo,    /* (in)  protection keys & certs */
00293     PKI_MSG_OBJ       response        /* (out) response message object */
00294   );
00295 
00328   int (*WriteCertRequestMsg) (
00329     CERTC_CTX         ctx,            /* (in)  Cert-C context          */
00330     POINTER           handle,         /* (in)  SP-specific data handle */
00331     PKI_MSG_OBJ       request,        /* (in)  request message object  */
00332     PKI_PROTECT_INFO *protectInfo,    /* (in)  protection keys & certs */
00333     ITEM             *encodedMsg      /* (out) serialized request      */
00334   );
00335 
00413   int (*RequestCert) (
00414     CERTC_CTX         ctx,                /* (in)  Cert-C context          */
00415     POINTER           handle,             /* (in)  SP-specific data handle */
00416     PKI_MSG_OBJ       request,            /* (in)  request  message object */
00417     PKI_PROTECT_INFO  *protectInfo,       /* (in)  protection keys & certs */
00418     SERVICE           db,                 /* (in) response message object  */
00419     PKI_MSG_OBJ       response            /* (out) response message object */
00420   );
00421 
00454   int (*SendMsg) (
00455     CERTC_CTX        ctx,              /* (in)  Cert-C context           */
00456     POINTER          handle,           /* (in)  SP-specific data handle  */
00457     ITEM            *encodedRequest,   /* (in)  encoded request message  */
00458     ITEM            *encodedResponse,  /* (out) encoded response message */
00459     PKI_STATUS_INFO *statusInfo        /* (out) out-of-band status info  */
00460   );
00461 
00491   int (*GenerateProofOfPossession) (
00492     CERTC_CTX         ctx,            /* (in) Cert-C context               */
00493     POINTER           handle,         /* (in) SP-specific data handle      */
00494     PKI_MSG_OBJ       certRequest,    /* (in) certification request object */
00495     B_KEY_OBJ         privateKey,     /* (in) private key                  */
00496     PKI_POP_GEN_INFO *popGenInfo      /* (in) determined by POP type       */
00497   );
00498 
00499   /* Called by EE if encrypted certificate was returned. */
00505   int (*ValidateProofOfPossession) (
00506     CERTC_CTX         ctx,          /* Cert-C context                     */
00507     POINTER           handle,       /* (in) SP-specific data handle       */
00508     PKI_MSG_OBJ       message,      /* certification request or response  */
00509     PKI_POP_VAL_INFO *popValInfo,   /* (in) private info to open response */
00510     B_KEY_OBJ         privateKey    /* subject's private key              */
00511   );
00512   /* --- DEPRECATE FUNCTIONS END --- */
00513 
00514 } PKI_FUNCS;

Data Fields

void(* Finalize )(CERTC_CTX ctx, POINTER handle)
 Frees resources associated with the specified service provider handle, including freeing memory allocated during service provider initialization. More...

int(* GeneratePKIMsgProofOfPossession )(CERTC_CTX ctx, POINTER handle, PKI_MSG_OBJ pkiMsgObj, unsigned int index, B_KEY_OBJ privateKey, PKI_POP_GEN_INFO *popGenInfo)
 Generates a POP for a particular certificate request message in the PKI message object. More...

int(* ValidatePKIMsgProofOfPossession )(CERTC_CTX ctx, POINTER handle, PKI_MSG_OBJ msg, unsigned int index, PKI_POP_VAL_INFO *popValInfo, B_KEY_OBJ privateKey)
 Validates a POP for a particular certificate request message in the PKI message object. More...

int(* SendPKIRequest )(CERTC_CTX ctx, POINTER handle, ITEM *encodedRequest, ITEM *encodedResponse, PKI_STATUS_INFO_OBJ statusInfo)
 Sends a PKI request message to the server, and returns an encoded response message and the status of the operation. More...

int(* RequestPKIMsg )(CERTC_CTX ctx, POINTER handle, PKI_MSG_OBJ pkiRequest, PKI_PROTECT_INFO *protectInfo, SERVICE db, PKI_MSG_OBJ response)
 Sends a certification request message to the specified PKI service; and receives and processes the response. More...

int(* GetPKIMsgDER )(CERTC_CTX ctx, POINTER handle, PKI_MSG_OBJ request, PKI_PROTECT_INFO *protectInfo, ITEM *encodedMsg)
 Creates a serialized certification request message according to the protocol implemented by the specified PKI service provider. More...

int(* SetPKIMsgBER )(CERTC_CTX ctx, POINTER handle, ITEM *encodedMsg, PKI_PROTECT_INFO *protectInfo, PKI_MSG_OBJ response)
 Processes a PKI response message. More...

int(* ReadCertResponseMsg )(CERTC_CTX ctx, POINTER handle, ITEM *encodedMsg, PKI_PROTECT_INFO *protectInfo, PKI_MSG_OBJ response)
 Composes a certificate response message from a buffer that contains a CRS message. More...

int(* WriteCertRequestMsg )(CERTC_CTX ctx, POINTER handle, PKI_MSG_OBJ request, PKI_PROTECT_INFO *protectInfo, ITEM *encodedMsg)
 Creates a serialized certificate request message according to the protocol implemented by the Cert-C CRS PKI service provider. More...

int(* RequestCert )(CERTC_CTX ctx, POINTER handle, PKI_MSG_OBJ request, PKI_PROTECT_INFO *protectInfo, SERVICE db, PKI_MSG_OBJ response)
 Sends a certificate request message to the specified PKI service provider or the configured CRS responder or responders. More...

int(* SendMsg )(CERTC_CTX ctx, POINTER handle, ITEM *encodedRequest, ITEM *encodedResponse, PKI_STATUS_INFO *statusInfo)
 Sends a serialized certificate request message (for example, as returned by C_WritePKICertRequestMsg()) to the Cert-C CRS PKI service provider. More...

int(* GenerateProofOfPossession )(CERTC_CTX ctx, POINTER handle, PKI_MSG_OBJ certRequest, B_KEY_OBJ privateKey, PKI_POP_GEN_INFO *popGenInfo)
 Calls the GenerateProofOfPossession function to generate a proof-of-possession for the indicated private key and attaches it to the message object. More...

int(* ValidateProofOfPossession )(CERTC_CTX ctx, POINTER handle, PKI_MSG_OBJ message, PKI_POP_VAL_INFO *popValInfo, B_KEY_OBJ privateKey)
 Called by EE if the encrypted certificate is returned. More...

Field Documentation (alphabetical)

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

Frees resources associated with the specified service provider handle, including freeing memory allocated during service provider initialization. Cert-C calls Finalize when a service provider's instance is unregistered.

int(* pki_funcs::GeneratePKIMsgProofOfPossession)( CERTC_CTX ctx, POINTER handle, PKI_MSG_OBJ pkiMsgObj, unsigned int index, B_KEY_OBJ privateKey, PKI_POP_GEN_INFO *popGenInfo )
 

Generates a POP for a particular certificate request message in the PKI message object.

Parameters:
ctx This input parameter is the Cert-C context.
handle This input parameter specifies the service provider-specific data handle.
pkiMsgObj This input/output parameter specifies the PKI message object.
index This input parameter specifies the index of the request in the message object.
privateKey This input parameter specifies the private key.
popGenInfo This input parameter is determined by POP type.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int(* pki_funcs::GenerateProofOfPossession)( CERTC_CTX ctx, POINTER handle, PKI_MSG_OBJ certRequest, B_KEY_OBJ privateKey, PKI_POP_GEN_INFO *popGenInfo )
 

Calls the GenerateProofOfPossession function to generate a proof-of-possession for the indicated private key and attaches it to the message object.

Deprecated:
This function is deprecated in Cert-C 2.5.
Parameters:
ctx This input parameter points to an initialized Cert-C context handle.
handle This input parameter is the handle returned by the service provider's initialization function.
certRequest This input parameter is the certificate request message object.
privateKey This input parameter is the private key whose possession is proven.
popGenInfo This input parameter points to information used to generate the proof-of- possession.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int(* pki_funcs::GetPKIMsgDER)( CERTC_CTX ctx, POINTER handle, PKI_MSG_OBJ request, PKI_PROTECT_INFO *protectInfo, ITEM *encodedMsg )
 

Creates a serialized certification request message according to the protocol implemented by the specified PKI service provider.

Parameters:
ctx This input parameter is the Cert-C context.
handle This input parameter specifies the service provider-specific data handle.
request This input parameter specifies the certificate request object.
protectInfo This input parameter specifies the protection/integrity information.
encodedMsg This output parameter specifies the serialized request.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int(* pki_funcs::ReadCertResponseMsg)( CERTC_CTX ctx, POINTER handle, ITEM *encodedMsg, PKI_PROTECT_INFO *protectInfo, PKI_MSG_OBJ response )
 

Composes a certificate response message from a buffer that contains a CRS message. Relevant cryptographic protections are validated (for example, digital signatures) or inverted (for example, digital envelope), or both. Information extracted from the message is stored in the supplied PKI_MSG_OBJ. There is no long-term disposition of the information in the response object. That is, this function does not store any elements of the certificate response in persistent datastores.

Deprecated:
This function is deprecated in Cert-C 2.5.
Parameters:
ctx This input parameter points to an initialized Cert-C context handle.
handle This input parameter is the handle returned by the service provider's initialization function.
encodedMsg This input parameter points to the serialized response message.
protectInfo This input parameter points to information used to cryptographically validate or unprotect the message.
response This is both an input and output parameter. On input, it is an allocated but uninitialized PKI_MSG_OBJ. On output, it is updated with the response information.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int(* pki_funcs::RequestCert)( CERTC_CTX ctx, POINTER handle, PKI_MSG_OBJ request, PKI_PROTECT_INFO *protectInfo, SERVICE db, PKI_MSG_OBJ response )
 

Sends a certificate request message to the specified PKI service provider or the configured CRS responder or responders. It receives and processes the response. It has provider-specific implementations by the Cert-C CMP PKI Service provider and the Cert-C CRS PKI Service provider.

Deprecated:
This function is deprecated in Cert-C 2.5.
Cert-C CMP CRS Service Provider Implementation

If any certificates, CRLs, or keys are received in the response, they are stored in the indicated database or databases and in the PKI_CERTRESP_FIELDS of the response object. The application can examine the response message for status information. In addition, it is recommended that the application examine the response to determine whether the identity of the responder is the one the application expects. For example, if the response message was protected with a digital signature, the application may need to verify that the subject name of the signing certificate is the same as the expected responder name.

Cert-C CMP PKI Service Provider Implementation

This function generates a certification response message as a result. If the requested certificate can be issued immediately by the CA, then it will be received in the response and it will be stored in any indicated database.

If the service provider exchanges more than one pair of messages with the PKI service, it can choose to return the last response message from the service or it can synthesize a response object containing information accumulated from multiple protocol response messages.

Parameters:
ctx This input parameter points to an initialized Cert-C context handle.
The two implementations have the same parameter definitions.
Parameters:
handle This input parameter is the handle returned by the service provider's initialization function.
request This input parameter is the certificate request message object.
protectInfo This input parameter points to information used to generate cryptographic protection for the request message.
db This input parameter is the database service handle indicating where certificates, and CRLs from the response message are to be stored. (Note that not all services return certificates, and CRLs in the response.)
response This is both an input and output parameter. On input, it is an allocated but uninitialized PKI_MSG_OBJ. On output, it is updated with the response information. The application can expect the service provider to fill in at least the statusInfo field of the PKI_MSG_FIELDS structure associated with the response object.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int(* pki_funcs::RequestPKIMsg)( CERTC_CTX ctx, POINTER handle, PKI_MSG_OBJ pkiRequest, PKI_PROTECT_INFO *protectInfo, SERVICE db, PKI_MSG_OBJ response )
 

Sends a certification request message to the specified PKI service; and receives and processes the response.

Parameters:
ctx This input parameter is the Cert-C context.
handle This input parameter specifies the service provider-specific data handle.
pkiRequest This input parameter specifies the request object.
protectInfo This input parameter specifies the protection/integrity information.
db This output parameter indicates where to put keys, certificates, and CRLs.
response This output parameter specifies the response message object.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int(* pki_funcs::SendMsg)( CERTC_CTX ctx, POINTER handle, ITEM *encodedRequest, ITEM *encodedResponse, PKI_STATUS_INFO *statusInfo )
 

Sends a serialized certificate request message (for example, as returned by C_WritePKICertRequestMsg()) to the Cert-C CRS PKI service provider. A serialized response is returned to the application. The application can read the response into a PKI_MSG_OBJ using a C_ReadPKI*Msg() function (for example C_ReadPKICertResponseMsg()).

Deprecated:
This function is deprecated in Cert-C 2.5.
Parameters:
ctx This input parameter points to an initialized Cert-C context handle.
handle This input parameter is the handle returned by the service provider's initialization function.
encodedRequest This input parameter points to the serialized request message.
encodedResponse This output parameter points to the returned serialized response message.
statusInfo This output parameter points to out-of-band status information.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int(* pki_funcs::SendPKIRequest)( CERTC_CTX ctx, POINTER handle, ITEM *encodedRequest, ITEM *encodedResponse, PKI_STATUS_INFO_OBJ statusInfo )
 

Sends a PKI request message to the server, and returns an encoded response message and the status of the operation.

Parameters:
ctx This input parameter is the Cert-C context.
handle This input parameter specifies the service provider-specific data handle.
encodedRequest This input parameter specifies the encoded request message.
encodedResponse This output parameter specifies the encoded response message.
statusInfo This output parameter specifies the out-of-band status information of the send request operation.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int(* pki_funcs::SetPKIMsgBER)( CERTC_CTX ctx, POINTER handle, ITEM *encodedMsg, PKI_PROTECT_INFO *protectInfo, PKI_MSG_OBJ response )
 

Processes a PKI response message.

Parameters:
ctx This input parameter is the Cert-C context.
handle This input parameter specifies the service provider-specific data handle.
encodedMsg This input parameter specifies the serialized response.
protectInfo This input parameter specifies the protection/integrity information.
response This output parameter specifies the response message object.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int(* pki_funcs::ValidatePKIMsgProofOfPossession)( CERTC_CTX ctx, POINTER handle, PKI_MSG_OBJ msg, unsigned int index, PKI_POP_VAL_INFO *popValInfo, B_KEY_OBJ privateKey )
 

Validates a POP for a particular certificate request message in the PKI message object.

Parameters:
ctx This input parameter is the Cert-C context.
handle This input parameter specifies the service provider-specific data handle.
msg This input parameter specifies the PKI message object.
index This input parameter specifies the index of the request or response in the message object.
popValInfo This input parameter specifies private information to open response.
privateKey This output parameter specifies the subject's private key.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int(* pki_funcs::ValidateProofOfPossession)( CERTC_CTX ctx, POINTER handle, PKI_MSG_OBJ message, PKI_POP_VAL_INFO *popValInfo, B_KEY_OBJ privateKey )
 

Called by EE if the encrypted certificate is returned.

Deprecated:
This function is deprecated in Cert-C 2.5.

int(* pki_funcs::WriteCertRequestMsg)( CERTC_CTX ctx, POINTER handle, PKI_MSG_OBJ request, PKI_PROTECT_INFO *protectInfo, ITEM *encodedMsg )
 

Creates a serialized certificate request message according to the protocol implemented by the Cert-C CRS PKI service provider. The message is not actually transmitted to a PKI server. This function also applies relevant cryptographic protections (such as digital signatures and envelopes) to the message as a part of the serialization process.

Deprecated:
This function is deprecated in Cert-C 2.5.
Parameters:
ctx This input parameter points to an initialized Cert-C context handle.
handle This input parameter is the handle returned by the service provider's initialization function.
request This input parameter is the certificate request message object.
protectInfo This input parameter points to information used to cryptographically protect the message.
encodedMsg This output parameter points to the returned serialized request message.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

The documentation for this struct was generated from the following file:

RSA BSAFE® Cert-C 2.7 API Reference