An application can check delegated VA certificates and determine whether to accept or reject the certificate used to validate the validation response. An application can do this using the Vtk_DelegatedIssuerCallback function, but only in VA or CA delegated trust paradigms.
The Vtk_Callback structure sets the callback function and parameter for the context. This structure is used only if the option CO_DelegatedIssuerCB 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.
The Toolkit calls your application's callback function when verifying OCSP or CRT responses in delegated mode. In delegated mode, the certificate in the OCSP or CRT response is from a non-trusted VA derived by chaining to the VA's or CA's trusted certificate. This means the signer of the response is not directly part of the trusted VA or CA certificate store.
The Toolkit first checks the context for the chain from the delegated certificate to the trusted root. It then verifies the non-trusted VA's certificate using the trusted certificate. Finally, the Toolkit calls the application's callback function during its checking of OCSP and CRT responses in delegated trust models to see if the certificate should be accepted.
Once the application completes its processing, it returns VTK_OK to indicate that the certificate is good and can be used for validating the response. If the application has detected a problem and does not want the Toolkit to use the certificate to validate the response, it returns a nonzero value.
Code Sample for Checking Delegated Certificates
/* * myDelegatedCallbackFunction * * Delegated issuer check callback function. */ int VTK_CALLBACK myDelegatedCallbackFunction(void *userHdl, const Vtk_Cert *delegatedCert, const Vtk_Cert *trustedCert); /* * DelegatedCtxtCreate * * Creates a ValiCert Validator Toolkit Context configured with * a callback for delegated OCSP/CRT VA trust models. * * Parameters: * appData - application specific data to be passed to the callback */ static Vtk_Ctxt* DelegatedCtxtCreate(struct my_sign_st *appData) { Vtk_Ctxt *ctxt = NULL; Vtk_uint32 retCode; Vtk_CtxtOption ctxtOption; Vtk_Callback cb; /* * Create default toolkit context */ if ((ctxt = Vtk_CtxtNew()) == NULL) return NULL; /* * Set the delegation certificate callback function. * This callback will be used when checking the validation response * from a VA which operates in a delegated model. */ /* * Set my callback structure fields. */ cb.f.DelCertCB = myDelegatedCallbackFunction; /* application function */ cb.userHdl = appData; /* application parameter */ /* * Set ctxt option data */ ctxtOption.option = CO_DelegatedCertCB; /* callback option */ ctxtOption.d.aCB = &cb; /* callback option data */ if ((retCode = Vtk_CtxtSetOption(ctxt, &ctxtOption)) != VTK_OK) { showError("Vtk_CtxtSetOption - CO_DelegatedIssuerCB", retCode); Vtk_CtxtDelete(ctxt); return NULL; } return ctxt; } /* DelegatedCtxtCreate */ /* * myDelegatedCallbackFunction * * The delegation certificate callback function. * This callback will be used when checking the validation response * from a VA which operates in a delegated model. * * This sample function will just display the delegated issuer * certificate. * * Parameters: * userHdl - application specified pointer set when installing the * callback function in the toolkit context * delegatedCert - responder certificate * trustedCert - trusted issuer of the delegatedCert (this is one of * the certificates set in the Vtk_Ctxt) */ int VTK_CALLBACK myDelegatedCallbackFunction(void *userHdl, const Vtk_Cert *delegatedCert, const Vtk_Cert *trustedCert) { myDelegCallback_st *cbStruct; Vtk_uint32 retCode; Vtk_CertInfo *certInfo = NULL; /* * This example has set the userHdl when setting the callback in * the Toolkit context, so it requires the handle in this call. */ if (userHdl == NULL) return VTK_ERR_USER_CALLBACK; cbStruct = (myDelegCallback_st*)userHdl; /* * This function will obtain the details of the VA and its * issuer's certificates. */ /* * The callback function userHdl has stored the Toolkit context * so that it can use it in this call. */ if ((retCode = Vtk_CertGetInfo(cbStruct->ctxt, delegatedCert, &certInfo)) != VTK_OK) { showError("Vtk_CertGetInfo", retCode); /* * Returns VTK_OK, but if needed the application * could return VTK_ERR_USER_CALLBACK to indicate * that it should not trust the VA's certificate. */ return VTK_OK; } /* * Now that we have the certificate details, display them. */ displayCert("Delegated VA certificate", certInfo); /* * No longer need the certificate information; delete it. */ Vtk_CertInfoDelete(certInfo); /* * Get the details of the issuer of the VA's certificate. */ if ((retCode = Vtk_CertGetInfo(cbStruct->ctxt, trustedCert, &certInfo)) != VTK_OK) { showError("Vtk_CertGetInfo", retCode); return VTK_OK; } /* * Display the VA's issuer certificate. */ displayCert("VA's issuer certificate", certInfo); /* * No longer need the certificate information; delete it. */ Vtk_CertInfoDelete(certInfo); return VTK_OK; } /* myDelegatedCallbackFunction */