Key-Stores and Trust-Stores¶
- 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.
To use the built-in FWD tool which automatically generates the root CA and the peer certificates, see the Cryptography Setup Helper chapter of this book.
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) Validity Not Before: Apr 27 16:50:26 2006 GMT Not After : Apr 22 16:50:26 2026 GMT Subject: countryName = US stateOrProvinceName = Georgia localityName = Atlanta organizationName = Acme Inc organizationalUnitName = Information Technology commonName = FWD Server X509v3 extensions: X509v3 Basic Constraints: CA:FALSE Netscape Comment: OpenSSL Generated Certificate X509v3 Subject Key Identifier: XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX X509v3 Authority Key Identifier: keyid:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX DirName:/C=US/ST=Georgia/L=Atlanta/O=Acme Inc/OU=Information Technology/CN=Certificate Authority serial:00 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 p2j-server-key.store under the alias standard:
sudo java com.goldencode.p2j.security.KeyImport p2j-server-key.store 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: p2j-server-key.store, 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 acme-client-trust.store under the alias acme-root-ca:
cd /var/ssl sudo keytool -import -keystore acme-client-trust.store -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: MD5: XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX SHA1: XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX 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 acme-client-trust.store -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 acme-client-trust.store
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.