The installation process differs slightly depending on the format of the certificate you received from a Certificate Authority. It is also possible to download the certificate along with the certificate trusted chain (CA bundle/intermediate certificates) from ZTABOX email.
1) PEM
If the certificate has been received in PEM format, you will need to add the CA root, CA intermediate, and certificate issued for your domain name in your keystore manually, in this order - starting from CA root and finishing with the certificate issued for your domain name.
Command for importation of a CA Root certificate to the keystore:
Command for importation of a CA Intermediate certificate to the keystore:
Important! If you received several intermediate certificates from the Certificate Authority, please import them one by one using different aliases.
Finally, you need to import the certificate issued for your domain name.
The alias for your domain certificate should be the same as the one you used when creating the keystore with the private key. If you did not specify the alias during the keystore creation, the default value will be 'mykey'.
2) PKCS#7
If the certificate was received in PKCS7 format (usually it has *.cer or *.p7b extension), which includes the certificate issued for you domain with the CA certificates, you need import it in the keystore:
If the certificate is imported successfully, and the keystore is completed, you should see the message:
'Certificate reply was installed in keystore'
To check the certificates which are added in the keystore run the command below:
You should see details of the certificates imported into the keystore in the output:
0n screenshot the chain consists of 2 certificates: root and certificate signed by root, that was created for testing purposes. Nowadays usually chain has at least three certificates: root, intermediate and certificate signed by intermediate.
To review the certificates added to the keystore as a plain text run the following command:
Once the the keystore is completed, you will need to describe it in the configuration of your tomcat.
Usually tomcat's configuration file is named server.xml.
Open it as a plain text and create there a record like below:
< Connector port="443" protocol="HTTP/1.1"
SSLEnabled="true"
scheme="https" secure="true" clientAuth="false"
sslProtocol="TLS" keystoreFile="/your_path/yourkeystore.jks"
keystorePass="password_for_your_key_store" / >
Restart tomcat to apply the changes and make the certificate work.
3. PKCS #12
Certificates generated on different Java-based servers may be transferred between servers. This can be done using Personal Information Exchange storage (.pfx / .p12 certificate file) containing full certificate chain (end-entity certificate and CA bundle) and a private key. (Note: .pfx and .p12 are different extensions of the same certificate format called PKCS#12.)
There are two ways of creating PKCS #12 file:
- Using OpenSSL
- Using Keytool (converting JKS into .p12 and importing it between Java servers)
OpenSSL
A .pfx file containing a private key (.key) file, end-entity certificate (.crt), and CA bundle (.ca-bundle) file can be created using this command:
(privatekey.key, domain.crt and domain.ca-bundle should be replaced with real filenames and file paths.)
After executing the command and entering PKCS#12 storage passphrase (password), the file will be accessible in certificate.pfx file in the default directory where the OpenSSL command has been executed (current directory can be checked with command pwd).
Once .pfx is generated, you can import it into Tomcat (or any other Java-based servlet container with Keytool instance) by following these commands:
-destkeystore keystore.jks -deststoretype jks -deststorepass < keystore password >
(PFX password, keystore password and .jks filename should be replaced with the valid data.)
Once the steps above are completed, the PKCS #12 file has been successfully imported into the JKS file.
You may also use the PKCS #12 file as the keystore itself. In this case, however, the file should be specified in the connector to the necessary port (default values 443 and 8443) and the type of keystore must be specified as well (e.g., keystoreType="PKCS12").
Keytool (converting complete keystore with end-entity certificate and full chain into PKCS #12)
Before proceeding with these steps, the end-entity certificate must be correctly imported into keystore. This is essentially an inverted process of the one described above - meaning the source keystore type (srcstoretype) will be jks, and the destination type will be PKCS #12.
Note: Some Java versions running Tomcat (or other servlet container using keytool as private/public keys management shell) have different prefered file extensions with which PKCS #12 is generated. Older versions (JDK 1.6 and earlier) can generate .p12 files. The latest versions can generate .pfx files. In terms of file content, .p12 and .pfx files are essentially the same. However, .p12 can easily be renamed as .pfx in Shell or via Windows File Explorer.
The command is the following:
-destkeystore keystore.p12 -deststoretype pkcs12 -deststorepass < pkcs#12 password >
(keystore.jks, keystore and PKCS #12 passwords need to be substituted with the real data.)
After the shell response 'Import command completed', the PKCS #12 file can be found in the file keystore.p12.
To have .p12 file working on Tomcat without unpacking it into a new keystore, you can simply specify it in the connector for the necessary port with keystoreType="PKCS12" directive added.