Mirth Connect DICOM over TLS: Step-by-Step Tutorial

Introduction

DICOM moves medical images between modalities, PACS, VNAs and viewers, and by default it does so in the clear. When those images cross a network you don’t fully control (between sites, to a cloud archive, to a reading group), the DIMSE traffic needs Transport Layer Security (TLS).

This guide sets up DICOM over TLS in Mirth Connect and its open-source forks, OIE (Open Integration Engine) and BridgeLink. It covers what the DICOM connector’s TLS options actually negotiate, how to build the keystores, how to configure the DICOM Listener and DICOM Sender, how to test the connection from the command line, and how to read the handshake errors you are most likely to hit. It comes out of the DICOM work we do on Mirth and OIE, including an optional dcm4che5 backend for OIE’s DICOM connector.

What the Mirth DICOM Connector’s TLS Options Negotiate

The DICOM Listener and DICOM Sender are built on the dcm4che2 library, and their TLS setting picks a fixed set of cipher suites:

Three consequences are worth knowing before you start:

• The connection negotiates TLS 1.2. The TLS versions come from mirth.properties (https.server.protocols for the Listener, https.client.protocols for the Sender, both TLSv1.3,TLSv1.2 by default), but neither AES suite exists in TLS 1.3, so the handshake settles on TLS 1.2.
• The HTTPS cipher list does not apply. The modern https.ciphersuites list in mirth.properties governs the HTTP connectors, not DICOM. DICOM always uses the suites in the table above.
• Some peers will not match. Both AES suites use RSA key exchange. A PACS or archive configured to offer only modern ECDHE and AES-GCM suites has no suite in common with the connector, and the handshake fails. Bringing the DICOM connector’s TLS in line with the rest of the platform is one of the goals of the dcm4che5 backend work.

Setting Up Mirth Connect for DICOM over TLS

Getting Started

1. Download KeyStore Explorer https://keystore-explorer.org/ if you prefer a GUI. The commands in this guide use Java’s keytool, which ships with every Java runtime, and KeyStore Explorer can do each step through its menus.
2. Download Mirth Connect or its open-source fork OIE.

Video Tutorial

Generate and Import Certificates

Each side of the connection needs a keystore (its own private key and certificate) and a trust store (the certificates it accepts from the other side). Self-signed certificates are fine for a test; in production, use certificates from your organization’s internal CA or a recognized CA so they can be rotated and revoked properly. keytool prompts for each password; use a different, real one for every store.

1. Generate the Mirth side’s key pair and certificate

   keytool -genkeypair -alias mirth-dicom -keyalg RSA -keysize 2048 -validity 825 \
     -dname "CN=mirth.example.org" -keystore mirth-dicom-keystore.p12 -storetype PKCS12
   keytool -exportcert -alias mirth-dicom -keystore mirth-dicom-keystore.p12 -rfc -file mirth-dicom.crt

2. Generate the peer’s key pair and certificate (the modality, PACS or other system sending to or receiving from Mirth)

   keytool -genkeypair -alias pacs -keyalg RSA -keysize 2048 -validity 825 \
     -dname "CN=pacs.example.org" -keystore pacs-keystore.p12 -storetype PKCS12
   keytool -exportcert -alias pacs -keystore pacs-keystore.p12 -rfc -file pacs.crt

3. Import each certificate into the other side’s trust store

   keytool -importcert -alias pacs -file pacs.crt -keystore mirth-dicom-truststore.p12 -storetype PKCS12 -noprompt
   keytool -importcert -alias mirth-dicom -file mirth-dicom.crt -keystore pacs-truststore.p12 -storetype PKCS12 -noprompt

Copy the Mirth keystore and trust store to the server, somewhere the Mirth service account can read, for example /opt/connect/appdata/keysandcerts/.

Configure the Mirth Connect DICOM Listener

In the channel’s source connector (DICOM Listener), open the TLS settings:

1. TLS: select AES.
2. Client Authentication TLS: Yes for mutual TLS, where the sender must present a certificate your trust store accepts. Use this whenever you control both ends. Select No only when the sender cannot present a certificate.
3. Accept ssl v2 TLS handshake: No. No modern peer needs it.
4. Keystore: the path to the Mirth keystore, for example /opt/connect/appdata/keysandcerts/mirth-dicom-keystore.p12, with its Keystore Password and Key Password (the same value unless you set them differently).
5. Trust Store: the path to the Mirth trust store, for example /opt/connect/appdata/keysandcerts/mirth-dicom-truststore.p12, with its Trust Store Password.

Configure the DICOM Sender

A channel that sends DICOM over TLS uses the same fields on its DICOM Sender destination: TLS set to AES, the keystore and trust store paths and passwords, and client authentication matching what the receiving system expects. The receiving system’s certificate must be in the Mirth trust store.

Test the New DICOM over TLS Connection

Start with a C-ECHO or a single image from the command line before pointing a modality at the channel. dcm4che’s storescu offers the same cipher suites as the AES setting:

storescu --tls-aes --tls12 \
  --key-store pacs-keystore.p12 --key-store-type PKCS12 --key-store-pass <password> \
  --trust-store pacs-truststore.p12 --trust-store-type PKCS12 --trust-store-pass <password> \
  -c MIRTH_TLS@mirth.example.org:11112 image.dcm

Replace MIRTH_TLS with the Listener’s application entity title (or any title, if the Listener doesn’t check it) and 11112 with its port. A successful store shows up in the channel’s message browser; a failure shows up in the storescu output and in the Mirth server log.

Troubleshooting Handshake Failures

• no cipher suites in common: the two sides share no cipher suite. Check that both use AES, and whether the peer only allows ECDHE and AES-GCM suites (see above).
• PKIX path building failed / unable to find valid certification path: the certificate the other side presented is not in your trust store, or its issuing CA is missing.
• bad_certificate or certificate_required: client authentication is on and the sender presented no certificate, or one the Listener’s trust store does not accept.
• protocol_version: the two sides share no TLS version. Confirm the peer accepts TLS 1.2.
• keystore password was incorrect / Cannot recover key: a wrong keystore or key password.

Best Practices and Considerations

• Keep your TLS certificates up to date to avoid disruptions in service; track their expiry dates, because an expired certificate stops every study on that connection.
• Regularly monitor and audit your DICOM transmissions to ensure compliance with healthcare regulations such as HIPAA.
• While TLS encrypts the data in transit, ensure your network is also secured through firewalls, intrusion detection systems, and other security measures, and restrict the Listener’s port to the peers that should reach it.
• Keep keystores readable only by the Mirth service account. The DICOM Listener’s keystore and trust store fields accept ${...} variables, so the paths and passwords can live in the configuration map instead of the channel export.

Conclusion

DICOM over TLS in Mirth Connect comes down to three pieces: a keystore and trust store on each side, the AES setting on the DICOM Listener or Sender, and a test from the command line before real traffic flows. Knowing what the connector negotiates (TLS 1.2 with an RSA AES-CBC suite) explains most of the handshake failures you will meet, especially against newer imaging systems.

Have questions or need help working with DICOM or Mirth Connect? Saga IT can help.

Learn more about Saga IT’s Mirth Connect consulting services Learn more about our Medical Imaging Integration services Test your HL7 messages with our free online HL7 parser