Web Page Access Control Using PKI

Introduction

Limited access to Web pages can be implemented through the use of Personal PKI certificates and client side SSL connections. Access can be limited to holders of personal PKI certificates issued by a particular institution such as Dartmouth College or even specific individuals. In such an SSL connection, the web server specifies that the user must open their end of the connection with a personal private key/public certificate. Once the client side SSL connection is established, the web server has access to the contents of the user's public key certificate. An application using this connection in turn uses this information to authenticate the user and decide whether to authorize access to the application. Setting up the server side of the application obviously depends on the web server software being used. The details below explain how to use the Apache v1.3 web server and Microsoft Internet Information Services (IIS) Version 5.1 on Windows XP Professional. 

Please note that IIS on Windows XP Professional is limited to 10 simultaneous connections and that IIS on server operating systems (Windows 2000 Server, Windows server 2003) is designed for scalable Web sites and the information presented here also applies to the server versions of IIS.

Apache v2.0 doesn't need mod_ssl. Other web servers that support SSL should also work by configuring features similar to those described below.

Apache v1.3 WEB Server Setup

Apache v1.3 web servers need to have the module "mod_ssl" installed. Follow these steps to install and configure the Apache web server:

  1. Install an Apache server with mod_ssl. Read through the Apache documentation for step-by-step instructions on how to do this.
  2. Verify that the Apache server is working by connecting to the server with a web browser.
  3. Create the public/private key pair for the apache server with openssl. From the Unix shell, type
    openssl req -newkey rsa:1024 -keyout server.key -out serverreq.csr
    The private key for the web server is now in the key.pem file. Move this file to the apache/conf/ssl.key/ directory. Set its permission to be read-only for the root account. If you provided a password during the key generation, this password will be required each time you start or restart the server. If you are willing to compromise security for convenience, leave the key without a password to protect it.
  4. Request a certificate for the web server's public key from your institutional Certificate Authority.
    To use Dartmouth's local CA. Go to https://collegeca.dartmouth.edu/ManServerEnroll.html and paste in the contents of the file serverreq.csr. Submit the form, and email the CA administrator that you have sent in a request. When the request is approved (you'll get an email response with instructions to follow), retrieve the certificate with a web browser, and put the PEM encoding of the certificate (copied from the retrieval web page) into a file called server.crt. Note, you do not want the PKCS#7 certificate chain, but rather the cert described as "Base 64 encoded certificate."
  5. Install the web server's certificate by putting the server.crt file into the apache/conf/ssl.crt/ directory.
  6. Install your institution's root certificate.
    For the Dartmouth CA certificate copy the following PKCS#7 text to the file apache/conf/ssl.crt/dartmouthca.crt 
-----BEGIN CERTIFICATE-----
MIIEEgYJKoZIhvcNAQcCoIIEAzCCA/8CAQExADAPBgkqhkiG9w0BBwGgAgQAoIID
4zCCA98wggLHoAMCAQICAQIwDQYJKoZIhvcNAQEFBQAwdzETMBEGCgmSJomT8ixk
ARkWA2VkdTEZMBcGCgmSJomT8ixkARkWCWRhcnRtb3V0aDELMAkGA1UEBhMCVVMx
GjAYBgNVBAoTEURhcnRtb3V0aCBDb2xsZWdlMRwwGgYDVQQDExNEYXJ0bW91dGgg
Q2VydEF1dGgxMB4XDTAzMDEwOTA1MDAwMFoXDTEzMDEwOTA1MDAwMFowdzETMBEG
CgmSJomT8ixkARkWA2VkdTEZMBcGCgmSJomT8ixkARkWCWRhcnRtb3V0aDELMAkG
A1UEBhMCVVMxGjAYBgNVBAoTEURhcnRtb3V0aCBDb2xsZWdlMRwwGgYDVQQDExNE
YXJ0bW91dGggQ2VydEF1dGgxMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC
AQEA4N+iD9S5TiAm1z5SxHoiEa0I3CyG7uOc19G1Dz38HiJST4I406/KDgV5MyIY
kXDHQ4BPaO4iDroHMv2R1Z05YelvHmQ8LG5tKH1Y6yNrDJhDR+2a3uNx8PwH/zqR
ElPPuZg4pK4KMzlu/nU3Znjg/dQVZQAipipCuF+QBQ5qqCrQW7jNWW1Xc2qv3how
iTIZ4rfrK6ByUYORSBMIKMADXvOf4lXQfMUwXBJ8uH5udzzGcyzj7Pm5GTgi0yqB
88Ujex28nVZpDxiPH6Bzg/eQuj+ZqIh6lscYO5nb31OY923nUQNQIa66aD9VsIt1
t+qC1An50u1xJ7Tslvmt0RK+tQIDAQABo3YwdDARBglghkgBhvhCAQEEBAMCAAcw
DwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUP8DWx6dPAH7vBplnbLyWHk2jdxIw
HwYDVR0jBBgwFoAUP8DWx6dPAH7vBplnbLyWHk2jdxIwDgYDVR0PAQH/BAQDAgGG
MA0GCSqGSIb3DQEBBQUAA4IBAQCoYpxiFn+s/OUpZXjp+tfBgrOEUyWLZXIeMWmt
YV/xn3GWoYd0Zg7gS684Jes++E2aGNxMvtGL1MYPGbFCC/eYxfVWfnnW+RPO7leh
len/UB8pCRUmu+MzeTnOZlH3qHhnpy5DR4fy/pu6J6zqHO4UTZmUWF3bTVOE5S+k
VHOUoyfKIF6pXY/TtHieiugFm7sK52pDoWTYNtGRfNX8f4rdw++gUnduJ8lQo8Ff
AqSsb5zN8X8K5T635dNR6wMrZxPcyD13X170rKiIl7Va4AN0N2xH6tSis+e/+FMj
tXQxHRXz1zMNciVhwIeUm2YJNxAsqAjiQNeFfXCddkt0Gm9cMQA=
-----END CERTIFICATE-----
  1. Modify the httpd.conf file to look in the appropriate places for certs. Modify the paths for the following directives.
    1. SSLCertificateFile /path/to/server.crt
    2. SSLCertificateKeyFile /path/to/server.key
    3. SSLCertificatePath /path/to/apache/conf/ssl.crt
    4. SSLCARevocationPath (supplied only if CRLs will be used)
      Note: if you do not keep up with the CRLs, and it becomes invalid, then no users will be able to access your site. For now, we recommend not using this directive.
  2. Change to the conf/ssl.crt directory and run make. This sets up the apropriate links for the certificates and CRLs.
  3. Modify the httpd.conf file to allow for ".sslaccess" files.
    1. Add the line "AccessFileName .sslaccess" to the httpd.conf file right after the SSLEngine on directive.
      Note: the default file file is usually ".htaccess"; using a different name prevents a server without mod_ssl installed from having problems interpreting the SSL directives.
  1. Restart the server by typing /path/to/server/bin/apachectl startssl The password that protects the key is required for this step.
  2. Verify that this works by attempting to connect to a protected web page. (how to protect pages is explained in the next section.) Make sure that you have set up your web browser to ask you every time it submits a cert, to see the process, otherwise an appropriate cert will be picked invisibly to you, and you'll just get connected.

Apache File Directory Setup

Assuming ".sslaccess" has been defined as suggested above, follow these steps to set up file server directories to require client authentication via SSL:

  1. In the .htaccess file set the directive: 
deny from all
  1. Create ".sslaccess" files to allow users to control access to their directories. For each of these directories, add the following mod_SSL directives to the file:
 
SSLVerifyClient require
SSLVerifyDepth 5

to the .sslaccess file. If you use the SSLVerifyClient optional directive, some clients may not be able to access the site, even though client certs are not required. Notably, IE5 on the Mac will not be able to work properly, though Mozilla and Netscape 4.7.9 have the proper behavior.

The mod_SSL directives specify the access rules. The "SSLVerifyClient require" directive requires that the user begin an SSL session with a personal certificate. The "SSLVerifyDepth 5" directive limits the number of certificates that can be in the chain of signatures. (Additional information on configuring mod_ssl can be found at:http://www.modssl.org/docs/2.8/)

The server can be additionally configured to check a CRL for revoked certificates. To do this complete the "SSLCARevocationPath" directive described in the server setup section and copy the CRL file to this location from the CA's LDAP directory. Note: it is however critical to keep this file up to date as the CA issues new CRLs. If the CRL becomes invalid, then no users will be able to access your site. (An example CRL Update script to do this is coming soon.)

The web site needs to be self contained, ie. references from a secure page to an insecure (file or image) will cause alerts to report that there is "insecure content which is not displayed on the secure page". Within the site URL references must either be to https URLs or should be relative so once you've started an SSL connection you don't jump back unintentionally to an unsecured page. You can make part of a web site secure by placing an .sslaccess file in the sub-directory you wish to limit.

Microsoft IIS Version 5.1 WEB Server Setup

Follow these steps to install and configure the Microsoft IIS web server to use client certificates on Windows XP Professional:

  1. If you don’t already have an IIS installation running, Install and verify IIS.
  2. Open the Microsoft Management Console for IIS.  This console will be used throughout these procedures.
  3. Configure IIS to use a server certificate.  A server certificate identifies your server to clients and is the foundation for secured communications using SSL.
    1. If you don’t already have a server certificate you must generate a server certificate. 
    2. Install the server certificate.
  4. Enable secured communications via SSL.   
  5. Configure IIS to use client certificates.  Client certificates identify clients to the server.
  6. Add your institution's CA certificate to the Certificate Trust List (CTL) on the IIS server.  Note that each Web site on an IIS server may have a different CTL.  Instructions for retrieving Dartmouth’s CA certificate can be found here.
  7. Add your institution’s CA certificate to the server’s certificate store.  If this step is not done (i.e. the CA certificate is not in the server’s certificate store) your browser may present an empty client certificate selection dialog box or you may fail to connect.
  8. Verify this works by connecting to a protected web page.  Make sure that you have set up your web browser to ask you every time it submits a certificate, to see the process, otherwise an appropriate certificate will be picked invisibly to you, and you'll just get connected if your browser has a valid certificate.

Client Setup

In order to access a Client Side SSL protected directory, the end user must have acquired a PKI certificate from an acceptable Certificate Authority (CA) and use it to begin the SSL session. An acceptable CA has its certificate(s) installed in the Apache server configuration files or the IIS CTL for the Web site. (If you wish to allow access for users having certificates signed by other CAs, these additional CA certificates need to be similarly copied into the "apache/conf/ssl.crt/" directory or added to the IIS CTL for the Web site). The SSL protocol proves that the user controls the private key corresponding to the public key found in the personal PKI certificate presented at the beginning of the session. The web server's SSL code checks that the certificate is not expired and is signed by a chain of valid and accepted institutional and root certificates. The server can be additionally configured to check a CRL for revoked certificates.

Application Authorization

It is important to remember that authentication and authorization are separate issues. Any non-trivial application needs to address both questions. The SSL protocol using a client side certificate will have established the identity of the end user by having the web server check the conditions described above. Depending upon the application, satisfying these conditions may be adequate authorization. In addition, the contents of the client certificate are available to the web server in environment variables. An application can implement additional required authorization checking logic using the certificate contents or possibly other information retrieved from other sources.

For example, the current existence in the institutional LDAP directory of an entry having a name matching the CN contained in the DN of the certificate used for SSL in this session may be a reasonable check to insure an individual is either still employed or enrolled at the institution. Other applications need to base their operation on the identity of the user and need to make a connection from the identity obtained from the certificate to whatever function they perform.

Here are some possible authorization conditions, that can be implemented by adding additional code, depending on the needs of the web site or application:

  • The end user must have a valid personal certificate issued by a specific CA
  • The certificate could be checked for some additional content, in it's DN or other fields
  • A script could check for arbitrarily complex certificate values and other conditions, eg. continued presence in the institutional LDAP directory.
  • A database application may search for a field matching the CN found in the certificate and base additional logic on the contents of that database record.

Example Apache Authorization Script

Here is an example PERL script that checks the Apache SSL environment variables after a client side SSL session has been started and "authorizes" the connection by verifying that the certificate used was signed by "Dartmouth College". The "verify_cert" routine could be expanded to include other authorization logic.

Example IIS Authorization Configuration

Authorization using client certificates in IIS is accomplished by Certificate Mapping.  IIS certificate mapping allows certificates to be associated with Windows user accounts, which are in turn used to control access to Web resources.  One-to-one and many-to-one relationships are supported.

Transition from Sidecar to PKI (for Dartmouth Web sites)

A single web site can be setup to use both Sidecar and PKI authentication and authorization controls by running two different web servers on the same part of the file directory tree. The same file tree can be protected by SSL from one server (eg. apache at port 443) and sidecar from another server (apache port 80). The non-SSL server limits access to directories with .htaccess files that contain mod_sidecar directives. The SSL server limits access to directories with .sslaccess files that contain mod_ssl directives. Within the site URL references should be relative so once you've entered from the SSL server side a link won't jump you to the non-SSL server. Make sure that you don't accidentally leave files open to the server on the other side when you do this.

Known Problems

1. There seems to be some bugs in Netcape 4.77 on Mac with client side SSL connections?
if you've got a client side SSL connection going, sometimes a broken key icon is displayed instead of a gif
sometimes a relative address link reports that the page doesn't exist, even when it did exist.
After quitting and restarting Netscape, the page may be found, but graphics won't display 6/17/02

2. When Apache is checking CRLs, the CRL must have a date for the next issue time and it seems it must be at least more than one day later (RH-9/11/02)

3. When configuring Apache/mod_ssl to require personal certificates (SSLVerifyClient require) it is vital that the directory pointed to by SSLCACertificatePath (and all the files inside), or the file pointed to by SSLCACertificateFile be world readable. If these files are not world readable, then Apache will not be able to verify the certificate chain.

Galeon/Mozilla (Linux) error message: 

Could not establish an encrypted connection because your certificate
was rejected by <server>.  Error Code: -12271.

 

Apache error output: 

 
[Tue Oct 22 15:55:59 2002] [error] mod_ssl: Certificate Verification: Error (20): unable to get local issuer certificate
[Tue Oct 22 15:55:59 2002] [error] mod_ssl: SSL handshake failed (server <server>:443, client <client IP>) (OpenSSL library error follows)
[Tue Oct 22 15:55:59 2002] [error] OpenSSL: error:140890B2:lib(20):func(137):reason(178)

Internet Explorer puts up a generic error page. (ow 10/22/02)

4. Versions of Netscape 4.X on Windows don't work well with sites using "SSLVerifyClient". They may prompt for the certificate password each time the SSL connection times out (approx. every 20 secs) and is re-establised by the browser. The settings for when the password for the certificate is required have an effect on this. Requiring the password the "first time" only may prevent the issue.

5. Internet Explorer for Mac (version 5 and later, possibly earlier too) generates an error if you try to connect to a web site that has "SSLVerifyClient" set to "optional". It complains "Security Failure. Personal certificate required." It should instead continue to connect. (Netscape 7.0 on MacOS does the right thing). In order to conitnue to support IE with Sidecar users, a second non-SSL path is needed.

Top
Back to PKI Lab Home

Dartmouth College PKI Lab
Last update: 26 February 2003