Skip to main content

Automated Delivery Service Encryption Guide

Updated

Contents

Overview

This guide contains technical instructions and is intended for use by information technology professionals such as data engineers, data analysts, and developers. 

Teladoc Health's Automated Delivery Service allows customers to receive an encrypted CSV of their data for use as a source in their own data pipelines, reporting tools, or spreadsheet applications like Excel.

The topics in this article demonstrate how to generate public and private encryption keys and how to use the private encryption key to decrypt data sent by the Automated Delivery Service.

The Automated Delivery Service relies on a free, open-source program called GnuPG to encrypt and sign the data files being sent. GnuPG follows the OpenPGP standard defined by RFC4880 (also known as PGP). You can find more information on GnuPG at GnuPG.org.

  • GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. Other frontend applications, libraries, and commercial products are available.
  • Since its introduction in 1997, GnuPG has been free software that can be freely used, modified, and distributed under the terms of the GNU General Public License

Important points to remember:

  1. Customers should never share a private encryption key or a secret passphrase with anyone, including Teladoc Health. Customers must treat their private encryption key as any other sensitive credential or password.
  2. The public encryption key, however, will need to be shared with Teladoc Health so that Teladoc Health can encrypt the files before delivering them to the customer. Teladoc Health securely stores all customer public keys.
  3. Teladoc Health encrypts data files using the customer-provided public encryption key, but Teladoc Health cannot decrypt them once they are encrypted.
  4. If a customer loses the private encryption key or forgets the secret passphrase, it will no longer possible to decrypt the files. To remedy this situation, the customer would need to re-generate the keys and provide a new public key to Teladoc Health. Teladoc Health would then use the new public key to encrypt the files going forward.

The diagram below shows the encryption/decryption process at a high level. SENDER is Teladoc Health's Automated Delivery Service (ADS), and RECEIVER is Teladoc Health's customer:

Screenshot of user interface

Generating keys

There are a variety of GnuPG client applications that can generate the PGP keys. However, this guide will only cover the two options below – a GnuPG command line utility and Gpg4win, a free Windows application that integrates a user-friendly interface into the Windows Shell and File Explorer.

How to generate keys using the GnuPG command line tool

Various free GnuPG tools are available for download. Customers should download the latest version of GnuPG, unzip the folder, locate the INSTALL.txt file inside, and follow the instructions under Basic Installation.

Linux users can also install the GnuPG (GPG) command line utility; however, some Linux distributions ship with it.

Please note that this guide uses version 2.4.7 of the GnuPG command line tool. There might be some minor differences depending on the version of the utility used.

  1. Once installed, generate a new key pair (a public key and a private key) by running the command: gpg --full-generate-key
  2. Select RSA and RSA (option 1 in the image below) when prompted on what kind of key you want.
    Screenshot of user interface
  3. When prompted for the key length, press enter to choose the default size of 3072 bits.
    Screenshot of user interface
  4. When prompted for how long the key should be valid, press enter to choose the default value of zero. This option means the key will never expire. You must confirm this choice with the y key.
    Screenshot of user interface
  5. The encryption keys must be tied to a user ID. We'll create that user by specifying the name, email address, and an optional comment. You can use any name or email, but be sure you can identify them. Teladoc recommends using your company email or your team's distribution group email. Change or confirm your choices by entering the letters in the parentheses.
    Screenshot of user interface
  6. Lastly, GnuPG will prompt you to enter a secret passphrase. If you forget this secret, you cannot decrypt your data later.
    Screenshot of user interface
  7. If the encryption key-pair generation is successful, the output should look something like this:Screenshot of user interface

The next step is to export the public key to a file (remember never to share your private key) and email it to the Teladoc team.

  1. Copy the public key fingerprint (highlighted in the screenshot below), as you will need it to build the export command in the next step. If you need to, you can execute a command to list all your keys: gpg --list-keysScreenshot of user interface
  2. Next, we must build a command using your public key fingerprint and give the exported key file a name. The file should follow this naming convention: myorg-public-key-for-teladoc.asc - replace myorg with your company name.
  3. $ gpg --export -a D45342D29117672C98D2CB9C4DA8DB0E06E25693 > myorg-public-key-for-teladoc.asc
  4. Now, simply email myorg-public-key-for-teladoc.asc to the Teladoc team.

Optionally, you can export the private key in a separate file (but do not share it with anyone). Once the private key is exported, you can store it as a file in your preferred secret vault or transfer it to another computer and import the key if you wish to decrypt the files on another machine:

  • gpg --list-secret-keys
  • gpg --export-secret-key -a keyfingerprint > privatekeyname.asc

How to generate keys using Windows Gpg4win application

Teladoc recommends that Windows users install Gpg4win, which will install both the command line tool and a Windows application.

Download Gpg4win first and then install it. You can always refer to the official Gpg4win user guide here.

  • Open Gpg4win's Kleopatra application - a front-end interface to the official GnuPG utility. If you previously generated other keys using the gpg command-line utility, Kleopatra will list these keys conveniently.

Go to the File menu and click "New OpenPGP Key Pair..."Screenshot of user interface

You must specify the name and email address, protect the key with a passphrase, and configure some advanced options.

  1. You can use any name or email if you can identify and trust the person associated with them.
  2. Teladoc recommends using your company email or your team's distribution group email.
  3. Check the "Protect the generated key with a passphrase" box.
  4. Press the Advanced Settings show/hide button to show the advanced settings.Screenshot of user interface
  5. In the Key Material dropdown, select rsa3072
  6. Uncheck the "Valid until" box so this key pair does not expire.Screenshot of user interface
  7. Kleopatra will prompt you to select a secret passphrase. Make sure to memorize or store the secret passphrase securely, as you will need it later to decrypt the files, and you cannot see it once it is created.
  8. At this point, the new key pair is generated.

The next step is to export the public key (remember never to share your private key) to a file that can be shared with the Teladoc Health team.

  1. Under the certificates list, right-click on your newly created key and select Export.
  2. Name the file "myorg-public-key-for-teladoc" (replace myorg with your company name) and hit save. The file should get the .asc extension.Screenshot of user interface
  3. Now, simply email the file to the Teladoc Health team.
P/N: PL016219.A