Getting Detailed Revocation Information
Using the Toolkit

prevnext

Getting Detailed Revocation Information

The Toolkit allows an application to retrieve detailed revocation information for a single certificate using either the Vtk_ValidationGetRevStatus or Vtk_ValHdlGetRevStatus validation function. The application can request detailed revocation information for the entire validation response or a single certificate. The detailed revocation information is returned in the Vtk_ValRespDetails or Vtk_ValRespSingleCertDetails structure.

To use the Vtk_ValHdlGetRevStatus function, an application can add a certificate to the validation query with a validation handle using Vtk_ValidationAddCert or Vtk_ValidationAddCertRaw functions. Alternatively, the application can use the Vtk_ValidationGetValHdl function.

If the application requests detailed revocation information (either respDetails or certDetails) but this information is not available in the response, the function returns VTK_OK, but the return values in the structure are not set.

Code Sample for Obtaining Revocation Information

The following code sample shows how to obtain revocation information after certificate validation.


/*
*
* GetRevocationInfo
* Parameters:
* pCtxt - pointer to Toolkit context
* pUserCert - certificate which will be validated
* pIssuerCert - issuer certificate of the user certificate
*/

void GetRevocationInfo(Vtk_Ctxt *pCtxt, const Vtk_Cert *pUserCert, const Vtk_Cert *pIssuerCert)
{
Vtk_Validation *pVal = NULL;
Vtk_uint32 ret, status;
Vtk_ValHdl *pHdl = NULL;

/*
* Create a Validation structure.
* Validation structures encapsulate the validation query sent to * the VA. The application can send the query using any of the
* supported validation protocols.
*/
pVal = Vtk_ValidationNew(pCtxt);assert(pVal);


/*
* Add the passed in certificate to the validation structure.
* For each certificate to be validated, the Toolkit requires the
* CA certificate as well as the certificate to be validated.
*
* The function will also set the validation handle (Vtk_ValHdl)
* which can be used to obtain validation details for user
* certificates.
*
*/
ret = Vtk_ValidationAddCert(pCtxt, pVal, pUserCert, pIssuerCert,
&pHdl);
if (ret != VTK_OK)
{
showError("Vtk_ValidationAddCert", ret);
goto done;
}

/*
* Vtk_ValidationValidate
*
* Performs certificate validation.
*/
ret = Vtk_ValidationValidate(pCtxt, pVal, &status);
if (ret != VTK_OK)
{
showError("Vtk_ValidationValidate", ret);
goto done;
}



/*
* Displays validation response details using the validation
* handle, that is, the Vtk_ValHdl structure.
*/
displayValidationDetailsHdl(pCtxt, pHdl, pVal);


/*
* IMPORTANT
*
* Alternatively, if the validation handle is not available, an
* application can get validation details using the user and
* issuer certificate pair.
*/
displayValidationDetails(pCtxt, pVal, pUserCert, pIssuerCert);


done:

/* Cleanup memory */

if (pVal)
Vtk_ValidationDelete(pVal);

if (pHdl)
Vtk_ValHdlDelete(pHdl);
}


/*
* displayValidationDetailsHdl
*
* Displays validation response details using the validation
* handle, that is, the Vtk_ValHdl structure.
*
* The Vtk_ValHdl is used to obtain detailed validation information
* for a particular certificate in the validation query.
* The Vtk_ValRespDetails structure details revocation information
* for the entire validation response. It includes header
* information common to all responses and header information
* specific to the OCSP, CRT, or CRL protocol.
*
* The Vtk_ValRespSingleCertDetails structure represents validation
* information for a specific certificate.
*
* Parameters:
* pCtxt - pointer to Toolkit context
* pHdl - validation handle which identifies the
* certificate
* pVal - pointer to validation query structure that
* contains the validated user certificate
*
*/
void displayValidationDetailsHdl(const Vtk_Ctxt *pCtxt,
const Vtk_ValHdl *pHdl, const Vtk_Validation *pVal)
{
Vtk_ValRespDetails *hdr = NULL;
Vtk_ValRespSingleCertDetails *certDetails = NULL;
Vtk_uint32 ret, status;

assert(pHdl);

/*
* Obtain validation details using a validation handle. The
* validation handle can be created using the
* Vtk_ValidationAddCert, Vtk_ValidationAddCertRaw, or the
* Vtk_ValidationGetValHdlfunction.
*
*/
if ((ret = Vtk_ValHdlGetRevStatus(pCtxt, pHdl, &status, &hdr,
&certDetails)) != VTK_OK)
{
showError("Vtk_ValHdlGetRevStatus", ret);
return;
}

if (hdr)
{
/* Print Validation Header information. */
printRespHdr(hdr);
Vtk_ValRespDetailsDelete(hdr);
}

if (certDetails)
{
/* Print single certificate validation information. */
printRespCertDetails(certDetails);
Vtk_ValRespSingleCertDetailsDelete(certDetails);
}

return;
}



/*
* displayValidationDetails
*
* Display validation response details using the user and issuer
* certificate pair.
*
* Parameters:
* pCtxt - pointer to Toolkit context
* pVal - pointer to validation query structure that
* contains validated user certificate
* pUserCert - user certificate
* pIssuerCert - issuer certificate
*/
void displayValidationDetails(const Vtk_Ctxt *pCtxt,
const Vtk_Validation *pVal, const Vtk_Cert *pUserCert,
const Vtk_Cert *pIssuerCert)
{
Vtk_ValRespDetails *hdr = NULL;
Vtk_ValRespSingleCertDetails *certDetails = NULL;
Vtk_uint32 ret, status;

assert(pUserCert);
assert(pIssuerCert);

/*
* Obtain validation details using the certificate pair.
*/
if ((ret = Vtk_ValidationGetRevStatus(pCtxt, pVal, pUserCert,
pIssuerCert, &status, &hdr, &certDetails)) != VTK_OK)
{
showError("Vtk_ValidationGetRevStatus", ret);
return;
}


if (hdr)
{
/* Print Validation Header information. */
printRespHdr(hdr);
Vtk_ValRespDetailsDelete(hdr);
}

if (certDetails)
{
/* Print single certificate validation information. */
printRespCertDetails(certDetails);
Vtk_ValRespSingleCertDetailsDelete(certDetails);
}
return;
}


/*
* Display contents of a Vtk_ValRespDetails structure
*/
void printRespHdr(const Vtk_ValRespDetails *hdr)
{
const char* protocols[] = { "CRT", "OCSP", "CRL" };
char *issuer;


/*
* Print Validation Header information.
*/
printf("\nValidation response Header...");
printf("\n\tProtocol %s,", protocols[hdr->type - 1]);
printf("\n\tVersion: %d,\t Issue time: %s", hdr->version,
ctime(&hdr->issueTime));

/*
* Either the issuerIdByName or issueridByKey will be set.
*/
if (hdr->issuerIdByName)
issuer = (char*)hdr->issuerIdByName->dPtr;
else
issuer = (char*)hdr->issuerIdByKey->dPtr;

printf("\tIssuer: %s", issuer);

/*
* Display additional, protocol specific details.
*/
if (hdr->type == VTK_VM_CRT)
{
printf("\n\tCRT next update: %s",
ctime(&hdr->d.crt->nextUpdate));
printf("\tCRT valid until: %s",
ctime(&hdr->d.crt->validUntil));
}
}

/*
* Print contents of a Vtk_ValRespSingleCertDetails structure.
*/
void printRespCertDetails(const Vtk_ValRespSingleCertDetails
*certDetails)
{
printf("\nSingle certificate details...");

if (certDetails)
{
printf("\n\tThis update: %s",
(certDetails->thisUpdate == -1 ? "not specified" :
ctime(&certDetails->thisUpdate)));
printf("\tNext update: %s",
(certDetails->nextUpdate == -1 ? "not specified" :
ctime(&certDetails->nextUpdate)));

/*
* If this certificate is revoked, there may be additional
* information.
*/
if (certDetails->certStatus & VTK_STATUS_REVOKED)
{
/*
* revocation time is optional parameter -1 means not set
*/
if (certDetails->revocationTime != -1)
printf("\n\tRevocation time: %s",
ctime(&certDetails->revocationTime));

/* revocation reason is optional field -1 means not set */
if (certDetails->revocationReason
!= VTK_REV_STATUS_UNKNOWN)
printf("\tRevocation reason: %d",
certDetails->revocationReason);
else
printf("\tRevocation reason not specified.");
}
}

printf("\n\n");
}

prevnext


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