Skip to main content

Citi Server KeyStore Configuration

Emily Yeomans

Please note: A PDF version of this guide is available for download at the bottom of the article.

Overview:  This guide will cover how to import the application server’s SSL certificate into the Java Keystore and TrustStore file.  This is required for interfaces such as CITI Feed, LDAPS, SSO, IMAPS, etc…  

  1. Prerequisites:
  1. The SSL cert applied to the site in IIS
  2. Need portecle.zip (can be provided by iMedRIS)
  3. Need jetty.zip (can be provided by iMedRIS)

 

 

  1. Note: it is possible that this setup has already been completed for different interfaces.  All of step two is just to check whether or not some of the requirements have been set up already.  

Have they been configured in sa.properties?

  1. Open up the sa.properties file
  2. Check to see if the following lines are not commented out and have a value:
  1. system.keyStore_1
  2. system.keyStorePassword_1
  3. system.trustStore_1
  4. system.trustStorePassword_1
  1. If there is a file path listed for system.keyStore_1 and a password listed for system.keyStorePassword_1 then the JKS file has been created and will need to be verified (follow section 3).
  2. If there is a file path listed for system.trustStore_1 and a password listed for system.trustStorePassword_1 then the JKS file has been created and will need to be verified (follow section 3).

 

 

  1. Verify KeyStore and TrustStore

Verify (only if the keyStore and/or trustStore exist – Otherwise skip to section 4):

  1. Extract the portecle.zip file to the desktop
  2. Open up the command prompt and change directory to the extracted portecle folder.
  3. Run the following command:
  1. > java –jar portecle.jar

  1. The portecle GUI will now open.

C:\Users\Glaubig\Google Drive\iMedRIS\Work Documents\System Information\Documentation\Tutorials\My Documentation\iRIS CITI Feed Setup\Edited Photos\2.png

Verify Java KeyStore

  1. Click the open button (highlighted above) and select the file path for the system.KeyStore_1
  2. Enter the system.keyStorePassword_1 when prompted for the password
  3. Once the key-store has been opened there should be a key-pair. 
  1. Right click and select certificate details

C:\Users\Glaubig\Google Drive\iMedRIS\Work Documents\System Information\Documentation\Tutorials\My Documentation\iRIS CITI Feed Setup\Edited Photos\3.png

  1. Make sure that the certificate is the SSL certificate for the application server.

Verify TrustStore

  1. Click the open button and select the file path for the system.trustStore_1
  2. Enter the system.trustStorePassword_1 when prompted for the password
  3. Once the trust-store has been opened you will find many certificates that have been imported
  1. Sort by date and look at the newest cert
  2. Right click and select certificate details

C:\Users\Glaubig\Google Drive\iMedRIS\Work Documents\System Information\Documentation\Tutorials\My Documentation\iRIS CITI Feed Setup\Edited Photos\4.png

  1. Make sure that the certificate is the SSL certificate for the application server.

 

If both of the above have been verified to have the SSL certificate for the URL in it, then interfaces should work over HTTPS when configured and the rest of the guide can be skipped.

 

 

  1. TrustStore Setup Pre-req:

Download the .cer from the SSL protected site:

  1. Navigate to the iRIS site that the interface is being set up on
  2. Click the lock icon and select view certificate

C:\Users\Administrator\Dropbox\iMedRIS\Systems Info\Documentation\Tutorials\Chris' Documentation\iRIS CITI Feed Setup\Edited Photos\6.png

 

  1. Select the Details tab and then click the Copy to File button

C:\Users\Administrator\Google Drive\iMedRIS\Work Documents\System Information\Documentation\Tutorials\iRIS LDAPS cacert Setup\Edited Pictures\1.png

 

  1. In the window that opens, select the DER encoded binary X.509 (.CER) option.  

C:\Users\Administrator\Google Drive\iMedRIS\Work Documents\System Information\Documentation\Tutorials\iRIS LDAPS cacert Setup\Edited Pictures\2.png

 

  1. Choose where to save to file.  Click next and then click finish on the following page.

C:\Users\cglaubig\Desktop\iRIS KeyStore and TrustStore Setup\image3007.pngC:\Users\Administrator\Google Drive\iMedRIS\Work Documents\System Information\Documentation\Tutorials\iRIS LDAPS cacert Setup\Edited Pictures\4.png

 

  1. Import into TrustStore
  1. Using Portecle, open the TrustStore:
  1. Default Path: %IMEDRIS_HOME%\jdk*\jre\lib\security\cacerts
  2. Default Password: changeit
  1. Click the certificate import button

bitmap.png

  1. Select the DER converted file (from the previous section) and import.
  2. Once the file is imported click the Save button

bitmap2.png

 

 

  1. Add the TrustStore to the sa.properties file

 

First change the password:

  1. With the TrustStore already open, go to Tools 🡪 Set Keystore Password

4.png

  1. Enter the new password and then save the KeyStore.
  2. Change to the %IMEDRIS_HOME%\jdk*\jre\lib\security directory.

Add to sa.properties:

  1. Add the %IMEDRIS_HOME%\jdk*\jre\lib\security\cacerts path to the system.trustStore_1 property.  Make sure that there are two ‘\’ for every 1 ‘\’ in the path
  1. Ex: C:\iMedRIS\ jdk1.7.0_67\jre\lib\security\cacerts 🡪 C:\\iMedRIS\\ jdk1.7.0_67\\jre\\lib\\security\\cacerts
  1. Add the password used for the cacert trustStore password to the system.trustStorePassword_1 property.

 

 

  1. JKS pre-req – Get certificate in .PFX format

This can be skipped if you already have the application server’s cert in .PFX format.

  1. Open up IIS on the application server
  2. Select the server name in the right pane and then double-click on Server Certificates in the middle pane

C:\Users\Administrator\Dropbox\iMedRIS\Systems Info\Documentation\Tutorials\Chris' Documentation\iRIS CITI Feed Setup\Edited Photos\7.png

 

  1. Right-click the certificate used for the website and select Export…
  1. Note: Some certificates do not allow export – you must obtain the .PFX SSL certificate and a password for it from someone at your institution

C:\Users\Administrator\Dropbox\iMedRIS\Systems Info\Documentation\Tutorials\Chris' Documentation\iRIS CITI Feed Setup\Edited Photos\8.png

 

  1. Enter the filename and path for the .PFX file to be exported and assign it a password

C:\Users\Administrator\Dropbox\iMedRIS\Systems Info\Documentation\Tutorials\Chris' Documentation\iRIS CITI Feed Setup\Edited Photos\9.png

 

 

 

  1. Create the Java Key Store using Jetty
  1. Extract the Jetty.zip onto the desktop
  2. Open up command line and change directory to the extracted folder.
  3. Run the following command:
  1. > java -classpath lib\jetty-6.1.1.jar org.mortbay.jetty.security.PKCS12Import <cert_pfx_file_path> %IMEDRIS_HOME%\jdk*\jre\lib\security\keystore.jks
  1. Input keystore passphrase = <password when exporting the cert from IIS or converting key to .pfx format>
  2. Output keystore passphrase = <choose password>

C:\Users\cglaubig\Desktop\iRIS KeyStore and TrustStore Setup\5.png

  1. Add the %IMEDRIS_HOME% \jdk* \jre\lib \security\<keystore>.jks path to the system.keyStore_1 property.  Make sure that there are two ‘\’ for every one ‘\’ in the path
  1. Ex: C:\iMedRIS\ jdk1.7.0_67\jre\lib\security\keystore.jks 🡪 C:\\iMedRIS\\ jdk1.7.0_67\\jre\\lib\\security\keystore.jks
  1. Add the password used for the keyStore to the system.keyStorePassword_1 property.

 

  1. Restart iRIS

 

Related articles