4.1.3.2 OLIS

Preface

These instructions allow for connecting OSCAR 15 to OLIS

Document Version History

• v1.0 – initial OSCAR 15 version published to oscarmanual.org – Mar 17, 2016
• V1.1 –Updated version with SHA-2 details – Mar 7, 2017

Instructions sourced from OSCAR-EMR Jay Gallagher, Duncan Rozario, Annie Zhou, and Darius Opensource

 New OLIS Setup from Scratch

 Registration process

1. Client to complete the Client Information Form.
2. OSP/OSSP to complete the OSCAR – Computer Application Form (section 1C and Part 2) with the client information.
3. OSP’s to e-mail OSCAR-EMR providing the completed Client Information Form and the completed OSCAR – Computer Application Form.  The e-mail should indicate that a client wishes to sign up for OLIS and provide the following information:
1.  Organization / Group Name
2. The name of each Physician or Nurse, and their respective CPSO or CNO #’s.
3. OSCAR-EMR  will then forward your request to OntarioMD (copying you), indicating that the client is eligible for OLIS (i.e.:  TOU signed, upgrade complete, etc.).
4. OntarioMD will then work with e-Health to obtain the remaining required OLIS agreements directly from the client.
5. Deployment of OLIS connectivity / certificates will continue via e-Health and the OSP / OSSP.

Generate Keys

2. Generate Keys and certificate signing request (CSR)

You will be using keytool to create the key and CSR. It is found in JAVA_HOME.

For Java 8 if you installed according to instructions for OSCAR 15 it will be  /usr/lib/jvm/java-8-oracle/bin/keytool

a. Generate private/public key pair

$sudo keytool  -genkey -keyalg RSA -keysize 2048 -validity 3600 -alias olis -keystore PATH/olis.jks

Place the olis.jks  keystore in a convenient location such as the Oscar keystore path /etc/tomcat7/

genkey will ask for standard parameters which you will get from your Excel file but they are typically as follows:

CN: your reference number from eHealth

OU:Applications

O:eHealthUsers

L:Subscribers

ST:subscribers

C:ssh

You will be asked for a password which for simplicity can be the same keystore password that Oscar uses, found in Java’s configuration file : /etc/tomcat7/server.xml  or you can make up a new one. What you need to remember is that if you are using a .deb before 461 the password “changeit” is hardcoded into the Driver.java file and you  must use this password for OLIS to work. This will create a public-private key pair, alias olis. One alias references two keys.

b. Generate a CSR

$sudo keytool -certreq -alias olis -file.csr.txt -keystore PATH/olis.jks

Email eHealthOntario with the csr.txt file and they will return to you two files.

c. Certificate importation

Start with the root certificate which may be something like:

CA_Root_Cert_Production.txt

$sudo keytool -import -trustcacerts -alias root -file  CA_Root_Cert_Production.txt -keystore PATH/olis.jks

You will get the response ”Certificate was added to keystore”

Then you must import the signed public certificate. It will be a file like: Cert_12345678.txt  where the number is your reference number.

$sudo keytool -import -trustcacerts -alias olis -file CSR_12345678.txt  -keystore PATH/olis.jks 

You must use the alias olis otherwise the private-public key chain will not match and you will generate certificate errors which will prevent OLIS access.

When I tried to import the signed public certificate using the alias olis I encountered the error “alias already in use”

To get around that I imported the signed public certificate under another alias

$sudo keytool -import -trustcacerts -alias temp -file CSR_12345678.txt  -keystore PATH/olis.jks

Then exported it as a .cer

$sudo keytool -export  -alias temp -file temp.cer  -keystore PATH/olis.jks 

Then imported it back to the keystore with no problems.

$sudo keytool -import -trustcacerts -alias olis -file temp.cer  -keystore PATH/olis.jks

If your signed public certificate has been successfully imported you will see the specific message “Certificate reply was installed in keystore” If you don’t get that message then the private-public key pair has not been updated, and access will not work.

Oscar Properties configuration

The Oscar Properties file must now be updated.

$sudo nano  /usr/share/tomcat7/oscar.properties 

Enter the following configuration

#OLIS
olis_keystore=PATH/olis.jks
olis_ssl_keystore=PATH/olis.jks
olis_ssl_keystore_password=********
olis_truststore=PATH/jssecacerts
olis_truststore_password=changeit
olis_returned_cert=PATH/Cert_12345678.txt
olis_response_schema=webapps/oscar/WEB-INF/classes/org/oscarehr/olis/response.xsd
OLIS_PROCESSING_ID=P
olis_simulate=no
olis_request_url=https://olis.ssha.ca/ssha.olis.webservices.ER7/OLIS.asmx
OLIS_SENDING_APPLICATION=^2.16.840.1.113883.3.239.14:EMR1234^ISO

Notes:

-the  olis_ssl_keystore_password=********  is the one used to create the olis.jks keystore, it may be “changeit”

-the number 1234 in OLIS_SENDING_APPLICATION is a unique number from your Excel file from Oscar-EMR, it is in your OLIS Access String/MSH3 Value. You must enter the OLIS_SENDING_APPLICATION line exactly as above, same case, carets etc.

- olis_truststore see details below

-olis_returned_cert- this must link to your actual Cert_12345678.txt file

4. /etc/hosts configuration

$sudo nano /etc/hosts

and add the line:

76.75.164.17 olis.ssha.ca

5. olis_truststore

The truststore is a collection of public certificates. The easiest way to configure this is to simply copy the trusted public certificates from the OLIS server. This is how to do that and create your own jssecacerts file. I tried using the caecerts store in JAVA but that didn’t work. Thanks to Annie Zhou for this.

Login to Oscar production server, run command (alter as necessary to match your java path):

$export JAVA_HOME=/usr/lib/jvm/java-8-oracle 

Then download the source and compile ($javac InstallCert.java)

https://confluence.atlassian.com/download/attachments/180292346/InstallCert.java

And then run it

$java InstallCert  olis.ssha.ca:443

 this should create a jssecacert file in the directory where you run the command.

-change your olis_truststore property to the path to this file (make sure tomcat can read the file, watch your ownerships)

set the password truststore property to “changeit”

restart tomcat7

sudo service tomcat7 restart

6. Oscar configuration

Ensure that olis.sql has been run on your schema.  Then from Admin/Provider/Search/Edit

The physicians CPSO (CPSID)  number, and name EXACTLY as it is listed on the website, including middle names must be entered

http://www.cpso.on.ca/docsearch/

If the last name exceeds 10 characters you may need to enter it manually into the schema

Migration from OSCAR 12_1

if you have OLIS working in OSCAR 12_1 simply copy over your keystore files and Cert, otherwise start from scratch as above.

Use your existing Oscar12_1.properties for OLIS but add these additional properties to oscar.properties if not already present:

olis_response_schema=webapps/oscar/WEB-INF/classes/org/oscarehr/olis/response.xsd
OLIS_PROCESSING_ID=P
olis_simulate=no
olis_request_url=https://olis.ssha.ca/ssha.olis.webservices.ER7/OLIS.asmx

 In the Admin screen you need to set an additional property, OLIS identifier type to MD. You can also set it in the database: provider, field:official_olis_type to MDL

Migration from SHA-1 to SHA-2

In 2017 OLIS is switching from SHA-1 (now considered insecure) to SHA-2. Some notes on how to successfully
migrate

1. eHealth will send you an email with a new reference number. This will be different from your previous one so you need to generate a new key. Save your old ‘olis.jks’ elsewhere first

keytool -genkey -keyalg RSA -dname "CN=<number provided>,OU=Applications,OU=eHealthUsers, OU=Subscribers, DC=subscribers, DC=ssh” -sigalg  SHA256withRSA -alias olis -keystore /etc/tomcat7/olis.jks

keytool -certreq -alias olis -file /etc/tomcat7/csr.txt  -sigalg SHA256withRSA  -keystore /etc/tomcat7/olis.jks

keytool -import -trustcacerts -alias root -file EntProdRootCAcert.cer.txt -keystore /etc/tomcat7/olis.jks

keytool -import -trustcacerts -alias intermediate -file ENTProdIssuingCAcert.cer.txt -keystore /etc/tomcat7/olis.jks

keytool -import -trustcacerts -alias olis -file 12345678.cer1.txt -keystore /etc/tomcat7/olis.jks

sudo keytool -list -v -keystore /etc/tomcat7/olis.jks to have a look at the certs