GPG Encryption Guide

Background

In order to authenticate against Blackfynn’s PPMI 2.0 API we require our partners use the OAuth 2.0 client credentials grant to generate a temporary access token with which to make requests.

The client credentials grant requires the use of a client_id  and client_secret . 

Blackfynn generates a client with the above credentials, which uniquely identifies each of our partners. This information is private and should be stored securely by our partners. Please see our guide to Safely Storing Credentials for securely storing and managing your client credentials.

In order to securely transmit these credentials to our partners we rely on the cryptographic encryption software GPG. Below is a step-by-step guide for our partners to help us facilitate this transfer.

Instructions

The below instructions are specific to a Unix or MacOS X environment. If you are using Windows we recommend using the GUI GPG application Gpg4win. The instruction text is hopefully generic enough to apply to a GUI program but if not please reach out to us.

Install GPG

• On macOS X we recommend using the package manager Homebrew. Once you have homebrew installed you can run: brew install gnupg 

• For other *nix operating systems we recommend usings the systems default package manager CLI tool to install GPG. For example, on Debian-based operating system such as Ubuntu you can use the package manager apt to run: apt-get install gnupg2 

Create a GPG Key Pair

Once you have GPG installed you’ll need to create a GPG key pair (public and private key).

1. Create a new primary key pair: gpg --full-generate-key 
2. Select (1) RSA and RSA (default) for the type of key.
3. Enter 4096  for the key size.
4. Enter 1m  (one month) for the expiration of your key pair.
5. Enter a name, email address, and comment to associate with the key pair.
6. Enter a passphrase of your choosing. Ensure the passphrase is strong by including multiple-case alphanumeric characters.
7. If you see the following message, the system requires more entropy to generate a key pair. You can accomplish this by typing randomly into your keyboard:We need to generate a lot of random bytes. It is a good idea to perform some other action (type on the keyboard, move the mouse, utilize the disks) during the prime generation; this gives the random number generator a better chance to gain enough entropy.

You can verify the key pair has been added to your keyring using: gpg --list-keys 

Export your GPG Public Key

Once you’ve created a GPG key pair you’ll need to export its public key and send it to Blackfynn.

1. Export the public key. Replace user@example.com  with the email address associated with the key’s owner’s email address. Replace public-key.gpg with whatever name you desire for the output file. This will save the output file to your current working directory.

gpg --armor --output public-key.gpg --export user@example.com
    
2. Send public-key.gpg  to Blackfynn. This file will be located in your current working directory. As its name suggests, this key is public and can be shared without secrecy. Feel free to send it as an attachment in an email to directly to Blackfynn. For additional security please send your key’s fingerprint. To do so, send the full output of the below command in the above email, replacing user@example.com  with the email you used to generate the GPG key above:

gpg --fingerprint user@example.com 

Decrypt your Client Credentials

Once you’ve sent Blackfynn your GPG public key we’ll send you a downloadable link to a GPG encrypted file with your client credentials. You’ll want to decrypt this file using the instructions below and securely store these credentials. See our guide for Safely Storing Credentials for best practices relevant to securely storing your credentials.

1. Download the file at the link sent to you from Blackfynn. The file should be named example-credentials.gpg  where example should be your company’s name.
2. Decrypt your client credentials. Replace example-credentials.json  with the name of the output you would like your decrypted client credentials saved to .gpg \  --output example-credentials.json \  --decrypt /path/to/example-credentials.gpg 
3. The contents of the decrypted client credentials file should be a JSON document containing two keys, client_id  and client_secret , each containing respective values.

cat example-credentials.json
{
  "client_id": "...",
  "client_secret": "..."
}