Sun Java System Messaging Server 6.3 Administration Guide

23.5.1 Obtaining Certificates

Whether you use SSL for encryption or for authentication, you need to obtain a server certificate for your Messaging Server. The certificate identifies your server to clients and to other servers. Another way of obtaining certificates is using msgcert command (described later in this section). Note that the old certutil command still works, but may be more complex to use and is not internationalized. For more information on certutil, see 23.5 Configuring Encryption and Certificate-Based Authentication and

This section consists of the following subsections: To Manage Internal and External Modules

A server certificate establishes the ownership and validity of a key pair, the numbers used to encrypt and decrypt data. Your server’s certificate and key pair represent your server’s identity. They are stored in a certificate database that can be either internal to the server or on an external, removable hardware card (smartcard).

Sun Java System servers access a key and certificate database using a module conforming to the Public-Key Cryptography System (PKCS) #11 API. The PKCS #11 module for a given hardware device is usually obtained from its supplier and must be installed into the Messaging Server before the Messaging Server can use that device. The pre-installed “Netscape Internal PKCS # 11 Module” supports a single internal software token that uses the certificate database that is internal to the server.

Setting up the server for a certificate involves creating a database for the certificate and its keys and installing a PKCS #11 module. If you do not use an external hardware token, you create an internal database on your server, and you use the internal, default module that is part of Messaging Server. If you do use an external token, you connect a hardware smartcard reader and install its PKCS #11 module.

Note –

In the following sections we will refer to the console or Directory Server Console. This refers to Directory Server prior to version 6. For version 6 or later, the graphical user interface is called the Directory Server Control Center. Refer to the latest Directory Server documentation (Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide) for more information.

You can manage PKCS #11 modules, whether internal or external, through Console. To install a PKCS #11 module:

  1. Connect a hardware card reader to the Messaging Server host machine and install drivers.

  2. Use the modutil found in msg-svr-base/sbin to install the PKCS #11 module for the installed driver.

Installing Hardware Encryption Accelerators. If you use SSL for encryption, you may be able to improve server performance in encrypting and decrypting messages by installing a hardware encryption accelerator. An encryption accelerator typically consists of a hardware board, installed permanently in your server machine, plus a software driver. Messaging Server supports accelerator modules that follow the PKCS #11 API. (They are essentially hardware tokens that do not store their own keys; they use the internal database for that.) You install an accelerator by first installing the hardware and drivers as specified by the manufacturer, and then completing the installation—as with hardware certificate tokens—by installing the PKCS #11 module. Creating a Password File

On most Sun Java System servers for which SSL is enabled, the administrator is prompted at startup to supply the password required to decrypt the key pair. On Messaging Server, however, to alleviate the inconvenience of having to enter the password multiple times (it is needed by at least three server processes), and to facilitate unattended server restarts, the password is read from a password file. Passwords themselves are generated when their certificate database is created using the msgcert generate_certdb command.

The password file is named sslpassword.conf and is in the directory msg-svr-base/config/. Entries in the file are individual lines with the format


where moduleName is the name of the (internal or external) PKCS #11 module to be used, and password is the password that decrypts that module’s key pair. The password is stored as clear (unencrypted) text.

Messaging Server provides a default version of the password file, with the following single entry (for the internal module and default password):

Internal (Software) Token:netscape!

If you specify anything but the default password when you install an internal certificate, you need to edit the above line of the password file to reflect the password you specified. If you install an external module, you need to add a new line to the file, containing the module name and the password you specified for it.

Caution – Caution –

Because the administrator is not prompted for the module password at server startup, it is especially important that you ensure proper administrator access control to the server and proper physical security of the server host machine and its backups. Obtaining and Managing Certificates

Whether you use SSL for encryption or for authentication, you need to obtain a server certificate for your Messaging Server. The certificate identifies your server to clients and to other servers. The primary mechanism for obtaining and managing certificates is using the msgcert. However, if the Administration Server is installed, you can also use the Administration Console.

The rest of this section describes how to use msgcert. About msgcert

msgcert allows you to generate a certificate request, add a certificate to the certificate database, list certificates in the database and so on. For detailed information enter the following at the command line:

msg-svr-base/sbin/msgcert --help

This is shown below.

# ./msgcert --help

Manages the Messaging Servers Certificate Database
The accepted values for SUBCMD are:

add-cert              Adds a certificate to the certificate database
add-selfsign-cert     Creates and adds a selfsign certificate to the 
                      certificate database
export-cert           Exports a certificate and its keys from the database
generate-certDB       Creates Messaging Server Databases cert8.db key3.db 
                      secmod.db and sslPassword
import-cert           Adds a new certificate and its keys to the cert database
import-selfsign-cert  Adds a new selfsign certificate and its keys to the 
                      cert database
list-certs            Lists all certificates in the Certificate database
remove-cert           Removes a certificate from the database
renew-cert            Renews a certificate
renew-selfsign-cert   Renews a selfsign certificate
request-cert          Generates a certificate request
show-cert             Displays a certificate

The accepted value for GLOBAL_OPTS is:-?, --help
                Displays SUBCMD help

NOTE: You must stop all the TLS or SSL-enabled servers before making any 
changes to the Certificate Database.

Each of the sub-commands shown above performs a specific certificate management function. Details about these sub-commands and their functions can be obtained by entering the following:

msgcert SUBCMD –help

The remainder of this section will describe some common certificate management procedures. Managing Certificates

This section describes how to manage SSL certificates in Messaging Server To run SSL on Messaging Server, you must either use a self-signed certificate or a Public Key Infrastructure (PKI) solution which involves an external Certificate Authority (CA). For a PKI solution, you need a CA-signed server certificate which contains both a public and a private key. This certificate is specific to one Messaging Server. You also need a trusted CA certificate, which contains a public key. The trusted CA certificate ensures that all server certificates from your CA are trusted. This certificate is sometimes also called a CA root key or root certificate.

Configuring the Certificate Database Password

When managing certificates, you do not need to type a certificate password or specify the password file. You can simply pass the password as -W argument. Example:

echo "password22" > /tmp/certdbpwd
echo "password22" > /tmp/certdbpwd
# ./msgcert list-certs -W /tmp/certdbpwd

ProcedureTo Create a Messaging Server Certificate Database with a Default Self-signed Certificate

  1. To create a Messaging Server Certificate Database run the following command:

    msgcert generate-certDB

    This reads the certificate database password from CERT_PW_FILE (Default: prompt for password)

  2. You can view this certificate by using the command:

    msgcert show-cert Server-Cert

ProcedureTo Manage Self-Signed Certificates

If you are using certificates for test purposes, you can use self-signed certificates. In deployment configurations, you might prefer to use trusted Certificate Authority (CA) certificates. You can also use the Directory Server Admin Console to perform this task.

  1. When you create the certificate database, a default self-signed certificate is automatically provided. If you want to use a self-signed certificate with non-default settings, use the msgcert add-selfsign-cert command. Example:

    msgcert add-selfsign-cert --name siroe --org comms --org-unit Messaging 
    --city SantaClara --state ca --country us MySelfSigned-Cert

    A self-signed certificate is valid for three months.

  2. When your self-signed certificate expires, renew the certificate with the command:

    msgcert renew-selfsign-cert cert_alias To Install Certificates of Trusted CAs

Use ./msgcert add-cert to install the certificates of certificate authorities. A CA certificate validates the identity of the CA itself. The server uses these CA certificates in the process of authenticating clients and other servers.

If, for example, you set up your enterprise for certificate-based client authentication in addition to password-based authentication (see “Setting Up Certificate-Based Login” on page 157), you need to install the CA certificates of all CAs that are trusted to issue the certificates that your clients may present. These CAs may be internal to your organization or they may be external, representing commercial or governmental authorities or other enterprises. (For more details on the use of CA certificates for authentication, see Introduction to Public-Key Cryptography in in Managing Servers With iPlanet Console 5.0.)

When installed, Messaging Server initially contains CA certificates for several commercial CAs. If you need to add other commercial CAs or if your enterprise is developing its own CA for internal use (using Sun Java System Certificate Server), you need to obtain and install additional CA certificates.

Note –

The CA certificates automatically provided with Messaging Server are not initially marked as trusted for client certificates. You need to edit the trust settings if you want to trust client certificates issued by these CAs. For instructions, see 23.5.1 Obtaining Certificates.

The following procedure describes the process of requesting and installing CA-signed server and trusted CA certificates for use with Messaging Server.

ProcedureTo Request a CA-Signed Server Certificate

You can also use the Directory Server Admin Console to perform this task.

  1. Generate a CA--signed server certificate request.

    msgcert request-cert [-W CERT_PW_FILE] {-S DN|--name NAME [--org ORG] [--org-unit ORG-UNIT]
       [--city CITY] [--state STATE] [--country COUNTRY] } [-F FORMAT] [-o OUTPUT_FILE]

    Below is an example of a request for a CA-signed server certificate. It returns the certificate in binary format:

    ./msgcert request-cert --name aqua --org siroe --org-unit Messaging -o my_ca_signed_request_cert

    To return the certificate in ASCII format use the command as follows:

    ./msgcert request-cert --name aqua --org siroe --org-unit Messaging -F ascii -o my_casigned_request_cert

    Certificate Authorities usually require all of the attributes that are shown in this example in order to completely identify the server. For a description of each attribute, enter ./msgcert request-cert --help. When you request a certificate by using msgcert request-cert, the resulting certificate request is a binary certificate request unless you specify ASCII as output format. If you specify ASCII, the resulting certificate request is a PKCS #10 certificate request in PEM format. PEM is the Privacy Enhanced Mail format specified by RFCs 1421 through 1424 and used to represent a base64-encoded certificate request in US-ASCII characters. The content of the request look similar to the following example:

  2. Transmit the certificate request to your Certificate Authority, according to its procedures.

    The process for obtaining your Certificate Authority certificate differs depending on the certificate authority you use. Some commercial CAs provide a website that allows you to automatically download the certificate. Other CAs will email it to you upon request.

    After you have sent your request, you must wait for the CA to respond with your certificate. Response time for your request varies. For example, if your CA is internal to your company, the CA might only take a day or two to respond to your request. If your selected CA is external to your company, the CA could take several weeks to respond to your request.

  3. Save the certificate you receive back from the Certificate Authority.

    You should back up your certificates in a safe location. If you ever lose the certificates, you can reinstall them by using your backup file. You can save them in text files. The PKCS #11 certificate in PEM format looks similar to the following example.

    -----END CERTIFICATE-----

ProcedureTo Add the CA-Signed Server Certificate and Trusted CA Certificate

You can also use the Directory Server Admin Console to perform this task.

  1. Add the CA--signed server certificate using the following command:

    msgcert add-cert cert_alias cert_file

    Where cert_alias is a name which you give to identify your certificate, and cert_file is the text file containing the PKCS #11 certificate in PEM format.

    For example, to install a CA-signed server certificate, you might use a command similar to:

    msgcert add-cert /my_cert/server-cert-file

    The certificate is now installed, but is not yet trusted. To trust the CA-signed server certificate, you must install the Certificate Authority certificate.

  2. Add the trusted Certificate Authority certificate using the following command:

    msgcert add-cert -C cert_alias cert_file

    The -C option indicates that the certificate is a trusted Certificate Authority certificate.

    For example, to install a trusted certificate from a Certificate Authority, you might use the command:

    msgcert add-cert -C CA-cert /my_cert/ca-cert-file
  3. Optionally, use the following command to verify your installed certificates:

    To list all server certificates, showing information such as alias and validity dates:

    msgcert list-certs

    The Messaging server will have a default certificate called Server-Cert when generated with ./msgcert generate-CertDB . The text Same as issuer indicates that the default certificate is a self-signed server certificate. For example:

    # ./msgcert list-certs
    Enter the certificate database password:
    Alias          Valid from       Expires on       Self-   Issued by               Issued to
    ------------   ----------------  --------------- ------  ---------------------   --------------
    SelfSignedCrt 2006/07/28 12:58  2006/10/28 12:58   y     CN=SFO,L=SC,ST=ca,C=us  Same as issuer
    Server-Cert   2006/07/28 07:47  2006/10/28 07:47   y     CN=perseids             Same as issuer
    2 certificates found

    To list trusted CA certificates:

    msgcert list-certs -C

    To view the details of a certificate, including the certificate expiry date:

    msgcert show-cert cert_alias

    For example, to show a self-signed certificate:

    # ./msgcert show-cert MySelfSigned-Cert
    Enter the certificate database password:
            Version: 3 (0x2)
            Serial Number:
            Signature Algorithm: PKCS #1 MD5 With RSA Encryption
                Not Before: Fri Jul 28 19:58:31 2006
                Not After : Sat Oct 28 19:58:31 2006
            Subject Public Key Info:
                Public Key Algorithm: PKCS #1 RSA Encryption
                RSA Public Key:
                    Exponent: 65537 (0x10001)
        Signature Algorithm: PKCS #1 MD5 With RSA Encryption
        Fingerprint (MD5):
        Fingerprint (SHA1):
        Certificate Trust Flags:
            SSL Flags:
                Valid CA
                Trusted CA
                Trusted Client CA
            Email Flags:
            Object Signing Flags:

ProcedureRenewing an Expired CA-Signed Server Certificate

When your CA-signed server certificate (public and private key) expires, you can renew it by using the following procedure. You can also use the Directory Server Admin Console to perform this task.

  1. Obtain an updated CA-signed server certificate from your Certificate Authority.

  2. Once you receive the updated certificate, install the certificate.

    msgcert renew-cert cert_alias cert_file

ProcedureTo Export and Import a CA-Signed Server Certificate

In some cases you might want to export a certificate so that you can later import the certificate, for example, to another host. You can also use the Directory Server Admin Console to perform this task.

  1. Export the certificate.

    msgcert export-cert [-o OUTPUT_FILE] CERT_ALIAS

    For example:

    $ ./msgcert export-cert -o /tmp/first-certificate "First Certificate"
    $./msgcert export-cert -o /tmp/first-server-certificate Server-Cert
    Choose the PKCS#12 file password:
    Confirm the PKCS#12 file password:
    $ls /tmp
  2. Import the certificate.

    $ msgcert import-cert  CERT_FILE

    For example, to import the certificate

    $ msgcert import-cert /tmp/first-server-certificate
    Enter the PKCS#12 file password: