Importing the eHealth Exchange Chain of Trust

Owned by Tran Tang (Unlicensed)
Jul 03, 2019

We install ehealth exchange certificate for all public facing servers. Below is the instructions to install and verify. Now, before we start this process we need to have two things - Reference Code and Authorization code  

Backup - do this if you are replacing an existing certificate with a new certificate

Backup whole existing keystore and individual cert. 

cp gateway.jks gateway.jks-yyyyMMdd
keytool -export -alias gateway -file gateway.crt -keystore gateway.jks

Remove old certificate - do this if you are replacing an existing certificate with a new certificate

Below example is removing just gateway certs but if the chained gateway cert is installed then remove all individual certs from both gateway and cacerts

keytool -delete -alias gateway -keystore gateway.jks
keytool -delete -alias gateway -keystore cacerts.jks

Verify Old certification - do this if you are replacing an existing certificate with a new certificate

keytool -list -v -keystore gateway.jks -alias gateway
keytool -list -v -keystore cacerts.jks -alias gateway


Note: once we run remove old certification steps, those steps above should give us error to indicate the alias doesn't exist


Generate new Key - do this if you NEED a new certificate

PROD:   keytool -genkey -alias gateway -keyalg RSA -keystore gateway.jks -dname "CN=<reference number>, OU=NHIN, O=HHS-ONC, C=US" -validity 365 -keysize 2048
VAL:    keytool -genkey -alias gateway -keyalg RSA -keystore gateway.jks -dname "CN=<reference number>, OU=NHIN-test, O=nhin, C=US" -validity 365 -keysize 2048

Generate CSR 


keytool -certreq -alias gateway -keystore gateway.jks -file gateway-yyyyMMdd.csr

Get Certificate (CSR reply from link in the Ehex Instructions)

https://enrolldnfi.managed.entrust.com/cda-cgi/clientcgi.exe?action=start 

With this link you need to provide - Reference number, Authorization code and provide CSR to generate CSR Reply and copy that to one the file. For example "gateway.pem"

Import CSR to gateway certificate

NOTE: If you created a new key store, make sure to import the intermediate and root certificates before proceeding

keytool -import -trustcacerts -alias gateway -file gateway.pem -keystore gateway.jks

This is NOT importing a new SSL certificate to replace what is currently in the key store. This is importing a CSR reply to allow for existing root certificate to be chained to the intermediate and root certificates.

Now, if you see any error after running above command for "chain certificate not found or something can't relate to chained certificate" then you need to generate to get the chained certificate as mentioned below.

  • Open up gateway.pem or the file you copied that "CSR reply" in Keystore Explorer. 
  • After opening that file you should be able to see "Authority Information Access" => extension value and you should be able to get a link to download a certificate For Ex: "URI: http://nfitestweb.managed.entrust.com/AIA/CertsIssuedToNFIMediumSSPCA.p7c"
  • Download the certificate and then open it in the Keystore Explorer and check if you see the full chained certificate until you reach the AKI of "gateway.pem" => Extensions
  • If you don't see the full chain then just go ahead and open and check each and every chained cert's if you find "Authority Information Access"  having a link to download further chain. Here is snapshot of how it looks like:

Also, in order to get chained cert you can also run openssl pkcs7 -inform DER -text -print_certs -in /tmp/cert/[nameofthecert].p7c  ( you can get the certificate and examine in keystore explorer and see if you can get the full chain)

Once full chain is decided and cert files are copied made ready 

Import Certs to gateway

Always start importing from root to Gateway.pem 

keytool -import -trustcacerts -alias gateway-root -file /tmp/cert/cert3.pem -keystore gateway.jks
keytool -import -trustcacerts -alias gateway-intermediate -file /tmp/cert/cert3.pem -keystore gateway.jks
keytool -import -trustcacerts -alias gateway -file /tmp/cert/gateway.pem -keystore gateway.jks


Note: for root cert import it should ask for trusting the certificate but for the rest of the chain cert it should not ask for trusting the cert. If asked the wrong chain is updated.

Export Certs from gateway to cacerts


keytool -export -alias gateway-root -keystore gateway.jks -rfc -file gateway-root-20150916.pem
keytool -export -alias gateway-intermediate -keystore gateway.jks -rfc -file gateway-intermediate-20150916.pem
keytool -export -alias gateway -keystore gateway.jks -rfc -file gateway-20150916.pem


Import certs to cacerts 

Import certs in the same order you do for the gateway.jks. Start from root to the end.

keytool -import -trustcacerts -file gateway-root-20150916.pem -alias gateway-root -keystore cacerts.jks
keytool -import -trustcacerts -file gateway-intermediate-20150916.pem -alias gateway-intermediate -keystore cacerts.jks
keytool -import -trustcacerts -file gateway-20150916.pem -alias gateway -keystore cacerts.jks