PMDF System Manager's Guide

15.2.1 Certificate Setup

Note

See the Glossary for definitions of unfamiliar terms.

PMDF-TLS requires a TLS certificate in order to accept TLS connections. This certificate is presented to the client during the negotiation of a TLS connection and is used to determine the secret private key that will be used to encrypt the connection between the server and the client.

The first thing that must be done is to generate the keys to be used in the certificate and then generate a certificate request. The certificate request is then given to a Certificate Authority such as Thawte Consulting or Verisign, Inc., who will sign the certificate with the Certificate Authority's own certificate. This new certificate will then be used in conjunction with the private key that was initially generated.

15.2.1.1 Generating the Certificate Request

A utility is provided to generate a public key pair and a certificate request. Its output includes three files:

a file containing the private key, (for testing purposes you can call the file anything you like, but for live operation the file must be named server-priv.pem and stored in the PMDF table directory and it must be protected against world access---this is your private key!),
a certificate request file containing the public key,
and a self-signed certificate (which can be used while awaiting signing by a Certificate Authority of the certificate request) also containing the public key.

You must be privileged to use this utility. To use the utility, on OpenVMS, issue the command:

$ RUN PMDF_EXE:tls_certreq

Or on UNIX, issue the command:

# /pmdf/bin/tls_certreq

Or on NT, issue the command:

C:\> tls_certreq

This utility invokes an interactive script that will prompt you for answers to a number of questions, including:

How many bits of encryption you would like to use.²
The name of the file in which to store the private key part of the RSA key pair.
Your e-mail address (as the person responsible for the certificate request).
The domain name for the PMDF system, or a wildcarded domain name for your site.
The two character ISO country code³ for the country in which the PMDF system is located.
The state or province in which the PMDF system is located.
The city in which the PMDF system is located.
The official name of your organization.
Optional additional organization information.
The name of the file in which to store the generated certificate request.
The number of days for which you would like your temporary self-signed certificate to be valid.
The name of the file in which to store the self-signed certificate.

When prompted for information, if there is a default value available, it will be shown within square brackets. Some questions do not require answers and will be presented displaying (optional) if you can simply press [RETURN] to skip that question.

A sample execution on OpenVMS of PMDF_EXE:tls_certreq is shown in Example 15-1; execution is analogous on UNIX and NT, modulo only different file name syntax.

Example 15-1 Sample Execution of the tls_certreq Utility on OpenVMS

---------------------------------------- Generating RSA Private Key ---------------------------------------- How many bits of encryption would you like for your certificate? 512 is used for export-grade encryption, 1024 is typical for domestic certificates [1024]: [RETURN] Generating a 1024 bit RSA private key........................................... ................................................................................ ................................................................................ ................................................................................ ................................................................................ ................................................................................ ........ Enter a filename where the PRIVATE part of the RSA key pair will be saved. (Note that this file must be protected against public access as doing otherwise would compromise the security offered by PMDF-TLS. Ensure that the file has a protection like "(RWED,RWED,,)". [PMDF_TABLE:SERVER-PRIV.PEM]: [RETURN] ---------------------------------------- Generating Certificate Request ---------------------------------------- Please enter the Distinguished Name information for your certificate request... This e-mail address will be used as the contact for this certificate. You should enter your e-mail address where the Certificate Authority can contact you regarding this certificate request. E-Mail address of person submitting the request: Joe.Manager@Domain.Com The domain name entered here will be the "common name" used for the certificate. Clients will verify that the system to which they connected matches this domain name, so you'll want to ensure that you choose the appropriate name for the server. For example, if a system is really named frodo.domain.com, but people will be accessing it as mail.domain.com, the domain name chosen here should be mail.domain.com Some Certificate Authorities (such as Thawte) will permit a "wildcard" domain name here, i.e., *.domain.com. If you have several hostnames within a particular domain that you will be supporting, this can be a better choice, but you'll need to ensure that the Certificate Authority that you'll be using to sign your certificate will support this form for the certificate's common name. Unfortunately, not all clients will recognize wildcard characters in the domain name, and those clients will be presented with a warning that the certificate's domain name doesn't match the server's domain name. The current versions of both Microsoft's and Netscape's clients, however, do support wildcarded domain names. Domain name of TLS/SSL server for which request is being generated: *.domain.com Enter the appropriate two letter code here (US for United States, CA for Canada, etc.). Two character ISO country code for server's location: US If desired, enter your state/province name here. Most Certificate Authorities will require that this field be filled in. State or Province (not abbreviated) where server is located (optional) []: California Also if desired, enter the name of your city here. Again, most Certificate Authorities will require this to be in your certificate. City where server is located (optional) []: West Covina This is the full name of the company or organization that will be the official owner of the certificate. The Certificate Authority will probably require that this EXACTLY match the organization's name as officially registered in the organization's local authority. Official name of organization responsible for server: Domains R Us Some organizations can have extra distinguishing information that they want to have included in their certificate. Extra company name information (optional) []: [RETURN] If this certificate will be used solely within a particular department, you can want to include that in the distinguished name on the certificate. Name of the department within organization responsible for server (optional) []: [RETURN] This file will contain the certificate request that will be given to a Certificate Authority to sign and generate your certificate. Enter a filename where the certificate request will be saved [PMDF_TABLE:SERVER-CERTREQ.PEM]: [RETURN] Certificate request has been generated. Follow the instructions provided by the Certificate Authority to obtain your certificate. ---------------------------------------- Generating Self-Signed Certificate ---------------------------------------- Since it will typically take some period of time to obtain a signed certificate from a Certificate Authority, the Certificate Request tool also generates a self-signed certificate that can be used temporarily in place of one signed by a Certificate Authority. Since all certificates have built-in expiration dates, you should choose how long before this self-signed certificate will expire. If you will be proceeding with obtaining a certificate signed by a recognized Certificate Authority, then the default of 365 days will provide ample time. If you intend on using the self-signed certificate permanently, you can want to choose a longer validity period. How many days would you like the self-signed certificate to be valid for? [365]: [RETURN] Enter a filename where the self-signed certificate will be saved [PMDF_TABLE:SERVER-SELFSIGN.PEM]: [RETURN] Self-signed certificate has been generated. You can use this certificate in lieu of one signed by a well-known Certificate Authority if you want. Please see the PMDF TLS installation documentation for more information about certificate usage and installation.

The three files produced as output by the tls_certreq utility consist primarily of BASE64 encoded data, and are not especially intelligible upon casual inspection. (However, see the tls_certdump utility which can display the data in such files.) For convenience in managing such files, the files are labelled with an initial text line describing the contents.

The private key file, the file which must be protected against world access as it contains your secret private key, (default name server-priv.pem), begins with the line:

-----BEGIN RSA PRIVATE KEY-----

The certificate request file containing your public key, the file to be sent to a Certificate Authority for signing, (default name server-certreq.pem), begins with the line:

-----BEGIN CERTIFICATE REQUEST-----

The self-signed certificate file, the file you can use while awaiting signing of your certificate request by a Certificate Authority, (default name server-selfsign.pem, which must be renamed to server-pub.pem if you want to use it while awaiting your signed certificate), begins with the line:

-----BEGIN CERTIFICATE-----

15.2.1.2 Getting a Certificate Authority to Sign Your Certificate

Once you have your certificate request completed, you then need to have it signed by the Certificate Authority of your choice. Some sites can choose to have their requests signed by an in-house Authority, but many will choose to go to an independent Certificate Authority, such as Thawte Consulting (http://www.thawte.com/) or Verisign, Inc., (http://www.verisign.com/).

Both of these Authorities will provide complete information on what is needed to complete your certificate request. For PMDF usage, tell the signing Authority that you want a "web server" or "server" sort of certificate.

When you have finished the process of getting a signed certificate from a Certificate Authority, you'll have a new file that starts with

-----BEGIN CERTIFICATE-----

(Note that this file has a similar form to the self-signed certificate generated by the tls_certreq utility---not surprising as both are certificate files, used in the same way! But unlike the self-signed certificate file, the certificate file signed by a recognized Certificate Authority should inspire confidence in client users of TLS.) You should place this signed certificate file on your system as PMDF_TABLE:server-pub.pem (OpenVMS) or /pmdf/table/server-pub.pem (UNIX) or server-pub.pem in the PMDF table directory (usually C:\pmdf\table\) (NT).

Note

² Due to United States export restriction regulations, most sites outside the United States and Canada will be limited to at most 1024 bits. Sites inside the United States and Canada can select up to the current PMDF-TLS maximum of 2048 bits, although note that currently the greatest number of bits likely to be supported by any client is 1024 so for practical purposes currently such sites would want to select at most 1024 bits. Also note that most currently existing "export version" TLS-enabled clients are still limited to 512 bits. When negotiating with such clients, if the PMDF-TLS certificate key length is greater than 512 bits, PMDF-TLS will automatically negotiate the TLS connection with a temporary 512 bit key.

³ ISO country codes essentially correspond to the list of two character top level country domains listed in the `internet.rules` file in the PMDF table directory.

Contents

Index

PMDF System Manager's Guide

15.2.1 Certificate Setup

15.2.1.1 Generating the Certificate Request

15.2.1.2 Getting a Certificate Authority to Sign Your Certificate

3 ISO country codes essentially correspond to the list of two character top level country domains listed in the internet.rules file in the PMDF table directory.

³ ISO country codes essentially correspond to the list of two character top level country domains listed in the `internet.rules` file in the PMDF table directory.