Implementing a server certificate

Ultimately, you will probably want to arrange to receive a certificate from a commercial certifying authority. Certificates and certifying authorities are discussed in some detail in About keys and certificates.

The process of getting a valid certificate and private key combination usually involves these steps:

Generate a private key and an associated certificate request. The certificate request is basically a certificate without a digital signature. The private key should be stored in a secure location and (preferably) encrypted.
Send the certificate request to the certifying authority (CA). This could be done via e-mail, fax, or simply moving files or procedures around on a machine.
The certifying authority digitally signs the certificate. Presumably, the certifying authority verifies that the information in the certificate is correct and valid, but this is not strictly necessary.
The certifying authority sends the digitally signed certificate back to the holder of the private key.
The holder of the private key receives the signed certificate. This usually involves associating the signed certificate with the private key in some way. With Janus Network Security, the private key and the signed certificate must be placed into the same procedure.

When generating a certificate request for a CA, you use separate forms from the Janus Certificate Management Application to accomplish steps 1, 2, and 5. When generating a self-signed certificate, all five steps are performed by the same server, so they are combined into a single step from the perspective of the end user.

This page discusses how to use the Rocket-provided Certificate Management Application to get either a commercially-signed or a self-signed certificate, and how to set up the web port that uses the certificate at your site.

Using the Certificate Management Application

This section describes how to use the Janus certificate management application (CMA) to get a signed certificate. The application can generate a certificate that you send to a CA for signing, or it can generate a certificate that it simultaneously signs for you. You may want to use the latter, self-signed, certificate (Self-signed certificates) for testing purposes.

You access the CMA from your browser with a URL that will cause you to be logged in as a JANSSL subsystem user:

Access the default home page via the SSL port set up to use the Sirius internal certificate (as described in Connect to the SSL port from a browser):
On the Janus default home page, follow the "configure and manage Janus SSL support" link in the introduction.

This brings you to the "SSL Configuration and Maintenance" page, which is a detailed summary of Janus SSL support (it contains much of the same content as these Janus Network Security wiki pages. The upper left of this page contains a list of links to the activity pages of the certificate management application:

Create a certificate request	Invokes a form that generates either a certificate request for a CA or a self-signed certificate. If a request for a CA, the output is two procedures: one contains the certificate request, and one contains your private key. If for a self-signed certificate, the output includes the two procedures just mentioned as well as a third procedure which contains the certificate itself.
Receive a signed certificate	Invokes a form that receives a signed certificate when it is sent back to you from a certifying authority(CA). This form is not needed for a self-signed certificate.
Sign a certificate request	Invokes a form that appends your site's digital signature to the certificate; it is designed to help you act as an organizational certifying authority. Note: You do not use this form in the exercise in this page (port with CA-signed certificate). For more information, see Acting as an Organizational Certifying Authority.
Manage private key and certificate procs	Invokes a form that lets you examine (as well as rename or delete) the certificates and keys you receive and create. This page also lets you append an intermediate certificate, should that be necessary (see Add an intermediate certificate).

Each of the Janus CMA forms contains its own online Help.

To use the CMA to get a CA-signed certificate, you submit the "Create a Certificate Request" and the "Receive a Signed Certificate" forms (and you may use the "Manage Private Key and Certificate Procedures" form for maintenance). For a self-signed certificate, you submit only the "Create a Certificate Request" form (selecting the "Create self-signed certificate" checkbox).

The rest of this section describes the process you follow to get a CA-signed certificate, supplementing the details of form completion found in the online Help.

Generate a certificate request

On the top left of the SSL Configuration and Maintenance page, select the "Create a certificate request" link.
In the "Help" and "Tips" sections of the "Create a Certificate Request" page, generate the request.
Follow the comments that pertain to generating a certificate request for a CA. In addition, make use of the comments in Storing the private key and Encrypting the private key, below.

You are returned a "Generated Certificate Request" page that contains your encryption password and your certificate request. On the mainframe, a .PKEY file (private key) and a .CERT file (certificate request) are added to your JANSSL file.

Storing the private key

When you generate the certificate request, a private key will also be generated and stored in JANSSL or some other file you designate. JANSSL is recommended, because it is set up to be impossible for an end user to peruse, and it is set up so that the JANSSL subsystem can place private keys there. It is essential that the private key is stored in a file that is not accessible by an average user. In fact, the certificate management system is set up so that even the user that generated the private key cannot determine the actual value of the private key.

Encrypting the private key

Regardless of where the private key is stored, it should also be encrypted. It is recommended that you allow the "Create a Certificate Request" application to automatically generate an encryption password (really a key), since this key will be more difficult to guess than a mnemonic password that you might consider. In any case, write the password down, since without it the private key is useless. It is probably best not to maintain it in a file on any computer, unless you are sure that the file is secure.

Send the certificate request to a CA

Once the certificate request and the corresponding private key are generated, the certificate request must be sent to the appropriate certifying authority, such as VeriSign, Inc. You can e-mail or fax to the CA a copy of the certificate request returned by the request-generating application. It is also possible to make a copy of the certificate request in a Model 204 procedure and somehow send it to the appropriate CA.

Receive the signed certificate

Once a signed certificate is received from the certifying authority, that certificate needs to be associated with the private key used to generate the certificate request. This association is done with the "Receive a Signed Certificate" form.

The simplest way to move the signed certificate received (hopefully via e-mail) from the CA into the "Receive a Signed Certificate" application is to cut and paste the certificate from e-mail into the application's input form. Depending on the e-mail package you are using and on your browser, the cut-and-pasted certificate might seem to line up oddly in the input text area. This should not be a problem: the form does not have to "look neat" in order for the "Receive a Signed Certificate" application to accept the certificate.

When the certificate is successfully received, you get a confirmation page that contains the "signed certificate information" (from your certificate request) that identifies your server to prospective browser clients.

If your CA provided an intermediate certificate, see Add an intermediate certificate, below.

If you generated a self-signed certificate, the receiving step is done automatically for you.

You can use the "Manage Private Key and Certificate Procedures" page of the Janus CMA to check that your certificate is stored in the procedure file you designated.

Review your certificate

After storing your signed certificate, you use the "Manage Private Key and Certificate Procedures" page of the Janus CMA to review the certificate information.

Add an intermediate certificate

As of sometime in 2006, most of the prominent CAs require that servers install one or more intermediate certificates instead of the CAs' well-distributed "root" certificates. For example, if you are getting your server certificate from VeriSign, Inc. and your server software supports chaining, you are required to install an intermediate certificate (as of April, 2006).

A well-known CA like VeriSign, Inc. (whose root certificate is trusted across the internet) typically creates an intermediate CA which is used to sign your server certificate, and in some cases, provides an additional intermediate certificate. This CA "chain" is designed to provide a layer or two of protection for the root certificate.

The Janus certificate management application is equipped to receive intermediate certificates. If your CA returns an intermediate certificate in response to your certificate request, you should actually get two certificates (in the simpler case) back from the CA:

The primary SSL certificate for your web server (signed by intermediate CA)
A certificate for the intermediate CA (signed by the primary CA)

You use the "Receive a Signed Certificate" page (as described in Receive the signed certificate) to store the primary SSL certificate (item 1, above). As part of the "receive," the Janus CMA will search its store of intermediate CA certificates for a match to the signer of your primary certificate. If a match is found, your intermediate certificate (item 2, above) is automatically added at the same time. If no match is found, then you use the "Manage Private Key and Certificate Procedures" page to "manually" add the intermediate certificate to the primary certificate.

To manually append an intermediate certificate:

From the "Manage Private Key and Certificate Procedures" page, display the stored certificate by identifying the procedure file and any password, then clicking the Search file button.
Select the prefix of the .CERT file that contains the certificate.
Scroll to the "Add an Intermediate Certificate" form, where you can paste the certificate you get from the CA.

Preparing the SSL port

Once you have associated the signed certificate with the private key, you are ready to make available a port that uses this certificate and private key. You will also want to consider the benefit and risk of starting your SSL port via the User 0 stream.

Defining and starting a port

To create a Web Server port that uses the new certificate and private key:

Define the port with a command like the following:
JANUS DEFINE WEBSSL 443 WEBSERV 10 - SSL JANSSL NEWCERT.PKEY

where the private key and associated certificate are contained in procedure NEWCERT.PKEY of file JANSSL, and these are the value of the SSL parameter.
Start the port by issuing:
JANUS START WEBSSL mysecretpassword

where mysecretpassword is the password for the private key discussed earlier in Encrypting the private key. If you correctly enter the password, the port is started and you may use the signed certificate.

If you enter an incorrect password, you receive the following error message, and the port is not started:

MSIR.0378: INVALID RSA PRIVATE KEY

Placing start-up commands in User 0

Once you have set up the port definition and start, it will be tempting to place the START command followed by the password into the user 0 CCAIN stream. While there is nothing strictly wrong with this, it does make the user 0 CCAIN stream a key part of your network security, hence this stream should be protected accordingly. If a user could read this CCAIN stream, the user would be halfway to breaking SSL security — they would still have to get access to the private key to be able to decrypt SSL encrypted messages on the network. By being protective of the private key password and the private key itself, you should ensure the efficacy of SSL security.

Connecting to the port

To test your SSL connection, connect to the port from your browser as described in Connect to the SSL port from a browser. If you are testing with a self-signed certificate, your browser is likely to warn you that the certificate is not from a recognized CA. If this warning becomes bothersome, you can stop it by downloading your certificate to the browser to keep in its database of trusted certificate authorities. Issuing the following browser request sends your certificate to the browser:

https://www.yourdomain.com/JANWEB/DOWNCA?JANSSL/mycertprocprefix

where mycertprocprefix is the prefix of the .CERT file that contains your certificate (and JANSSL is presumably the procedure file). The browser's security interface prompts you for how to handle the incoming certificate.

You may still get an additional warning if www.yourdomain.com does not exactly match the host name you specified on the certificate request form.

Note: If you are connecting to the server port from a Janus CLSOCK client, the CLSOCK port does not by default load a database of trusted CA certificates like a browser does. The CLSOCK port must explicitly add a root certificate from the CA that signed the server certificate. The root certificate verifies the server certificate.

One way to get a root certificate for a CLSOCK port is to:

Connect to the secure port with a browser.

Select the options to examine the server certificate and determine its Issuer.

Export the appropriate certificate and upload it to your Online.

After you obtain a CA root certificate, you use a JANUS ADDCA command, which is also shown in an example for authentication of a client Example: SSL port requires client certificate).

CLSOCK ports may also take advantage of the SOUL ADDCA utility to add one or more of the standard CA root certificates that are pre-loaded to the SIRIUS procedure file. For more information about the ADDCA utility, see the JANUS ADDCA command.

Acting as an Organizational Certifying Authority

There is no further discussion in this topic of what you do if you want to be your own certifying authority, creating and managing certificates for your organization's subscribers. If you want to explore this possibility or need help with some of the issues discussed in this document, contact technical support.

Security in general and SSL in particular are complex, and a simple misunderstanding can result in a security hole. It is best to talk things through and be sure you are doing the right thing if there is any doubt whatsoever.