Tool to test TCPS Receiver (TCP over TLS)

[tom08zehn]

I had the need to test TCPS connections because my Mirth is not able to do it (without the SSL Manager plugin) and I just wanted to share the Python code I wrote.

It was useful for me to check whether the TCPS endpoints present a proper SSL certificate.

It's still very basic, so feel free to adapt it to your needs.

#!python

"""
HL7v2 Sender, MLLP-framed over TCP + TLS encryption
https://gist.github.com/marshalhayes/ca9508f97d673b6fb73ba64a67b76ce8

Connects to a TCP socket over TLS, sends an MLLP-framed HL7v2 message and prints the response (HL7v2 N/ACK) as well as the server certificate.

Example:

{'OCSP': ('http://ocsp.digicert.com',),
 'caIssuers': ('http://cacerts.digicert.com/DigiCertGlobalG2TLSRSASHA2562020CA1-1.crt',),
 'crlDistributionPoints': ('http://crl3.digicert.com/DigiCertGlobalG2TLSRSASHA2562020CA1-1.crl',
                           'http://crl4.digicert.com/DigiCertGlobalG2TLSRSASHA2562020CA1-1.crl'),
 'issuer': ((('countryName', 'US'),),
            (('organizationName', 'DigiCert Inc'),),
            (('commonName', 'DigiCert Global G2 TLS RSA SHA256 2020 CA1'),)),
 'notAfter': 'Mar 17 23:59:59 2025 GMT',
 'notBefore': 'Feb 28 00:00:00 2024 GMT',
 'serialNumber': '********************************',
 'subject': ((('countryName', 'US'),),
             (('stateOrProvinceName', 'Massachusetts'),),
             (('localityName', 'Boston'),),
             (('organizationName', 'Interoperability Bidco, Inc.'),),
             (('commonName', '*.domain.com'),)),
 'subjectAltName': (('DNS', '*.sub.domain.com'),
                    ('DNS', 'sub.domain.com'),
                    ('DNS', 'www.sub.domain.com')),
 'version': 3}
"""

import ssl
import socket
import pprint

# MLLP settings
# Start of message bytes
MLLP_SOM = b'\x0B' # <VT>
# End of message bytes
MLLP_EOM = b'\x1C\x0D' # <FS><CR>
# Composes: <VT><Message Data><FS><CR>

CHARSET = "utf-8"

HOSTNAME = "your-host-here"
PORT = 443
CERT = "ca-bundle.crt" # bundle of trusted root CA certificates in PEM format
MESSAGE = None # bytes! (I recommend using MESSAGE_FILE instead)
MESSAGE_FILE = r"C:\Path\to\HL7v2\Message.txt" # carriage return line endings!

def main(hostname, port, cert, message=None, messageFile=None):
    sslSocket = None
    try:
        # Read message in binary mode
        if message is None:
            with open(messageFile, "br") as f:
                message = f.read()
        # Create SSL context
        sslContext = ssl.create_default_context()
        # Load the trusted root CA certificates
        sslContext.load_verify_locations(cafile=cert)
        # Wrap socket in SSL socket
        sslSocket = sslContext.wrap_socket(socket.socket(socket.AF_INET, socket.SOCK_STREAM), server_hostname=HOSTNAME)
        # Connect to SSL socket
        sslSocket.connect((hostname, port))
        # Print server certificate
        pprint.pprint(sslSocket.getpeercert())
        # Wrap HL7 message in MLLP-frame (so we can simply use `socket.sendall()`)
        mllpRequest = MLLP_SOM + message + MLLP_EOM
        # Print MLLP-framed message (escaped characters)
        print("Server request (MLLP-framed):", str(mllpRequest, encoding=CHARSET).encode("unicode_escape").decode(CHARSET))
        # Send message
        sslSocket.sendall(mllpRequest)
        # Receive response
        # https://www.digitalocean.com/community/tutorials/python-socket-programming-server-client
        # https://docs.python.org/3/howto/sockets.html#using-a-socket
        mllpResponse = sslSocket.recv(1024)
        # Print server response (escaped characters)
        print("Server response (MLLP-framed):", str(mllpResponse, encoding=CHARSET).encode("unicode_escape").decode(CHARSET))
        # Extract HL7 N/ACK
        ack = mllpResponse.lstrip(MLLP_SOM).rstrip(MLLP_EOM).decode(CHARSET)
        print("HL7 N/ACK:", ack)
    except Exception as e:
        print("Error:", e)
    finally:
        if sslSocket is not None:
            try:
                sslSocket.close()
                return True
            except Exception as e:
                print("Error closing SSL socket:", e)
        return False

if __name__ == "__main__":
    print("Sending HL7v2 message successful?", main(HOSTNAME, PORT, CERT, message=MESSAGE, messageFile=MESSAGE_FILE))

[pacmano1]

You don't need to send a message to get / test TLS configs. testssl.sh (https://testssl.sh) can do a full analysis and openssl cli can get the certs if needed. Just a note for readers of this post. it is potentially valuable to send a transaction of course. There are tools for that as well, including Stunnel and HAproxy. Just some alternatives.

[tom08zehn]

Yes, but (1.) testssl.sh teared down the interfaces on the remote system 😬 and (2.) it cannot send a transaction to prove that the connection works. Printing the server certificate details was just a nice extra.

I simply found it too complex to set up stunnel or HAproxy for such a simple test. Of course, you would need it if you want Mirth to send/receive over TCPS.

[nicovn]

You can also use the free (graphical) tool HAPI TestPanel to test HL7 TLS connections

https://hapifhir.github.io/hapi-hl7v2/hapi-testpanel/

To start the tool you can use a batch file with the contents below to specify the TLS settings:

`echo off
rem *****************************************************
rem THIS SCRIPT WILL LAUNCH THE TESTING UI FOR HAPI
rem YOU MUST FIRST SET THE ENVIRONMENT VARIABLE HAPI_HOME
rem TO THIS DIRECTORY
rem *****************************************************

if NOT EXIST %HAPI_HOME% ( echo Warning: The HAPI_HOME environment variable is not set or not valid. )

set PORT=8888
set HAPI_HOME=C:\Downloads\hapi\testpanel-2.0.1
echo HAPI_HOME is set to %HAPI_HOME%

echo Running ca.uhn.hl7v2.app.TestPanel with HL7Service on port %PORT%
call java -version
call java -Xmx1048m -Dlog4j.configuration=file:///%HAPI_HOME%/log4j.xml -Dhapi.home=%HAPI_HOME% ^
-Djavax.net.debug=all ^
-Djavax.net.ssl.trustStore=hapi-testpanel-truststore.jks ^
-Djavax.net.ssl.trustStorePassword=hereyourpassword ^
-Djavax.net.ssl.keyStoreType=pkcs12 ^
-Djavax.net.ssl.keyStore=hapi-testpanel-keystore.p12 ^
-Djavax.net.ssl.keyStorePassword=hereyourpassword ^
-jar hapi-testpanel-2.0.1-jar-with-dependencies.jar %PORT%

pause`

Best Regards

Nico