Web Page Access Control Using PKI

• Introduction
• Server Setup
• File Directory Setup
• Client Setup
• Application Authorization
• Example Authorization Script
• Transition from Sidecar to PKI
• Known Problems

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. 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 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 server.key 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 text to the file apache/conf/ssl.crt/dartmouthca.crt

-----BEGIN CERTIFICATE-----
MIID3zCCAsegAwIBAgIBAjANBgkqhkiG9w0BAQUFADB3MRMwEQYKCZImiZPyLGQB
GRYDZWR1MRkwFwYKCZImiZPyLGQBGRYJZGFydG1vdXRoMQswCQYDVQQGEwJVUzEa
MBgGA1UEChMRRGFydG1vdXRoIENvbGxlZ2UxHDAaBgNVBAMTE0RhcnRtb3V0aCBD
ZXJ0QXV0aDEwHhcNMDMwMTA5MDUwMDAwWhcNMTMwMTA5MDUwMDAwWjB3MRMwEQYK
CZImiZPyLGQBGRYDZWR1MRkwFwYKCZImiZPyLGQBGRYJZGFydG1vdXRoMQswCQYD
VQQGEwJVUzEaMBgGA1UEChMRRGFydG1vdXRoIENvbGxlZ2UxHDAaBgNVBAMTE0Rh
cnRtb3V0aCBDZXJ0QXV0aDEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB
AQDg36IP1LlOICbXPlLEeiIRrQjcLIbu45zX0bUPPfweIlJPgjjTr8oOBXkzIhiR
cMdDgE9o7iIOugcy/ZHVnTlh6W8eZDwsbm0ofVjrI2sMmENH7Zre43Hw/Af/OpES
U8+5mDikrgozOW7+dTdmeOD91BVlACKmKkK4X5AFDmqoKtBbuM1ZbVdzaq/eGjCJ
Mhnit+sroHJRg5FIEwgowANe85/iVdB8xTBcEny4fm53PMZzLOPs+bkZOCLTKoHz
xSN7HbydVmkPGI8foHOD95C6P5moiHqWxxg7mdvfU5j3bedRA1AhrrpoP1Wwi3W3
6oLUCfnS7XEntOyW+a3REr61AgMBAAGjdjB0MBEGCWCGSAGG+EIBAQQEAwIABzAP
BgNVHRMBAf8EBTADAQH/MB0GA1UdDgQWBBQ/wNbHp08Afu8GmWdsvJYeTaN3EjAf
BgNVHSMEGDAWgBQ/wNbHp08Afu8GmWdsvJYeTaN3EjAOBgNVHQ8BAf8EBAMCAYYw
DQYJKoZIhvcNAQEFBQADggEBAKhinGIWf6z85SlleOn618GCs4RTJYtlch4xaa1h
X/GfcZahh3RmDuBLrzgl6z74TZoY3Ey+0YvUxg8ZsUIL95jF9VZ+edb5E87uV6GV
6f9QHykJFSa74zN5Oc5mUfeoeGenLkNHh/L+m7onrOoc7hRNmZRYXdtNU4TlL6RU
c5SjJ8ogXqldj9O0eJ6K6AWbuwrnakOhZNg20ZF81fx/it3D76BSd24nyVCjwV8C
pKxvnM3xfwrlPrfl01HrAytnE9zIPXdfXvSsqIiXtVrgA3Q3bEfq1KKz57/4UyO1
dDEdFfPXMw1yJWHAh5SbZgk3ECyoCOJA14V9cJ12S3Qab1w=
-----END CERTIFICATE-----

7. Modify the httpd.conf file to look in the appropriate places for certificates. 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.
8. Change to the conf/ssl.crt directory and run make. This sets up the apropriate links for the certificates and CRLs.
9. Modify the httpd.conf file to allow for ".sslaccess" files.
   • 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.
10. Restart the server by typing /path/to/server/bin/apachectl startssl The password that protects the key is required for this step.
11. 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 certificate, to see the process, otherwise an appropriate certificate will be picked invisibly to you, and you'll just get connected.

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 apache 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 showing the details of setting up CRL can be found here.)

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.

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. (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). 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

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.

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

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

[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)