PMDF System Manager's Guide
PMDF-REF-6.0

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 may 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 may 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, assuming that you have /usr/bin in your search path, issue the command:

# 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 thetls_certrequtility 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 may 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 may have extra distinguishing information that they 
    wish to have included in their certificate. 
 
Extra company name information (optional) []: RETURN
 
    If this certificate will be used solely within a particular department, 
    you may wish 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 may wish 
    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 may use this certificate 
in lieu of one signed by a well-known Certificate Authority if you wish. 
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 expecially 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 may 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 wish 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 may 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 wish 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 may 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.

Previous | Next | Contents