How to Parse a Certificate Using Active Server Pages (ASP)

Updated: December 1996

Contents
The Request Object ClientCertificate Collection
Request Object Interface for Java
Request Object Interface for C++
Request Object Interface for Visual Basic

By providing a built-in object (Request) and collection (ClientCertificate) supporting certificates, ASP makes it very easy for Webmasters to parse a certificate when authenticating a client.

The Request Object ClientCertificate Collection

The Request object retrieves the values that the client browser passed to the server during an HTTP request using the syntax:

Request[.Collection](variable)

The Request object supports the ClientCertificate, Cookies, Forms, QueryString, and ServerVariables collections. (For more information on ASP Objects, please consult the ASP Object Reference.)

The ClientCertificate collection is of interest as it retrieves the certification fields (specified in the X.509 standard) from the request issued by the Web browser.

If a Web browser uses the SSL3.0/PCT1.0 protocol to connect to a server and the server requests certification, the browser sends the certification fields.

If no certificate is sent, the ClientCertificate collection returns EMPTY.

Before you can use the ClientCertificate collection, you must configure your Web server for SSL and to request client certificates. For more information see How to Set Up SSL in IIS 3.0 and How to Set Up Client Authentication in IIS 3.0.

Syntax

Request.ClientCertificate( Key[SubField] )

Parameters

Key

Specifies the name of the certification field to retrieve. A client certificate consists of the following fields.

Value	Meaning
Subject	A string that contains a list of subfield values that themselves contain information about the subject of the certificate. If this value is specified without a SubField, the ClientCertificate collection returns a comma-separated list of subfields. For example: "C=US, O=Msft, ".
Issuer	A string that contains a list of subfield values containing information about the issuer of the certificate. If this value is specified without a SubField, the ClientCertificate collection returns a comma-separated list of subfields. For example: "C=US, O=Verisign, ".
ValidFrom	A date specifying when the certificate becomes valid. This date follows VBScript format and varies with international settings. For example: in the U.S.: 9/26/96 11:59:59 PM.
ValidUntil	A date specifying when the certificate expires.
SerialNumber	A string that contains the certification serial number as an ASCII representation of hexidecimal bytes separated by hyphens (-). For example: "04-67-F3-02".
Certificate	A string containing the binary stream of the entire certificate content in ASN.1 format.
Flags	A set of Flags that provide additional client certificate information. The following flags may be set: ceCertPresent - A client certificate is present. ceUnrecognizedIssuer - The last certification in this chain is from an unknown issuer. Note To use the preceding flags you must include the client-certificate include file in your ASP page. If you are using VBScript, include Cervbs.inc. If you are using JScript, include Cerjavas.inc. These files are installed in the \Inetpub\ASPSamp\Samples directory.

SubField

An optional parameter you can use to a retrieve an individual field in either the "Subject" or "Issuer" keys. This parameter is added to the Key parameter as a suffix. For example: "IssuerO" or "SubjectCN". The following table lists some common SubField values.

Value	Meaning
C	Specifies the name of the country of origin.
O	Specifies the company or organization name.
OU	Specifies the name of the organizational unit.
CN	Specifies the common name of the user. (This subfield is used with the "Subject" key.)
L	Specifies a locality.
S	Specifies a state or province.
T	Specifies the title of the person or organization.
GN	Specifies a given name.
I	Specifies a set of initials.

SubField values other than those listed in the preceding table can be identified by their ASN.1 identifier. The format of the ASN.1 identifier is a list of numbers separated by a period (.). For example: "3.56.7886.34".

Remarks

You can use an iterator to loop through the keys of the ClientCertificate collection. This is demonstrated in the following example.

<%
For Each key in Request.ClientCertificate
   Response.Write( key & ": " & Request.ClientCertificate(key) & "<BR>")
Next
%>

Examples

The following example uses the Subject key to test whether a client certificate has been presented.

<%
If Len(Request.ClientCertificate("Subject")) = 0
    Response.Write("No client certificate was presented")
End if
%>

The following example retrieves the common name of the company that issued the client certificate.

<%= Request.ClientCertificate("IssuerCN") %>

The following example checks the organization name of the subject of the client certification.

<% 
If (Request.ClientCertificate("SubjectO")="Msft")
   Response.Write("Good Choice!")
End if
%>

The following example displays the expiration date of the client certificate.

This certification will expire on 
<%= Request.ClientCertificate("ValidUntil") %>

The following example uses the Flags key to test whether the issuer of the certificate is known. The include statement in the first line enables this script to use the named flag ceUnrecognizedIssuer.

<!--#include file="cervbs.inc" -->
<%
   if Request.ClientCertificate("Flags") and ceUnrecognizedIssuer then
      Response.Write "Unrecognized issuer"
   end if 
%>

The following example displays all the fields of a client certificate.

Serial number: <%=Request.ClientCertificate("SerialNumber")%><br>
Issuer org: <%=Request.ClientCertificate("IssuerO")%><br>
Subject name: <%=Request.ClientCertificate("SubjectCN")%><br>
Not before: <%=Request.ClientCertificate("ValidFrom")%><br>
Not after: <%=Request.ClientCertificate("ValidUntil")%><br>
<%cer=Request.ClientCertificate("Certificate")%>
Issuer: <%=Request.ClientCertificate("Issuer")%><br>
Subject: <%=Request.ClientCertificate("Subject")%><br>
Certificate Raw Data: <%=cer%><br>
Certificate length: <%=len(cer)%><br>
Certificate Hex Data:
<%for x=1 to 100%><%=hex(asc(mid(cer,x,1)))%>&nbsp;<%next%>

Back to contents

Request Object Interface for Java

Active Server Pages implements interfaces that enable your component to access the properties and methods of the ASP built-in objects, including the Request Object. The IScriptingContextinterface contains methods that return interfaces to the built-in objects. Your component can then use these object interfaces to access the methods and properties of the built-in objects.

The Java type libraries are not installed with Active Server Pages. If you are using Microsoft Visual J++™, you can generate classes from the the Microsoft Active Server Pages Object Library with the Java Type Library Wizard. This wizard can be reached from the Tools menu.

To use the built-in object interfaces in a Java component, you must import the ASP classes into your code as shown below.

import asp.*;

IRequest Interface

The IRequest interface enables your component to use the methods and properties of the Request object.

public interface asp/IRequest 
    extends com.ms.com.IUnknown
{
    public abstract asp.IRequestDictionary getQueryString();
    public abstract asp.IRequestDictionary getCookies();
    public abstract asp.IRequestDictionary getServerVariables();
    public abstract asp.IRequestDictionary getForm();
    public abstract asp.IRequestDictionary getClientCertificate();
    public abstract java.lang.Object getItem(java.lang.String);
}

Back to contents

Request Object Interface for C++

Active Server Pages implements interfaces that enable your component to access the properties and methods of the ASP built-in objects. The IScriptingContext interface contains methods that return pointers to the built-in object interfaces. Your component can then use these object interfaces to access the properties and methods of the built-in objects, or interfaces to the Response object collection.

To use the IScriptingContext and object interfaces in a C++ component, you must include the header file Asptlb.h as shown in the following code. This file is installed with the Active Server Pages feature in the directory \Inetsrv\Asp\Cmpnts\.

#include "asptlb.h"

To create a component that uses the ActiveX™ Template Library (ATL) 1.1, you should install ATL on your machine and then select "ATL COM Appwizard" when creating a new project workspace in Microsoft® Visual C++®.

IRequest

This interface exposes methods that access the collections of the Request object.

Method	Description
get_ClientCertificate	Retrieves the ClientCertificate collection.
get_Cookies	Retrieves the Cookies collection.
get_Form	Retrieves the Form collection.
get_Item	Retrieves an item from the Requestcollection by looking for the first match in the QueryString, Form, Cookies, ClientCertificate, and ServerVariables collections.
get_QueryString	Retrieves the QueryString collection.
get_ServerVariables	Retrieves the ServerVariables collection.

Note This interface also supports the IUnknown and IDispatch methods. For more information, see \Inetsrv\Asp\Cmpnts\Asptlb.h, the header file installed with Active Server Pages.

Back to contents

Request Object Interface for Visual Basic

Active Server Pages implements classes that enable your component to access the properties and methods of the ASP built-in objects. The ScriptingContext class contains methods that return an interface to one of the ASP built-in objects. Your component can use these interfaces to access the methods and properties of the built-in objects.

To use the ScriptingContext and built-in object interfaces in a Visual Basic component, you must load the Microsoft Active Server Pages Object Library (asp.dll) into your available references. This file is installed with the Active Server Pages feature in the directory \Inetsrv\Asp\.

Note If you are using Microsoft® Visual Basic® 5.0, you should create your component as an ActiveX DLL and not an ActiveX Control.

Request

This class contains methods that enable your component to use the methods, properties, and collections of the Requestobject.

Method	Description
ClientCertificate() As IRequestDictionary	Collection of client certificate fields (specified in the X.509 standard).
Cookies() As IRequestDictionary	Collection of cookies sent as part of the request (read-only).
Form() As IRequestDictionary	Collection of form elements.
Item(bstrVar As String) As Object	Retrieves the specified item from the Request collections.
QueryString() As IRequestDictionary	Collection of query string values.
ServerVariables() As IRequestDictionary	Collection of predetermined environment variables.

Back to contents

Back to Client Authentication in IIS page