All posts by Brady Mathis

CMS Embracing Open Source

The new Open Medicaid IT strategy was codified into law as of December 4, 2015 and it went into effect on January 1, 2016 (see Federal Register | Medicaid Program; Mechanized Claims Processing and Information Retrieval Systems (90/10)). This is a must read. Note that the Federal Rule not only mentions “open” and “open source” 43 times, it actually explains why CMS, in collaboration with the States, has embraced an open source approach to Medicaid IT. This rule breaks standard Federal rule-making in that it wisely leaves many of the specific details of its implementation open to development in collaboration with State agencies and public servants, the health IT industry, and the open source community. Thus the RFI and one of the key the reasons OSEHRA and the OSEHRA community should provide input.

Conundrum Release out of Beta

Release 2.3.1 (the 20150625 snapshot) brings the “Conundrum” release out of beta, upgrading Neuron to the March 14, 2014 release of Tolven and addressing several other issues in Neuron. Here’s what’s new in Conundrum:

Compatibility with Java 7 and Drools v6

Improved column width calculation

The application now uses the average character width, determined from information supplied by the client browser, to better determine how many characters can be displayed in a given column before truncation is necessary.

Resolved issues in list displays

Display issues on lists such as the HCQM Encounters list, Outbound Message Queue, and Electronic Notes lists have been resolved.

Removed medications with Lexicomp drug lookup

Since the Medication Administration Record (MAR) plugin depends on the proprietary Lexicomp libraries, we have elected to remove this plugin from the open source collection. Thus Neuron no longer contains the MAR and all its dependent plugins. However, the MAR plugins are still freely available as is the source code. Please contact the team at Neuron Health for information about these plugins.

Resolved references to a deprecated allergies list

The Neuron plugins contained references to a list that has been deprecated. These references have been updated. echr:patient:allergies:current is no longer a valid list. All references to this list have been updated to echr:patient:allergies:active.

Additional default properties

We have added a set of default patient types to represent Inpatient. These values are specified in org.rhsoftware.inpatientPatientTypes and may be modified for your instance. The values in this system property control the workflow in the Consolidated CPOE module.

Resolved issues in the nullification of vitals

During the beta period, we found an error that prevented users from nullifying certain observations within a vitals assessment. This problem was due to an error stemming from the introduction of “fuzzy” dates in Tolven. We made changes to the Vitals Assessment TRIMs to reference the correct data element with the appropriate precision.

Updated javascript for wizards

We resolved some compatibility problems between Neuron code and updated javascript for wizards in the Tolven snapshot. This new javascript enables enhanced functionality in several wizards, such as the allergies wizard.

Important Notes:

Many, if not all, development and testing instances will use auto-generated certificates and key pairs for a Neuron instance. However, most modern browsers will no longer render a page that uses a key with less than 2048-bit RSA security. This means that previous auto-generated keys will no longer work. You will receive an error message in the browser when you attempt to login to the Neuron instance. Take a look at Generating 2048-bit RSA Keys for Neuron for a detailed guide that will help you resolve this problem.

Also, please note that this is a major upgrade, so please see our Upgrade Considerations page.

Generate 2048-bit RSA keys for Neuron

As you most likely know, most modern browsers will no longer render a page encrypted with less than a 2048-bit RSA key.  For those of us who use the auto-generated self-signed certificates in Neuron for our test and development environments, this means we’ve got to upgrade.  There are a couple of options for generating new keys.  If you are deploying a new instance from scratch, it’s actually pretty simple to get your key length and algorithm up to snuff.  On the other hand, if you have an existing development instance, there are a few other steps you need to follow.  Don’t worry, the intrepid engineers working on the Neuron project have already traversed these shark-infested waters, and we have a few tips that should help you out.

In the more recent releases of the Tolven framework, the install process has become largely automated.  This is a great thing – for the most part.  It turns out that the ant scripts that deliver the automated SSL certificates are using the default key algorithm and key length, which results in a 1024-bit DSA key.  Though it has been some time since the CA/Browser Forum updated the requirements for SSL, most browsers still rendered pages using certs that didn’t meet the requirements.  However, recent updates to Firefox and Chrome changed that easy-going modus operandi.  Now, pages encrypted with anything less then 2048-bit RSA won’t even be loaded.  So, if you try to login to your Neuron instance, and instead of the login page you get an error message, it’s time to upgrade your SSL certs.

Cut the chat, what’s the syntax!

Let’s cut to the chase, then.  If you want to generate new keys for your app, here’s the keytool command to get you there.

keytool -genkey -alias tolven -dname “dev.example.com, ou=services, o=tolven, c=US” -keystore newKeystore.jks -keyalg RSA -keysize 2048 -storepass tolven -keypass tolven -validity 7300

Of course, you must replace dev.example.com with your local instance name.  Now that you have a cert that your browser will like, you need to propagate this to your JBoss configuration.  If you want more detail about how to make your Neuron instance use these new keys, jump on down to the The Handy Guide to Upgrading (below).

Generating Keys for a Fresh Neuron Instance

Now then, since the Tolven team worked so hard to automate the initial deployment of these certificates, you might also consider making use of that mechanism to simplify things.  If you need to deploy a new instance of Neuron, you can make a few modifications to the right ant script and the automated generation will take care of generating the certs and distributing them to the other components for you.

First locate the build.xml file.  Look here:

snapshots\V21_20140314_ONC_snapshot\tolven-installer\

Then, find the following ant target.  It should be about 170 lines down.

<target name="create-common-keystore-src" if="${createCommonKeystoreSrc}"> <keytool args="-genkey -alias tolven -dname &quot;cn=${tolvenDomain}, ou=services, o=${keystoreOrg}, c=US&quot; -keystore ${initialComponents.commonKeystoreSrc} -storepass ${password.commonKeystore} -keypass ${password.commonKeystore} -validity 7300" /> </target>

Having located the create-common-keystore-src target, just insert the -keyalg RSA -keysize 2048 arguments right before the -storepass argument.  Save this file, and continue with the install as normal.  The ant script will handle the rest for you, and your browser will be happy.

The Handy Guide to Upgrading

Those are the easy options.  Chances are, you have an existing Neuron instance that needs to be upgraded to work with the browser restrictions.  Here’s a guide for getting this done.

1. Backup the existing keys and certs

This section is like the fine print at the bottom of the rental agreement for a jet ski.  “Dear user, if you hurt yourself with this toy, it’s not our fault.”  Check out the following location, and make backup copies of the keys therein.

[tolven_home]\tolven-config\credentials\dev.example.com\

As usual, replace dev.example.com with your instance name.

2. Generate a new key pair

Once you have backed up the existing cert data, go ahead and generate a new key pair using the keytool command shown here.  Execute this command from the key repository folder (above).

keytool -genkey -alias tolven -dname “dev.example.com, ou=services, o=tolven, c=US” -keystore newKeystore.jks -keyalg RSA -keysize 2048 -storepass tolven -keypass tolven -validity 7300

3. Rename the keystore

Now rename the newKeystore.jks file to keystore.jks.  This should overwrite the existing keystore (containing the 1024-bit DSA key) with your new keystore that contains the browser-pleasing 2048-bit RSA key.  Keeping the file name, keystore.jks, simplifies the integration process since many of the components expect that file name.

4.  Get the new key into the trust store

Getting the key into the trust store is a two step process:  export and import.  While there are openssl commands that will accomplish this task, we’ve taken to using Portecle for this type of thing.  You can use the Java Web Start option, or you can download the jar files from SourceForge.  Either way, fire up Portecle and open the keystore (keystore.jks).  Use this tool to export the key pair from the keystore.  Pick decent file name and use the default file type since you will use Portecle in the next step to import the key.

Now, using Portecle, open the trust store, which is called cacerts.jks.  Import the key that you just exported from the keystore a moment ago.  There will already be a keypair with the alias tolven in the trust store.  That’s OK.  Overwrite the existing alias with your new keypair.  That’s the idea here, we want to update the alias known as “tolven” with a 2048-bit RSA key.  With this, and all other key manipulation steps, use the password “tolven” when prompted.

5.  Generate keys for PostgreSQL

Most of the components of Tolven will reference these files, but we need to create another set of files for PostgreSQL, following the same steps you’ll find in the install guide.  Make sure you are in the key repository.

[tolven_home]\tolven-config\credentials\dev.example.com\

Then run the commands that follow.  First make a PKCS12 key.

keytool -importkeystore -srckeystore keystore.jks -destkeystore keystore.p12
-srcstoretype JKS -deststoretype PKCS12 -srcstorepass tolven -deststorepass
tolven -noprompt

Next, prepare the certs for PostgreSQL.

openssl pkcs12 -in keystore.p12 -out server.key -nocerts
openssl pkcs12 -in keystore.p12 -out server.crt -nokeys
copy server.crt root.crt

Now, copy these new files to the PostgreSQL data folder.  These commands assume that you have followed the install guide for your system and therefore you have an environmental variable called PGDATA that points to the PostgreSQL data folder.

copy server.key "%PGDATA%"
copy server.crt "%PGDATA%"
copy root.crt "%PGDATA%"

Finally, jump over to the PostgreSQL data folder, and remove the password from the server.key file.

cd "%PGDATA%"
openssl rsa -in server.key -out server-nopasswd.key

Now, delete server.key and rename server-nopasswd.key to server.key.  Modify the properties of server.key and set it to read-only.  Done!

If everything worked according to plan, you only need to restart the component services of Neuron and you are off and running with 2048-bit RSA keys.  Restart OpenDS, PostgreSQL, and finally JBoss.

Neuron EHR Quick Tour

The team at Roberts-Hoffman has started producing a video series to lower the barriers to exploring Neuron Health.  Now, you don’t have to download the code from our SourceForge site or follow the install guide to experience the Neuron EHR.   Instead, just point your browser to our YouTube channel and watch the video tour.

The playlist below will give you an overview of the basic components of the Neuron EHR. The series of videos begins with how to login and select an account.  Then you can see an introduction to each of the top-level tabs in the application.  Stay tuned for more detailed explainer videos in the future.