We're here to help.

Osirix Connectivity using Stunnel on MacOS Big SurMacOS


When a medical modality or a DICOM software client connects to a (PACS) server, communication begins between the systems. Typically, this communication is unsecured, meaning any third party could potentially see what data is being exchanged. The Butterfly Cloud DICOM Connector creates a secure, encrypted connection between Butterfly Cloud and your facility’s DICOM endpoints. This enables secure transmission of ultrasound studies captured with Butterfly iQ+, via Butterfly Cloud, to a DICOM PACS, VNA or other medical image archive.

The Butterfly Cloud DICOM Connector utilizes DICOM-TLS (Transport Layer Security, v 1.2) to facilitate point-to-point encrypted communication without the drawbacks and setup challenges associated with a VPN tunnel.

Since many PACS solutions do not inherently support the encryption/decryption of DICOM-TLS, we leverage either a network device such as a Citrix ADC (Netscaler), F5 Networks Big-IP, or software like Stunnel to terminate (decrypt/encrypt) the TLS encrypted network traffic.

Stunnel is a proxy designed to add TLS encryption/decryption functionality to existing clients and servers without any changes in the original programs' code.

Stunnel is a free software authored by Michał Trojnara and distributed under GNU GPL version 2 or later with OpenSSL exception. Additionally, commercial technical support for Stunnel or non-GPL licenses are offered for a fee directly from Stunnel.

Figure 1. DICOM-TLS Termination Using Stunnel Software

DICOM-TLS Termination Using Stunnel Software



  1. Ensure that you have access to Butterfly Cloud (cloud.butterflynetwork.com) as an Administrator, so that you can configure the PACS connection. The PACS configuration screen will provide you with the digital certificate-key pair that will be used with Stunnel.

  2. Ability to install software on a system running MacOS Big Sur. The system will have to remain in operation continually to run the Stunnel software and proxy the TLS connection form Butterfly Cloud.

  3. On your firewall - NAT or port forward the port that you wish to receive the encrypted DICOM-TLS data from Butterfly Cloud to the server that has Stunnel installed.

  4. Install Osirix Lite or MD, or other DICOM viewer compatible with MacOS Big Sur.

    1. Configure Osirix Listener to use port 11112.

    2. Do NOT configure DICOM-TLS in Osirix.


Set Up Connection from Butterfly Cloud and Download Digital Certificate

  1. Log in to Butterfly Cloud using your Browser - ensure that your user role in Butterfly Cloud is that of Administrator.

  2. Navigate to the DICOM Configuration menu. Click your username in the upper right of the window and select Organization Settings.

  3. Select the Connectivity tab and click the ‘+ Add’ option next to Connections to create a new TLS end-point that will be used with your DICOM integration.

  4. Proceed to enter all of the necessary DICOM connection parameters.

    1. Name = Friendly name for the Connection.

    2. In the 'Security' section - set TLS to 'Active' and select the 'Generate' option.

    3. Select the PEM download format, and click 'Download'. Ensure that you receive 2 files: Butterfly_SCP_Cert.pem and Butterfly_SCP_key.pem

      1. The 2 files will be used in a later step; during the configuration of your TLS termination.

    4. Select PFX as the download format, and ensure that you copy/save the Secret password for later use.

      1. You will be prompted to download the Butterfly_SCP_key_pair.pfx file which contains the Digital Certificate.

    5. In the 'SCP' section - Enter the Host information, DNS name or IP of your TLS end-point.

      1. Please note that the IP address must be a public IP that can be accessible from Butterfly Cloud to your network. This will typically be the IP address of your network firewall, router, or TLS termination device. Non-routable/private IP addresses are not valid.

  5. Click Save, then click on the Connectivity tab to create the DICOM Integration.


Configure the DICOM Integration and Associate the TLS Connection

  1. After clicking on the Connectivity tab, click the ‘+ Add’ option next to Integrations and select PACS/VNA.

  2. Give your PACS/VNA a friendly Name, and select to associate it with the TLS Connection created in Set Up Connection from Butterfly Cloud and Download Digital Certificate.

  3. Proceed to enter all of the necessary DICOM integration parameters.

    1. SCU - Calling AET = The source AE Title of Butterfly Cloud (typically ‘BUTTERFLY’).

    2. SCP - AET = the AE Title of your DICOM destination.

    3. Enter a Port that you will need to forward from your firewall or router to the computer hosting the Citrix ADC software.

      1. Port 11113/TCP is typically used for DICOM-TLS.

    4. Please note that the port that is entered here is the public-facing port that is exposed by your TLS termination point.

  4. Set the Compression level of the DICOM Images and Cine Loop as required or preferred. The settings above are typical. Select ‘Save Configuration’ to complete the setup.


Configure the MacOS Network Settings

  1. Turn off MacOS firewall in settings.

  2. Make note of the IP address that is configured. This will be the IPAddress1 used below.

  3. Configure a second IP Address on you Mac using Preferences, going to network settings, and then clicking the + sign.

    1. Use a manually configured IP address within your subnet but outside of your DHCP range, use the same Netmask as your existing subnet.

    2. This will be IPAddress2 used below.


Install and Configure Stunnel

  1. Install Homebrew via browser using the following text on one line:

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  2. Install Stunnel and SSL using Homebrew from terminal command line, keep the windows open for reference.

    brew install stunnel
    brew install openssl@1.1
  3. Install PEM key and Cert.

    1. Remove any Butterfly keys / certs from Mac Keychain.

    2. Do NOT install Butterfly Key and / or Cert to the Mac Keychain.

    3. Copy key and cert from the Downloads folder to the folder /usr/local/etc/stunnel

    4. Verify that the Key in the Stunnel folder starts with the line “-----BEGIN RSA PRIVATE KEY-----”.

      1. If it does not, open the file with TextEdit and delete the text.

      2. Open the Key file from the Downloads directory in a new window.

        1. Copy the text from this file and paste it into the file in the Key file in the /usr/local/etc/stunnel directory.

    5. Verify the Cert in the Stunnel folder starts with the line “-----BEGIN CERTIFICATE-----”.

      1. If it does not, open the file with TextEdit and delete the text.

      2. Open the Cert file from the Downloads directory in a new window.

        1. Copy the text from this file and paste it into the file in the Cert file in the /usr/local/etc/stunnel directory.

    6. Edit the Users/your-user-name/Downloads/stunnel.conf-sample file using TextEdit as follows:

      1. cp /usr/local/etc/stunnel/stunnel.conf-sample /Users/your-user-name/Downloads.

        1. Replace your-user-name with your MacOS profile name.

      2. Add a “;” to the beginning of every line that does not already start with a “;”.  This will mark the lines as comments, so they will not be processed by stunnel.

      3. After “Global Options”, add the following line:

        1. “Foreground = yes”

      4. Before “Example Client Mode Services”, copy and paste the following text:

        ;********************************* Example TLS server mode services
        sslVersion = TLSv1.2
        [DICOM STORE]
        accept = IPAddress1:11113
        connect = IPAddress2:11112
        cert = usr/local/etc/stunnel/Butterfly_SCP_Cert.pem
        key = usr/local/etc/stunnel/Butterfly_SCP_Key.pem
        verifyChain = off
      5. ** Replace IPAddress1 and IPAddress2 with the two addresses configured on your Mac.

      6. Copy the stunnel.conf-sample file to /usr/local/etc/stunnel/stunnel.conf.

    7. Open a terminal window and type Stunnel followed by Enter.

      1. Make note of any errors marked with [!] at the beginning of the line.

      2. If you want Stunnel to start every time your computer is started, type the following command at the command prompt in Terminal:

        brew services start stunnel
      3. Otherwise you will need to open a Terminal window to manually start Stunnel when needed.

      4. Restart the MacOS firewall and allow Stunnel to access data on and receive data from the internet.


Verify the Connection from Butterfly Cloud

  1. Switch back to Butterfly Cloud in the Browser.

  2. Navigate to the integrations menu. Click your username in the upper right of the window and select Organization Settings.

  3. Select the Connectivity tab and click the ‘...’ next to the newly created DICOM integration. Select the Echo option to perform a DICOM C-ECHO from Butterfly Cloud.

  4. Click Echo, then Click on ‘Echo’ again in the upper right of the pop-up menu. This triggers a new  DICOM C-ECHO; please verify the output is similar to below.

  5. Congratulations - you have setup an encrypted DICOM-TLS connection to your DICOM destination.

Was this article helpful?
2 out of 2 found this helpful
Thank you for your feedback

We’re sorry this didn’t answer your question. We’re here to help. Contact us