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"); }