Producing Signed Requests
Using the Toolkit

prevnext

Producing Signed Requests

OCSP optionally allows an application to produce signed requests. For an environment that requires signed requests, your application needs to:

A context is the global Toolkit environment that your application creates using the Vtk_CtxtNew function. Typically, a single context is created in the start-up code of the application, it sets configuration values, and is used in all subsequent function calls for the Toolkit. Your application must customize the context with requestor signing information. It can add this functionality for handling signed requests by calling the Vtk_CtxtSetOption function and setting the Vtk_OCSPSignInfo structure in the context. This structure supplies a signing function callback and signer information to be included in the request. This structure is used only if the option CO_OCSPSignInfo is specified as the value for the Vtk_CtxtOptionType enumeration which defines configuration option types for a Vtk_Ctxt structure. Configuration options can be configured using the Vtk_CtxtSetOption function and can be retrieved using the Vtk_CtxtGetOption function.

Your callback function performs the actual signing. The Vtk_OCSPSignCallBack function enables the application to add signatures to the outgoing requests. The parameters include the following:

When the Toolkit gets to the point of its processing where OCSP signing occurs, the Toolkit calls the call back the application has specified. The application will then create the signature on the token.

Once the application completes its processing, it needs to return VTK_OK to indicate that the OCSP signature has been added and the Toolkit can continue with its processing. If the application encounters an error when it tries to create the signature, it needs to return any nonzero value to terminate the operation and stop the Toolkit from creating the request.



Code Sample for Customizing a Context

The following sample function shows how to create a Vtk_Ctxt structure and customize it for an environment that requires signed requests.


/*
* myOCSPRequestSignCallbackFunction
*
* Callback function for producing signed OCSP requests.
*/
int VTK_CALLBACK myOCSPRequestSignCallbackFunction(void* userHdl,
Vtk_Buffer *digest, Vtk_Buffer *sigOut,
int maxSigOutBuf, int padding);


/*
* SignCtxtCreate
*
* Creates a Toolkit Context configured for signing of OCSP
* requests.
*
* Parameters:
* signCert - the signer's certificate
* appData - application specific data to passed to the callback
*/
static Vtk_Ctxt* SignCtxtCreate(Vtk_Cert *signCert,
struct my_sign_st *appData)
{
Vtk_Ctxt *ctxt = NULL;
Vtk_uint32 retCode;
Vtk_CtxtOption ctxtOption;
Vtk_OCSPSignInfo signInfo;

/*
* Create default Toolkit context
*/
if ((ctxt = Vtk_CtxtNew()) == NULL)
return NULL;

/*
* Setup the request signing callback information for the
* context.
*/
signInfo.OCSPSignCB = myOCSPRequestSignCallbackFunction;
signInfo.signerCert = signCert;
signInfo.userHdl = (void*)appData; /* any application data */
ctxtOption.option = CO_OCSPSignInfo;
ctxtOption.d.aSignInfo = &signInfo;

if ((retCode = Vtk_CtxtSetOption(ctxt, &ctxtOption)) != VTK_OK)
{
showError("Vtk_CtxtSetOption - CO_OCSPSignInfo", retCode);
Vtk_CtxtDelete(ctxt);
return NULL;
}

return NULL;
} /* SignCtxtCreate */


Note: The scope of the userHdl parameters needs to be at least as long as that of the Vtk_Ctxt in which it is set. The Toolkit does not interpret these parameters, but instead passes these parameters to the callbacks until the parameters have been reset or the Vtk_Ctxt is no longer valid.


Code Sample for Signing OCSP Requests

The following sample provides skeleton code that shows a signing callback function an application can set through the Vtk_OCSPSignInfo structure. This function can then be called every time an OCSP request is created and needs signing. The callback function can be triggered by either calling Vtk_ValidationValidate or Vtk_ValidationGetQueries.


/*
* myOCSPRequestSignCallbackFunction
*
* Callback function for signed OCSP requests.
* This function will get invoked every time the Toolkit
* requires a signature on the request.
*/
int VTK_CALLBACK myOCSPRequestSignCallbackFunction(void* userHdl,
Vtk_Buffer *digest, Vtk_Buffer *sigOut, int maxSigOutBuf,
int padding)
{
struct mySign_st *signHdl;

/*
* This sample callback requires and sets the userHdl parameter.
*/
if (userHdl == NULL)
return VTK_ERR_USER_CALLBACK;

/*
* Convert the application handle to proper type - this
* parameter is set when configuring the context;
* The application determines whether this parameter is set.
*/
signHdl = (struct mySign_st*) userHdl;

if (padding == 1) /* PKCS #1 padding required */
{
/*
* The digest parameter contains the DER encoding of the
* data that needs to be encrypted with the private key.
* The resulting data needs to be written to the sigOut
* buffer and the length set in the sigOut->len field.
* The Toolkit allocated the data in sigOut
* structure and it is of size maxSigOutBuf.
*/

/*
* The application performs the following:
* -generate the signature on digest buffer
* -write resulting signature to sigOut->dPtr
* buffer setting the sigOut->length; the toolkit
* has allocated space in sigOut buffer of size
* maxSigOutBuf
*/


} else
return VTK_ERR_USER_CALLBACK;


return VTK_OK;
} /* myOCSPRequestSignCallbackFunction */

prevnext


ValiCert, Inc.
http://www.valicert.com
Voice: +1.650.567.5469
Fax: (+1.650.254.2148
support@valicert.com