BCDA File Decryption: An Example

Gathering the tools

To complete this decryption example, you will need:

Exploring the API with Swagger

You will be interacting with the BCDA API in your browser using Swagger. This will enable you to authenticate, make requests, and everything else the API provides.

  • Open your browser and navigate to:

https://sandbox.bcda.cms.gov/api/v1/swagger

Screenshot of swagger

Getting a token

Use your credentials from the previous step to get an access token in this step.

  • Click the Authorize button
  • In the Basic authorization section
    • Enter your Client ID in the Username box
    • Enter your Client Secret in the Password box
    • Click Authorize

Available authorizations

  • Click the /auth/token link

Token endpoint

  • Click Try it out, then Execute

Getting a token

If you’re successful, your token will appear as pictured in the response body. You can now use this token to get full access to the API.

  • Copy your new token to your clipboard
  • Click the Authorize button
  • In the bearer_token box:
    • Type “Bearer”
    • Add a space
    • Paste your token (Ctrl + V)

Authorization dialog

  • Click Authorize, then Close

API menu

Requesting a file

There are three types of encrypted files that can be downloaded: Coverage, Explanation of Benefit (EoB), and Patient. The example below id is for downloading the EoB.

  • Click the /api/v1/ExplanationOfBenefit/$export link

Notice that there’s quite a bit of documentation here, from the parameter types to possible kinds of server responses.

Starting Explanation of Benefits job

  • Click Try it out, then Execute

Explanation of Benefits response

If you’d like to repeat this from the command line or implement this API call in code, look in the Curl section for the request you just made. Not far below that under Server response you can see the response: an HTTP 202 success giving a link in the content-location header for status information on our EoB job.

  • Note the job ID number at the end of this link.
  • Open the job status section in Swagger (click /api/v1/jobs/{jobID})

Requesting job status

  • Type the job ID you received
  • Click Execute

Job status response

  1. Depending on the size of the file, the job may take some time. If the job is not yet complete, status information will be shown. Simply wait a few seconds and click execute again until the job completes. You will then get a result for a completed job as shown below. You can download the file from the URL provided.
  2. Your token will expire after a few minutes, and you may need to get another from /auth/token if it expires before you are finished interacting with the API.
  3. Take special note of the new KeyMap section of the response. To decrypt the file, you will need the filename (the first part of the keymap) and the symmetric key (the second part of the keymap), as shown above. There are no spaces in either one.
  4. Sometimes one or more data points are unavailable. When this happens, the error section will contain a separate filename and symmetric key with a list of the patients involved.
  • Copy these values from the KeyMap (filename and symmetric key) for later.

Your last API task is to download the encrypted file.

  • Open the data file section in Swagger (click /api/v1/jobs/{jobID}/{filename})
  • Paste the job ID and filename into the appropriate boxes
  • Click Execute

Get data file (Swagger)

  • Click the Download file link that appeared in the response section. Note that a large sample file may take a while to download.

Download file

Decrypting a file

After downloading the file, move to the command line. Navigate to the directory you saved decrypt.py and requirements.txt from the Gathering the tools section.

Directory with decryption tool

Verify that Python is running properly.

  • Run decrypt.py with the help argument (python decrypt.py -h). You should get the response shown below.

Decrypt.py syntax

  • Rename the downloaded file with the filename you saved earlier. This is extremely important as the file name is used as part of the file decryption process and using a different file name will cause decryption to fail.

Rename downloaded file

You are now ready to decrypt the file! Your sample decryption tool will print the decrypted contents to the console, so you can send the output to a file. Make sure to use the following syntax, with the entire command on the same line:

python decrypt.py 
    --pk   [location_of_private_key] 
    --file [location_of_encrypted_file] 
    --key  [symmetric_key_value]
    > filename.txt

Running decrypt.py

Take a look at the result. If you do not see unencrypted NDJSON (two example lines shown below), then skip ahead to the troubleshooting section.

Parsing decrypted file contents

Reading further

Troubleshooting

Authentication problems in Swagger

  • Did you use the credentials (Client ID and Client Secret) from the user guide with Basic authorization?
  • After entering your credentials, did you get an access token from /auth/token?
  • Did you put your access token in the bearer_token section of the authorization dialog?
  • Has your token expired? Use your credentials to get a new token from /auth/token.
  • Is it possible you clicked on Logout? Is the lock on the Authorize icon not closed? Click it again, and after pasting your token in the bearer_token box, make sure to click the Authorize button.
  • Are there any spaces or newlines in your token? Remove them and paste it as a single line.
  • Do you get an HTTP 504 GATEWAY_TIMEOUT error? Make sure to add the word “Bearer” (and a space) before the token, as demonstrated in the exploring the API section.

Python not installed

Encryption issues

  • The best practice would be to keep your private key in a separate, secured directory. While you’re testing the encryption feature for the first time, however, you may find it useful to have all the files in the same directory.
  • Have you saved the encrypted file with exactly the filename provided by the API? If not, rename it and try again.
  • Is the symmetric key value provided with no spaces or newlines? Double-check that no characters are missing from the beginning or end of the key.

Have questions?

The BCDA Google Group is the best place to get your questions answered by the BCDA team. In this community you can sign up for feedback session opportunities, get answers to your questions, share your feedback and ideas, and get updates on the project.

Back to top