Key-Stores and Trust-Stores

Once a certificate authority (CA) is established, it can be used to issue private keys and their public certificates for FWD servers and clients. See the chapter entitled Certificate Authority for details on how to create an organization-specific CA.

Private/public key pairs for server, process and user accounts enable SSL session security. The public key for any account is then signed by a CA and thus transformed into a certificate. That certificate can be used as an account credential to allow authentication between FWD servers and clients or between two FWD servers.

Private keys are only made available to the specific code (client or server, including custom Java application code) which represents the user, process or server account. The keys are kept in a Java KeyStore object which reads an optionally password encrypted file (the key-store file) that persistently stores the keys. The Java code that uses the keys must have access to the key-store and to the password to decrypt the contents. All other entities must not have any access to the key-store or the password.

Public keys (actually their signed versions as X.509 certificates) are used to validate that an incoming SSL session comes from an entity that “owns” the private key that is known to be associated with a given account. The certificates are also used to enable the SSL session encryption keys to be negotiated.

Any client code (custom or the standard FWD client) that connects to a FWD server will use a trust-store to establish the authenticity of any FWD server certificate. A trust-store is a list of certificates that should be trusted. The FWD server also has a trust-store, but it is dynamically created in-memory every time the server starts, based on certificates that are read from the server's configuration (the directory file).

This chapter describes how to create the public/private key pairs, certificates, key-stores and trust-stores that are needed to enabled non-interactive authentication and SSL session security, using the OpenSSL tools. At the end of the chapter is a description of how to load certificates into the server's directory so that accounts can be associated with certificates. For consistency, all examples will assume the same paths and file names that were used in the Certificate Authority chapter.

[CA] To use the built-in FWD tool which automatically generates the root CA and the peer certificates, see the FWD Cryptography Tool chapter of this book. [/CA]

Creating Public/Private Key Pairs and Certificates

This task includes creating the a private key and public certificate for a user, process or server.

Step 1 - Generate a New Public/Private Key Pair

Run these commands:

cd /var/ssl
sudo openssl req -config /etc/openssl.cnf -new -keyout newreq.pem -out newreq.pem

The resulting dialog should look like this:

Generating a 1024 bit RSA private key
writing new private key to 'newreq.pem'
Enter PEM pass phrase: mypasswd
Verifying - Enter PEM pass phrase: mypasswd
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
Country Name [US]:

State [Georgia]:

Locality (city etc) [Atlanta]:

Golden Code Development Corporation [Acme Inc]:

Organizational Unit [IT Operations]:

Subject Name []:FWD Server

email []:

Please enter the following 'extra' attributes

to be sent with your certificate request

A challenge password []:

An optional company name []:

In this case the subject name was set to “FWD Server” and the password was set to mypasswd.

Step 2 - Sign the Certificate

Sign the newly created certificate using this command and the root CA password (as it was set during the root CA creation):

sudo openssl ca -config /etc/openssl.cnf -policy policy_anything -out newcert.pem -infiles newreq.pem

The resulting dialog will appear something like this:

Using configuration from /etc/openssl.cnf
17768:error:0E06D06C:configuration file routines:NCONF_get_string:no value:conf_lib.c:329:group=CA_default name=unique_subject
Enter pass phrase for /var/ssl/acme-root-ca-key.pem:
Check that the request matches the signature
Signature ok
Certificate Details:
        Serial Number: 1 (0x1)
            Not Before: Apr 27 16:50:26 2006 GMT
            Not After : Apr 22 16:50:26 2026 GMT
            countryName               = US
            stateOrProvinceName       = Georgia
            localityName              = Atlanta
            organizationName          = Acme Inc
            organizationalUnitName    = Information Technology
            commonName                = FWD Server
        X509v3 extensions:
            X509v3 Basic Constraints:
            Netscape Comment:
                OpenSSL Generated Certificate
            X509v3 Subject Key Identifier:
            X509v3 Authority Key Identifier:
                DirName:/C=US/ST=Georgia/L=Atlanta/O=Acme Inc/OU=Information Technology/CN=Certificate Authority
Certificate is to be certified until Apr 22 16:50:26 2026 GMT (7300 days)
Sign the certificate? [y/n]:y
1 out of 1 certificate requests certified, commit? [y/n]y
Write out database with 1 new entries
Data Base Updated

Step 3 - Save the Private Key

Rename and save the private key file permanently:

sudo mv newreq.pem private/p2j-server-key.pem

The name of the private key file can be chosen to match the role or name of account. The key file can be stored anywhere secure.

Step 4 - Verify the Certificate

Verify the information in the certificate:

sudo openssl x509 -in newcert.pem -noout -text

Step 5 - Save the Certificate

Save the certificate permanently:

sudo openssl x509 -in newcert.pem -out certs/p2j-server-cert.pem
sudo rm newcert.pem

The name of the certificate file can be chosen to match the role or name of account.

Creating a Key-Store

The key-store is a password protected storage file for a private key, which is encrypted and decrypted using the given password. This allows a slightly better level of security than without the encryption. However it is essential that both the key-store and the password be kept in a secure location (where no unauthorized users can access them in any way, including read-only access).

At runtime on the client, the key-store must be accessible to the any FWD or application code that connects to the FWD server. When the server starts up, it needs access to its own private key via its password protected key-store.

Step 1 - Convert the Private Key into Import Form

Prepare the FWD server's private key for import into a key store:

cd /var/ssl
sudo openssl pkcs8 -in private/p2j-server-key.pem -topk8 -outform DER -nocrypt -out p2j-server-key.der

Use the password (mypasswd in this example) given at creation.

Step 2 - Import the Private Key and Certificate into a Key-Store File

Import the private key and public certificate into a new key store under the alias standard:

sudo java standard p2j-server-key.der certs/p2j-server-cert.pem

The dialog should look like this:

Enter keystore password:whatever
Enter key entry password:123456
Keystore:, alias standard, RSA private key imported.

You can assign different passwords, aliases and filenames, as long as you use new ones consistently.

Step 3 - Cleanup

Remove the temporary key file:

rm p2j-server-key.der

Creating a Trust-Store

For FWD clients to validate an SSL connection with a FWD server, they must have a trust-store file that contains the certificates for the root CA and for the FWD servers to be validated. It is possible to connect to the FWD server via SSL without using SSL handshake validation. The trust-store is only needed if validation is used.

FWD servers obtain lists of CAs and peer certificates from their directory files at startup. All those certificates must be loaded into the directory to make them available. Since this is driven by directory data, there is no need for a FWD server to have a trust-store file. For details, see Importing a Peer Certificate into the Directory in this chapter and Importing a Root CA Certificate into the Directory in the Certificate Authority chapter.

The minimum trust-store contains a root CA certificate and at least one FWD server certificate which was signed by that root CA certificate. The program named keytool is used for this process. That is a tool that is included in most JDK (Java Development Kit) distributions.

Step 1 - Import the Root CA Certificate

Import the root CA certificate into a new trust store under the alias acme-root-ca:

cd /var/ssl
sudo keytool -import -keystore -alias acme-root-ca -file acme-root-ca-cert.pem

This will create the trust-store as a new file.

The dialog (somepw is a password given to this trust-store file):

Enter keystore password: somepw
Owner: CN=Certificate Authority, OU=Information Technology, O="Acme Inc", L=Atlanta, ST=Georgia, C=US
Issuer: CN=Certificate Authority, OU=Information Technology, O="Acme Inc", L=Atlanta, ST=Georgia, C=US
Serial number: 0
Valid from: Thu Apr 27 12:28:10 EDT 2006 until: Wed Apr 22 12:28:10 EDT 2026
Certificate fingerprints:
Trust this certificate? [no]:  yes
Certificate was added to keystore

Step 2 - Import a FWD Server Certificate

At least one FWD server certificate will need to be imported into the same trust-store file as the root CA certificate. This process can and should be repeated for all FWD servers to which the client will connect (and whose connections require validation).

Import the FWD server certificate into the same trust store under the alias p2j-server:

sudo keytool -import -keystore -alias p2j-server -file certs/p2j-server-cert.pem

The dialog (somepw is a password given to this trust-store file):

Enter keystore password: somepw
Certificate was added to keystore

Step 3 - Verify the Trust-Store

Verify the trust-store file:

sudo keytool -list -keystore

The dialog:

Enter keystore password: somepw
Keystore type: jks
Keystore provider: SUN
Your keystore contains 2 entries
p2j-server, 27.04.2006, trustedCertEntry,
Certificate fingerprint (MD5): XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX
acme-root-ca, 27.04.2006, trustedCertEntry,
Certificate fingerprint (MD5): XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX

Importing a Peer Certificate into the Directory

All certificates used to authenticate users, processes and servers must be known to each FWD server. Even a FWD server's own certificate must be known to it, in addition to the certificates of all other FWD servers in the network. These “peers” on the network require the definition of a peer certificate into the list of known certificates that is in the server's directory file. This allows these certificates to be used for authentication and privacy (SSL socket communications).

There are two ways to import (i.e. load) a certificate. With a running server, the administration client can be used to edit the directory of that running server. For details, please see the chapter in Part 3 of this book entitled Loading Known Certificates.

The other way to import the certificate is to use a command line utility while the server is not running. The following commands will do the work:

Change the “working directory” to the location from which the server is normally run. In this file system location, it is expected to find the directory file (the server's XML configuration file) and the server's bootstrap configuration file. For the purposes of this example, the working directory where the server's files exist will be /server/p2j/, the directory file will be directory.xml and the bootstrap configuration file will be server.xml.

cd /server/p2j

Run the utility, to load the each given certificate as a known “peer” certificate:

java -Xmx256m com.goldencode.p2j.util.LoadCert -config ./server.xml /security/certificates/peers/p2j-server /var/ssl/certs/p2j-server-cert.pem

The bootstrap configuration file has a reference to the directory.xml (which is how the FWD server knows which file to use as its directory when the server starts). This command opens that directory file (./directory.xml) and imports the p2j-server-cert.pem certificate into the path /security/certificates/peers/p2j-server. The p2j-server name can be anything unique in that parent element (/security/certificates/peers/). The server will recognize that this is a peer certificate based on the location in the directory and it will add it into a dynamically created in-memory trust-store at server startup. A trust-store contains a list of known peer certificates. The name specified will be the alias of the certificate in the trust-store.

© 2004-2017 Golden Code Development Corporation. ALL RIGHTS RESERVED.