Writing ASP Code to Access Certificate Server Functionality | Programming Microsoft Visual InterDev 6.0

In addition to writing ASP code to read client certificates, you can also write ASP code to interface with Certificate Server itself. As we saw in the earlier section on Certificate Server architecture, the product exposes several COM interfaces for external applications to take advantage of. In this way, you can create specialized applications that truly extend Certificate Server and integrate your own business rules regarding the issuance, renewal, and revocation of digital certificates. By customizing Certificate Server in this way, you can also reduce the amount of manual administration that is required to run your Certificate Authority services.

In Table 23-1 in "Installing Certificate Server," we saw some of the interfaces that Certificate Server exposes. To be able to call them from within our ASP code, we need to determine the program IDs (PROGIDs) for these components. Table 23-4 lists the PROGIDs for each of these interfaces.

Table 23-4. The PROGIDs for each of the interfaces exported or imported by the Certificate Server server engine. These PROGIDs can be used to communicate with Certificate Server via ASP Web pages.

*Interface*	*PROGID*
ICertAdmin	CertificateAuthority.Admin
ICertConfig	CertificateAuthority.Config
ICertGetConfig	CertificateAuthority.GetConfig
ICertPolicy	CertificateAuthority.Policy
ICertRequest	CertificateAuthority.Request
ICertServerExit	CertificateAuthority.ServerExit
ICertServerPolicy	CertificateAuthority.ServerPolicy

NOTE
One trick for finding the appropriate PROGIDs for any server-side components that you have installed on your machine is to use the Microsoft Transaction Server Explorer within the Microsoft Management Console. You can create a dummy package and then choose the option to add components that are already registered into the package. By doing this, you'll see a list of COM components that are registered on your system. When you have found the PROGIDs that you're looking for, simply choose to cancel the operation.

Determining Certificate Disposition

The code below shows how to use the CertificateAuthority.Admin and CertificateAuthority.Config components to determine the current disposition of a client certificate. Both of these components are instantiated by using the now familiar <OBJECT> tag with the appropriate PROGID. The code is taken from the Disposition.asp page included in the Certificate Web project on the CD-ROM.

 <%@ Language=VBScript %> <HTML> <HEAD> <META NAME="GENERATOR" Content="Microsoft Visual Studio 6.0"> </HEAD> <BODY> <H2>Client Certificate (Disposition) Sample</H2> <HR> <OBJECT RUNAT=server PROGID=CertificateAuthority.Admin      id=objAdmin> </OBJECT> <OBJECT RUNAT=server PROGID=CertificateAuthority.Config      id=objConfig> </OBJECT> <% If Len(Request.ClientCertificate("Subject")) = 0 Then     Response.Write _         "This sample page requires a client certificate." Else     strSerialNumber = _         Request.ClientCertificate("SerialNumber")     strConfig = objConfig.GetConfig(0)     disposition = _         objAdmin.IsValidCertificate(strConfig, strSerialNumber)     Select Case disposition         Case 1             strDisp = "Call did not complete"         Case 2             strDisp = "Call failed"         Case 3             strDisp = "Certificate revoked"         Case 4             strDisp = "Certificate still valid"         Case 5             strDisp = "Certificate never issued"         Case 6             strDisp = "Taken under submission"     End Select     Response.Write "Configuration: " + strConfig + "<P>"     Response.Write "SerialNumber: " + strSerialNumber + "<P>"     Response.Write "Certificate disposition is <B>" + _         strDisp + "</B>" End If %> </BODY> </HTML>

The page reads the client certificate presented by the browser and determines its SerialNumber key value by using the Request.ClientCertificate("SerialNumber") syntax. Next the GetConfig method of the Certificate-Authority.Config component is used to get the default configuration string for the certificate server. This configuration string uniquely identifies the certificate server by including the machine name and the name of the root CA. Next the IsValidCertificate method of the CertificateAuthority.Admin component is used to determine the disposition of the certificate. There are six disposition types, as shown in the code above. When calling the IsValidCertificate method, the serial number of the certificate and the configuration string for the certificate server are passed as arguments. Figure 23-12 shows an example of the resulting output from the Disposition.asp page.

click to view at full size.

Figure 23-12. Output from the Disposition.asp page showing the configuration string for the Certificate Server, the serial number of the presented client certificate, and the Certificate's disposition.

Revoking a Certificate

When a certificate is revoked, a user can no longer use his or her certificate to access your application. Revoking a certificate is useful, and often highly necessary, in cases where employees leave a company or when you need to quickly deny access to your application.

Certificates are most commonly revoked using the Certificate Server Log Administration page. This page is accessible by clicking the Certificate Administration Log Utility hyperlink on the main administration page of Certificate Server. The list view of this page can be found at http://localhost/certsrv/wcalist.asp. To revoke a certificate, you'll need to switch over to the form view by choosing a certificate to revoke. Figure 23-13 shows the Certificate Form Viewer with the Revoke button displayed at the bottom of the page.

click to view at full size.

Figure 23-13. The Certificate Form Viewer showing the details of a client certificate and the Revoke button for revoking the certificate.

In your applications, you might want to automate features such as certificate revocation. You can do this from within your ASP code. For example, say you want to automatically revoke a certificate if your business partner becomes more than sixty days overdue in your accounts receivable database. To programmatically revoke a certificate, you can use the CertificateAuthority.Admin component, as shown in the code below.

 <OBJECT RUNAT=server PROGID=CertificateAuthority.Admin      id=objAdmin> </OBJECT> <% objAdmin.RevokeCertificate strConfig, strSerialNumber, 0, 0 %>

To revoke a certificate, call the RevokeCertificate method of the CertificateAuthority.Admin component and pass it four parameters:

The configuration string for the Certificate Server

The serial number of the certificate that you want to revoke

The revocation reason (0 means an unspecified reason)

The date at which the revocation becomes effective (0 means the current GMT time)