C O N T E N T S

HP Secure Web Server Documentation
SSL User Guide
SSL Setup Information
Introduction to SSL
An SSL Primer
Using mod_ssl Directives
Understanding Certificates
Using the Certificate Tool

Using Certificates

Glossary

Chapter 7:
Using Certificates

This chapter tells you how to put certificates to work on your SSL-enabled HP Secure Web Server. There are instructions that will show you how to use mod_SSL, OpenSSL, and the Certificate Tool to set up your server's security. Those commands that require command-line OpenSSL are introduced and explained at the end of this chapter.

__Topics_____________________________________________

How to use certificates

How to test a real server certificate

How to install a VeriSign Global Server ID

How to enforce secure pages selectively

How to create and distribute client certificates

How to implement the FakeBasicAuth option

FAQs

How to use command-line OpenSSL

How to create and view a client revocation list

FAQs

How to use certificates

A self-signed certificate, good for 30 days, is automatically generated for your server when you run CSWS in SSL mode . In a production environment you will normally need to pay for a commercial CA to sign your certificate request so that clients will automatically trust your site.

Important: Once a real certificate has been installed, you should delete the temporary, self-signed certificate (APACHE$SPECIFIC:[CONF.SSL_CRT]SERVER.CRT) that was created during the installation of HP Secure Web Server. This will prevent the accidental use of the temporary certificate if you've installed the real certificate in APACHE$COMMON:[CONF.SSL_CRT] using the same name and your mod_ssl.conf directive uses APACHE$ROOT as part of the certificate file path. For example:
SSLCertificateFile /apache$root/conf/ssl_crt/server.crt
Because APACHE$ROOT is a search-listed logical name, the server will first look in APACHE$SPECIFIC:[CONF.SSL_CRT] and then in APACHE$COMMON:[CONF.SSL_CRT] for the server.crt file. If you've used the same name as the temporary certificate file, the server will find that one first.

How to test a real server certificate

You can test a real server certificate by using a CA's trial program. For example, you can test VeriSign's Secure Server ID.

Follow these steps to install a CA's certificate (also referring to your CA's instructions as they apply to Apache with mod_ssl):

In the OpenSSL Certificate Tool generate a certificate request using Option 3. Create a Certificate Request (using the default responses in most cases).

Send the .CSR file generated by Step 1, or the contents of the file, to the CA by secure email or whatever submission process is provided.

To copy the .CSR file contents, exit the Certificate Tool and use TYPE or EDIT to copy the contents.

Receive the digitally signed certificate file by secure email or another means.

After making backups, replace the existing .CRT file or replace its contents with the one you have received from the commercial CA. Also replace the existing .KEY file with the new one that was generated with the certificate request (but not sent to the CA). The SERVER.CSR (certificate request) file is no longer needed.
To copy the files:

$ COPY SERVER.CRT APACHE$SPECIFIC:[CONF.SSL_CRT]
$ COPY SERVER.KEY APACHE$SPECIFIC:[CONF.SSL_KEY]

To edit the CRT file (first make it writable):

$ EDIT APACHE$SPECIFIC:[CONF.SSL_CRT]SERVER.CRT

! Before pasting the contents of the new certificate, make sure you eliminate line breaks (caused by some mail programs) if necessary by pasting into a text editor first.

Restart the server after verifying that all CSWS processes have stopped.

$ @SYS$STARTUP:APACHE$SHUTDOWN.COM

$ @SHOW SYSTEM/PROC=APACHE*

$ @SYS$STARTUP:APACHE$STARTUP.COM

Test your new server certificate in a client browser using the https:// prefix.

You should receive a security alert because the site certificate of the root CA corresponding with the trial server certificate will not be in your browser.

On installing a paid-for version of a VeriSign certificate, such a warning would not be shown because its root CA site certificate would already be in the certificate store of your browser.

Important: You have secured the web server, but this security only applies to those pages that clients access using https://. Pages accessed with the standard http:// are not secure. Therefore to implement a secure site or a site with secure and unsecured pages, you must specify which pages may only be viewed with a secure connection.

How to install a VeriSign Global Server ID

Please be aware of the client requirements before installing a VeriSign Global Server ID (GSID).

The following instructions configure the Global Server ID server certificate in the system-specific configuration directory and the Intermediate CA certificate in the common configuration directory. If this is not appropriate for your site, the location of the Intermediate CA certificate can be placed in the system-specific configuration directory.

Obtain a Global Server ID from VeriSign.

Generate a certificate request file.

Download and install the Intermediate CA certificate.

Click the link for Intermediate-CA.

Copy and paste the entire text of the Intermediate CA certificate, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines, into a file named:

APACHE$COMMON:[CONF.SSL_CRT]INTERMEDIATE-CA.CRT

! Before pasting the contents of the new certificate, make sure you eliminate line breaks (caused by some mail programs) if necessary by pasting into a text editor first.

Add the following directive to your APACHE$COMMON:[CONF]MOD_SSL.CONF file, within the <VirtualHost> section that defines your secure web server and with the other SSL directives:

SSLCertificateChainFile /apache$common/conf/ssl_crt/intermediate-ca.crt

Install the Server Certificate.

Place the server certificate you received from VeriSign and the key you generated in the certificate directories, respectively:
$COPY SERVER.CRT APACHE$SPECIFIC:[CONF.SSL_CRT]SERVER.CRT

$COPY SERVER.KEY APACHE$SPECIFIC:[CONF.SSL_KEY] SERVER.KEY
Add the following directives to your APACHE$COMMON:[CONF]MOD_SSL.CONF file, within the <VirtualHost> section that defines your secure Web server and with the other SSL directives:
SSLCertificateFile /apache$root/conf/ssl_crt/server.crt

SSLCertificateKeyFile /apache$root/conf/ssl_key/server.key

Restart the server.

Verify that all CSWS processes have stopped first.
$ @SYS$STARTUP:APACHE$SHUTDOWN.COM

$ @SHOW SYSTEM/PROC=APACHE*

$ @SYS$STARTUP:APACHE$STARTUP.COM

You are now using your Global Server ID.

Client requirements

Global Server IDs will work with the following browsers:

Netscape Navigator 4.0 or later

Microsoft Internet Explorer 4.0 or later

Microsoft Internet Explorer 3.02 or later on Windows NT

If your users are using Netscape Navigator 3.0, they will be able to connect to your site at the 40-bit encryption. Navigators prior to 3.0 or Internet Explorers prior to 3.02 will not work with GSIDs.

How to enforce secure pages selectively

It's important to realize that installing a trusted CA certificate does not enforce blanket security for your server unless you require it. You may want to specify which of your server's directories or files require a secure connection. Without doing so, clients are able to view the same pages using URLs beginning with http:// as well as https://.

The simplest way to do this is by using the SSLRequireSSL directive in the HTTPD.CONF file using the MOD_SSL.CONF include file. If you apply it to the HTDOCS (or equivalent) directory, it prevents access to any pages in that directory or subdirectories without a secure connection (without using https://).

You can also include the SSLRequireSSL directive in .HTACCESS files for individual directories. Using MOD_SSL.CONF is the more secure method, but this requires stopping and restarting the server. Using an .HTACCESS file offers greater flexibility but also has the potential to compromise performance and security.

In order to enforce authentication of all clients, use the SSLVerifyClient directive. The require option makes the presentation of a client ID mandatory.

A much more complex directive, SSLRequire, enables you to implement selective security using client verification on a per directory basis. You construct SSLRequire directives using Boolean statements that parse the credentials of client certificates (using their corresponding environment variables). The official mod_ssl documentation explains how to construct such directives.

mod_ssl How-To

See also: How to use the FakeBasicAuth option

How to create and distribute client certificates

Issuing client certificates means you are performing the role of a Certificate Authority with the purpose of requiring clients to use a certificate that you issue. The following steps are involved:

Using the Certificate Tool, create a certificate request (Option 3) and sign the certificate with your CA certificate (Option 6).

Option 6 assumes you have already generated a CA certificate file (Option 5) for your server (default file name is SERVER_CA.CRT).

Client certificates are issued to individual persons. Therefore the common name is the individual's proper name (not the name of a network node).

Important: When signing the client certificate you must use the same pass phrase you used to create your certificate authority.

Convert the signed client certificate from PEM format to PKCS12 format by using the following OpenSSL commands :

$ openssl pkcs12 -export -in <CLIENT_NAME>.CRT -

_$ inkey OPENSSL_KEY:<CLIENT_NAME>.KEY -

_$ out <CLIENT_NAME>.P12 -name "<Issuer Name>" -

_$ rand RANDFILE
Notes:

The -rand parameter is required. If not specified, the resulting .P12 file will not be usable by Internet Explorer or Netscape Navigator. During import, the browser will pop up an error message with the text "password entered is incorrect" or similar error.

The -out parameter should be a full file specification if you have not SET DEFAULT to the same directory as the .CRT file.

For example:

$ openssl pkcs12 -export -in JSAMPLE.CRT -
_$ inkey OPENSSL_KEY:JSample.KEY -

_$ out JSample.P12 -name "XYZCorp" -

_$ rand RANDFILE

Enter Export Password:

Verifying password - Enter Export Password:

The export password that you specify is required by the recipient of the certificate when installing it.

Convert to .DER for Internet Explorer

In the case of IE, you need to convert the .CRT file to .DER format by using the following command:
$ openssl x509 -in SERVER_CA.CRT -out SERVER_CA.DER -outform der

Distribute the certificate from the server to the client's browser.

A client can receive a certificate by email, FTP, or directly using the browser. In the case of Internet Explorer (IE), having clients point directly to the files is the simplest way. This method may also be used with Netscape Navigator, but not with the advantage of automating the process.

If you use the browser method, copy the client certificate and the server certificate to your HTDOCS (or another accessible) directory. Clients can then point their browsers at the certificate files and save them. For example, the URLs could be:

http://test.res.xyz.corp/martian_client.p12
and
http://test.res.xyz.corp/server_ca.der

Important: In order to serve PKCS12 client certificates correctly to a Netscape users, you need to define this file type in HTTPD.CONF using the MOD_SSL.CONF include file.

In the case of IE, opening the save file will start the Certificate Manager Import Wizard automatically.

In the case of Netscape Navigator, users should load them using the Security Info window.

From the Communicator menu, choose Tools, and then choose Security Info.

From the Security Info window, click Certificates: Yours and then click Import a Certificate.

Important: Clients must load both the client certificate and the server certificates. The password you use when converting the certificates to PKCS12 format is required by clients to install the certificates.

On the server, edit your MOD_SSL.CONF file to uncomment SSLVerifyClient, giving it the value of Require. Also uncomment SSLVerifyDepth, leaving the value of 10 under most circumstances.

Restart the server after verifying that all CSWS processes have stopped.

$ @SYS$STARTUP:APACHE$SHUTDOWN.COM

$ @SHOW SYSTEM/PROC=APACHE*

$ @SYS$STARTUP:APACHE$STARTUP.COM

How to add PKCS12 file type to MOD_SSL.CONF

Unless you define the PKCS12 file type on your server, Netscape browsers will not be able to save certificate files with a .P12 extension. To specify the file type add the following to the MOD_SSL.CONF file under MIME-types, either inside or outside the <IfDefine SSL> section, and restart the server:

AddType application/octet-stream .p12

This will cause Netscape browsers to display the Save As dialog box for this file type.

How to implement the FakeBasicAuth option

This is an option of the SSLOptions directive . Using this option causes HP Secure Web Server to use standard Apache authentication based on the client certificate's distinguished name.

Create a password file containing the following line for each client certificate:

<Distinguished Name fields of a certificate>:xxj31ZMTZzkVA

where:

<Distinguished Name fields of a certificate> is required for every client certificate. You can obtain these by using the following OpenSSL command line:

$ openssl x509 -noout -subject -in "client certificate"

"xxj31ZMTZzkVA" is the literal string you should use.

This is a predefined DES-encrypted string (actually, the word "password") for any client certificate used with FakeBasicAuth.

Define a user authentication scheme in HTTPD.CONF (using the MOD_SSL.CONF include file) or access files (.HTACCESS).

For example, the definition could be as follows in MOD_SSL.CONF:

<Directory /apache$common/htdocs>

SSLRequireSSL

SSLVerifyClient require

SSLOptions +FakeBasicAuth +StrictRequire

AuthName "FakeBasicAuth Client Authentication"

AuthType Basic

AuthUserFile /apache$common/conf/ssl/fba_passwd.txt

require valid-user

</Directory>

In an access file, omit the <Directory> section command (first and last line).

Restart the server if you added the definition to MOD_SSL.CONF.

FAQs

Why do I already have a server certificate on my system?

A server certificate is required to start HP Secure Web Server if you enabled SSL. A 30-day certificate is self-signed for you when you run the CSWS configuration tool:

$ @SYS$MANAGER:APACHE$CONFIG.COM

You can examine the file's contents by choosing Option 1 in the OpenSSL Certificate Tool and entering the default specification:

APACHE$ROOT:[CONF.SSL_CRT]SERVER.CRT

What happens when the self-signed certificate expires?

Your SSL-aware server will not start without a valid certificate. In most cases, you will want to replace it with a commercial CA certificate, according to the preceding instructions for testing and installing certificates. However, a certificate does not have to be signed by a public CA. You can self-sign a new certificate by rerunning the CSWS configuration tool or by using the OpenSSL Certificate Tool to set a longer expiration period as required.

Note: Self-signing means that you have used your private key to sign the certificate, which in turn contains your public key. Clients now have the option of choosing to install your self-signed certificate as a trusted root CA certificate. This may be an appropriate setup in a intranet.

Can I install more than one server certificate?

Yes. Multiple server certificates for virtual hosts need to be defined using individual SSLCertificateFile and SSLCertificateKeyFile directives.

How to use command-line OpenSSL

SSL-enabled HP Secure Web Server includes the complete OpenSSL command-line interface in its native UNIX format. Whether you will need to use this depends on the type of administrative tasks you plan to do. For example, if you are implementing client authentication, one requisite activity is to generate a Client Revocation List if you are issuing client certificates.

Start the OpenSSL command-line interface with this command:

$ @APACHE$COMMON:[OPENSSL.COM]OPENSSL_INIT_ENV.COM

Then enter the following, to choose a directive and proceed:

$ OPENSSL <commandname>

If you type an unknown command name, a complete list of commands (standard, message digest, and cipher) is displayed.

$ OPENSSL <unknown_commandname>

How to create and view a client revocation list

If you want to implement a client revocation list using the mod_SSL directives, SSLCARevocationPath and SSLCARevocationFile, you will need to set up your list using OpenSSL commands in the following way:

Revoke a certificate

When you revoke a certificate, you specify a client certificate you have issued. Doing so denies authorized access. The syntax of this command is as follows:

$ openssl ca -verbose -config OPENSSL_CA.CONF -
_$ revoke <FILESPEC>.CRT

Example:

$ openssl ca -verbose -config OPENSSL_CA.CONF -
_$ revoke APACHE$COMMON:[OPENSSL.CRT]JAY_SAMPLE.CRT
Using configuration from openssl_ca.conf
Enter PEM pass phrase:

[List of Certificates]

Revoking Certificate 06.
Data Base Updated
$

The files specified are the CA configuration file (OPENSSL_CA.CONF), and the CRT fileAPACHE$COMMON:[OPENSSL.CRT]JAY_SAMPLE.CRT.

Create the client revocation list

When you create a CRL file, you are bundling all the revoked client certificate requests on your system. The syntax of this command is as follows:

$ openssl ca -gencrl -config OPENSSL_CA.CONF -out -
_$ <FILESPEC>.CRL -crldays [365]

Notes:

OpenSSL arguments (shown lowercase) may precede or follow OpenVMS file specifications (shown uppercase).

If you do not have default_crl_days defined in your OPENSSL_CA.CONF file, you must supply this on the command line also (as in the following example).

If you get an error message "Unable to load 'random state'," you can create a RANDFILE environment variable, as follows:

$ SHOW SYSTEM /FULL /OUT=SYS$LOGIN:RANDFILE.;
$ DEFINE /PROCESS RANDFILE SYS$LOGIN:RANDFILE.; Example: $ openssl ca -gencrl -config OPENSSL_CA.CONF -out - _$ APACHE$COMMON:[CONF.SSL_CRL]CA-BUNDLE.CRL -crldays 365 Using configuration from openssl_ca.conf Enter PEM pass phrase: $ The files specified are the CA configuration file (OPENSSL_CA.CONF), and the CRL file, APACHE$COMMON:[CONF.SSL_CRL]CA-BUNDLE.CRL. View the client revocation list The syntax of this command is as follows: $ openssl crl -in <FILESPEC>.CRL -text -noout Example: This command would open the CRL file created by the previous example. $ openssl crl -in APACHE$ROOT:[CONF.SSL_CRL]CA-BUNDLE.CRL - _$ text -noout Certificate Revocation List (CRL): Version 1 (0x0) Signature Algorithm: md5WithRSAEncryption Issuer: /C=US/O=XYZ Corp./OU=Research Dept./CN=XYZ Authority Last Update: Aug 14 16:27:42 2004 GMT Next Update: Aug 14 16:27:42 2005 GMT No Revoked Certificates. Signature Algorithm: md5WithRSAEncryption 83:47:e1:ce:f9:d9:41:ef:29:e7:a8:90:66:ee:1b:ad:50:37: bf:d3:16:ec:14:52:e5:1c:4f:dc:95:46:5b:ba:28:73:87:8f: 3f:49:80:11:08:8b:ab:64:56:77:bf:9f:75:3a:d7:be:55:a9: 87:2f:58:c2:59:80:31:52:a4:7d:28:00:24:a6:cc:0d:23:a2: 00:5c:f5:04:f5:91:80:59:ab:52:dc:72:83:ac:40:40:1b:08: fa:bd:d0:f9:c4:45:47:7a:c0:52:0b:3a:22:e4:5e:2a:8d:5d: fa:74:f1:1b:ee:ec:ce:88:c5:c6:50:4a:e2:74:9b:96:9f:cb: f6:a8 OpenSSL Reference Documents FAQs After entering OPENSSL -?, why am I prompted for a _File? You should use the following command to work with the OpenSSL command line: $ @APACHE$COMMON:[OPENSSL.COM]OPENSSL_INIT_ENV.COM After doing this, you can proceed by entering $ OPENSSL once or prior to each command. Where are the OPENSSL configuration files? OpenSSL configuration files can exist in the system-specific or common CONF directory. When using common configuration files across a cluster: APACHE$COMMON:[CONF]OPENSSL.CONF and OPENSSL_CA.CONF When using system-specific configuration files: APACHE$SPECIFIC:[CONF]OPENSSL.CONF and OPENSSL_CA.CONF How do I view certificates and certificate requests? If you don't want to use the Certificate Tool for this purpose, use the following commands from the OpenSSL command line: To view a certificate request: $ OPENSSL REQ -IN <FILE_NAME>.CSR -NOOUT -TEXT For example: $ OPENSSL REQ -IN [.OPENSSL.CSR]MR.CSR -NOOUT -TEXT To view a certificate: $ OPENSSL X509 -IN <INPUT_FILE>.CRT -NOOUT -TEXT For example: $ OPENSSL X509 -IN [.OPENSSL.CRT]MR.CRT -NOOUT -TEXT Why and how do I convert from PEM to DER and PFX formats? These formats are methods of hashing certificates for distribution to clients. File Extension Also Known As Purpose .P12 PFX/PKCS12 Format used by Internet Explorer and Netscape Navigator to import client certificates. .DER Format used by Internet Explorer to import CA certificates. .CRT PEM Format used by Netscape Navigator to import CA certificates. From the OpenSSL command line, use the following commands: To convert to DER: $ openssl X509 -in <FILE_NAME>.PEM -inform PEM - _$ outform DER -out <FILE_NAME>.DER To convert to PFX: $ openssl PKCS12 -export -in <FILE_NAME>.CRT - _$ INKEY OPENSSL_KEY:<FILE_NAME>.KEY _$ OUT <FILE_NAME>.P12 -NAME "Issuer Name"