Security

Protocol Summary

XDS Toolkit supports three types of IHE transactions. We list two HTTP based protocols separately because the Toolkit software implementation differs.

• HTTP(S) / SOAP transactions that support IHE XDS
• HTTP(S) / simple GET transactions that support DICOM WADO
• HL7 Minimum Lower Layer Protocol (MLLP) to send/receive HL7 V2 ADT messages.

The two HTTP based transactions can be tested in toolkit using plain HTTP as well as HTTPS. The HL7 MLLP transactions are only supported using straight TCP. There is no TLS implementation included for HL7 V2 transactions.

Socket Level Security

Implementation Overview

Toolkit is designed to both initiate and accept HTTPS transactions. Inbound HTTP and HTTPS transactions are sent to the Tomcat servlet container and then delivered to the Toolkit software. That means that all HTTPS handshaking is managed by the Tomcat server and is not directly controlled by Toolkit software.

Outbound HTTP and HTTPS transactions are initiated by Toolkit using Java code. That Java code uses different methods of creating the HTTPS connection internally, but the configuration remains the same. The internal differences are due to the library used to manage SOAP connections that is not used for the WADO transactions. As mentioned, both types of outbound HTTPS connections use the same configuration mechanism to control TLS socket parameters.

Configuration

Inbound Connections (Tomcat)

SSL/TLS configuration for Tomcat is found in the Tomcat conf/server.xml file. There is a element that has a number of attributes for configuring an inbound connection. An abbreviated example is: <Connector port="8483" maxThreads="150" ...../>

The attributes that are of interest and need to be configured are:

Attribute	Value	Comment
scheme	https
secure	true
clientAuth	true
SSLEnabled	true
sslProtocol	TLS
ciphers		See notes below
keystoreFile		See notes below
keystorePass		See notes below
sslEnabledProtocols		See notes below
truststorePass		See notes below

ciphers: A comma separated list of ciphers accepted by Tomcat. If you do not specify this attribute, you get Tomcat default behavior (not documented here). For example ciphers="TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

keystoreFile: Path to the Java keystore file that contains the certificate used on behalf of Toolkit.

keystorePass: Plain text string with the password to the keystore file. Typical implementation is to use the Java default of 'changeit', but that is not a required value.

sslEnabledProtocols: A comma separated list of protocols accepted by Tomcat. As with ciphers, you can get the default Tomcat behavior by omitting this attribute. An example is sslEnabledProtocols="TLSv1.1,TLSv1.2"

truststoreFile: Path to the Java truststore file with CA and other certificates that represent the system or systems under test. This might contain only the certificate used to sign any system certificates.

Outbound Connections (Java Code)

Prior to version 6.5, Toolkit used one shared file for both the Java keystore and Java truststore. It also defaulted to whatever the JRE used for CipherSuites and SSL Protocols.

Starting with version 6.5.0, Toolkit allows you to have separate keystore and truststore files or continue to share one file. It also allows you to configure specific values for CipherSuites and SSL Protocols.

keystore: The Java keystore for outbound connections is stored in the external cache under the current test session. Look in the folder $EXTERNAL_CACHE/environment/$TESTING_SESSION/keystore. That folder contains two files that contain the keystore (file = keystore) and the password to the keystore (keystore.properties). This is the configuration supported by Toolkit for some time. If the keystore files are not present, outbound TLS connections are not possible.

truststore: If you want to use a shared file for both the keystore and truststore, you include the files described above in the keystore folder and nothing else. If you want a separate truststore, add a file called truststore to that folder and a separate file called truststore.properties with the password for the truststore file. If these truststore files are not included, Toolkit will use the same behavior that was implemented before the 6.5.0 release.

CipherSuites: There is a toolkit property called Client_Cipher_Suites. This is a comma separated list of CipherSuites that are accepted by Java network software. For example, you can specify TLS_RSA_WITH_AES_128_CBC_SHA. If you leave the value for this property empty, Toolkit will default to what the JRE implements.

SSLProtcols: The Toolkit proper Clilent_SSL_Protocols is a comma separated list that controls the SSL Protocols used when making a network connection. If you leave the value for this property empty, Toolkit will default to what is implemented by the JRE. An example of such a list would be: TLSv1.1,TLSv1.2.

Gazelle STS

See this link.

Tomcat HTTPS Configuration Sidenotes

The documentation for Tomcat7 describes the attributes that control TLS connections. Experience showed that the configuration described by the documentation did not work. After some trial and error, we managed to get the TLS connections working using the configuration described above.