Skip to content

4.0.0 Upgrade Guide

Chris Turczynskyj edited this page Mar 22, 2022 · 3 revisions

Database Reader XML Casing

In 3.12.0 we updated Apache Commons DBUtils and made some associated changes in our code. As part of that change, the XML created by the Database Reader was using the same case that appeared in the actual SQL query, whereas before 3.12.0 everything was just normalized to lowercase. In 4.0.0, we made some more updates in the Connect codebase to, again, normalize the casing to all lowercase.

If you are upgrading to 4.0.0 from any version before 3.12.0 there is no change for you and database queries will use the casing they always have.

If you are upgrading to 4.0.0 from 3.12.0 and had made changes adding AS clauses in your queries to work around the casing change in 3.12.0 there is no change for you.

If you experienced database query errors after upgrading to 3.12.0 due to casing in the query statements, after upgrading to 4.0.0 you should no longer encounter those errors.

TLS Protocols and Cipher Suites

Default TLS protocols and cipher suites have been updated. Weaker, potentially exploitable protocols and cipher suites have been disabled as a best practice.

TLS Protocols

TLSv1.1 has been disabled and the default protocols are now:

https.client.protocols = TLSv1.3,TLSv1.2
https.server.protocols = TLSv1.3,TLSv1.2,SSLv2Hello

Cipher Suites

The following cipher suites have been disabled:

  • TLS_RSA_WITH_AES_256_CBC_SHA256
  • TLS_RSA_WITH_AES_256_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

If you had updated your https.ciphersuites in mirth.properties previously, you will see a https.ciphersuites.old property which contains your previous values. If you had not updated https.ciphersuites then https.ciphersuites will have been updated removing the cipher suites above.

Impact

If any of your connectors, either connecting to external servers, or allowing clients to connect were using these older protocols or cipher suites then it is possible they may fail a TLS handshake after upgrading to 4.0.0.

Resolution

If you encounter a TLS handshake error after upgrading it is best to let the external entity know they need to switch to a more secure protocol and/or cipher suite.

If this is not possible:

SSL Manager Options

SSL Manager TLS Options

If you are using the SSL Manager commercial extension, you can select TLSv1.1 and/or a weaker cipher suite for the connector(s) which need to allow these weaker legacy protocols and cipher suites.

Server Wide Options

If you are not using the SSL Manager commercial extension, you can manually add back TLSv1.1 to your https.client.protocols or https.server.protocols or any of the cipher suites removed above to your https.ciphersuites property (in mirth.properties) to restore previous, less secure, behavior for all of your connectors.

HTTP User Agent

When HTTP Connectors send a message, the user-agent header will no longer include information about the Apache or Java library versions (example user-agent=[Apache-HttpClient/4.5.13 (Java/1.8.0_181)]) and will instead send "Mirth Connect" as the user agent. This default user agent can be overridden with a different user agent by populating your own user-agent header in the HTTP Sender's headers table.

HTTP Server Header

In previous versions of Connect, HTTP connectors and the Connect web server, which hosts the Dashboard and API documentation, would automatically add a server header which included the version of the Jetty library (example server=[Jetty(9.4.21.v20190926)]). Jetty would also show a "Powered by Jetty" message (example Powered by Jetty://9.4.21.v20190926) on error pages. To prevent external entities or malicious tools from easily learning about the libraries and versions used within Connect, after upgrading to 4.0.0, neither the Jetty header nor the "Powered by Jetty" message will be included in HTTP responses.

FHIR Extension

The FHIR extension is now part of NextGen's commercial extensions and no longer freely available. If you would like to use the FHIR extension, please contact [email protected] for more information.

Clone this wiki locally