Securing sensitive information¶

Create a key¶

Start by creating a set of GPG keys to use for encryption and decryption of secrets.

Use the gpg command to create a key. For example:

gpg --gen-key

This command will ask for your name and address.

For example:

root@9f1cc7b78557:~# gpg --gen-key
gpg (GnuPG) 2.1.20; Copyright (C) 2017 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

GnuPG needs to construct a user ID to identify your key.

Real name: Alice User
Email address: a.user@organization.com
You selected this USER-ID:
    "Alice User <a.user@organization.com>"

Change (N)ame, (E)mail, or (O)kay/(Q)uit?

To proceed, answer O (the letter, not the number) and the command will ask you for a passphrase in a separate window.

6──────────────────────────────────────────────────────^@
< Please enter the passphrase to                       │
< protect your new key                                 │
<                                                      │
< Passphrase: ________________________________________ │
<                                                      │
<       <OK>                              <Cancel>     │
^@─────────────────────────────────────────────────────5

If you do nothing else correctly for this procedure, you must absolutely get this step correct.

Your passphrase decrypts and encrypts sensitive data in the f5-ansible repository. If your passphrase is compromised, then the information contained within the gpg-encrypted files is compromised.

Now, because you include these gpg files in git, the compromised versions are accessible even if you rotate the keys.

It is your job to choose a passphrase (not just pass**word**) that is sufficiently long to hedge the risk of having it discovered computationally.

Create a passphrase¶

A practice referred to as Diceware allows you to choose a passphrase that is sufficiently difficult to computationally discover.

From the Diceware website, it is described as…

...a method for picking passphrases that uses dice to select words at random from a special list called the Diceware Word List.
Each word in the list is preceded by a five digit number. All the digits are between one and six, allowing you to use the outcomes
of five dice rolls to select a word from the list.

Here is a short excerpt from the Diceware word list:

  16655 clause
  16656 claw
  16661 clay
  16662 clean
  16663 clear
  16664 cleat
  16665 cleft
  16666 clerk
  21111 cliche
  21112 click
  21113 cliff
  21114 climb
  21115 clime
  21116 cling
  21121 clink
  21122 clint
  21123 clio
  21124 clip
  21125 clive
  21126 cloak
  21131 clock

The complete list contains 7776 short words, abbreviations and easy-to-remember character strings. The average length of each word
is about 4.2 characters. The biggest words are six characters long. The English list is based on a longer word list posted to the
Internet news group sci.crypt by Peter Kwangjun Suk. An alternative list, edited by Alan Beale, contains fewer Americanisms and
obscure words. And there are lists for several other languages. You can also download the Diceware word list in PDF format or in
PostScript format.

The idea is that you toss a dice and record the number. The numbers correspond to words in a list of words.

Your passphrase should be at least six words and a symbol, in any order.

If you do not have a pair of dice to roll, the next best option is to use an online service that rolls digitally or generates word lists on the fly. For example:

• https://www.rempe.us/diceware/

Complete your key¶

After you choose a passphrase, enter it in the aforementioned box. Press Enter and re-enter the passphrase.

6──────────────────────────────────────────────────────^@
< Please re-enter this passphrase                      │
<                                                      │
< Passphrase: ________________________________________ │
<                                                      │
<       <OK>                              <Cancel>     │
^@─────────────────────────────────────────────────────5

Pressing Enter after typing the passphrase a second time will generate the necessary public and private keys for you, as well as add them to your GPG keychain locally on disk.

For example:

gpg: key 5FE19AB05871BDA3 marked as ultimately trusted
gpg: revocation certificate stored as '/gpg//openpgp-revocs.d/6CA2078812CBB7F6112BDADF5FE19AB05871BDA3.rev'
public and secret key created and signed.

pub   rsa2048 2017-09-26 [SC] [expires: 2019-09-26]
      6CA2078812CBB7F6112BDADF5FE19AB05871BDA3
      6CA2078812CBB7F6112BDADF5FE19AB05871BDA3
uid                      Alice User <a.user@organization.com>
sub   rsa2048 2017-09-26 [E] [expires: 2019-09-26]

root@9f1cc7b78557:~#

You can verify that your keys exist in your keyring with the following command:

gpg --list-keys

If you were successful, you will see your key in the list.

pub   2048R/5871BDA3 2017-09-26 [expires: 2019-09-26]
uid                  Alice User <a.user@organization.com>
sub   2048R/0B29438A 2017-09-26 [expires: 2019-09-26]

Include your key in the test environment¶

After you generate your keys, you can include them in the Docker development containers that come with f5-ansible.

In the devtools/docker-compose.yaml file in this repository, a configuration section instructs docker-compose to create a path in your container at runtime. This path maps the .gnupg directory in your home directory to the /gpg directory in the container.

- type: bind
  source: ~/.gnupg
  target: /gpg

To change the local file system location where the GPG keys are, change it in this configuration.

Encrypt files¶

Determining what you should and should not encrypt is the first step in this process.

Generally speaking, F5 encrypts anything that is “F5-specific”. Some examples are:

• Websites that are internal to F5
• License keys used for integration tests
• System configuration that is irrelevant to the public (insofar as it would not help them in any way to have)

For all of those, and more, instances, encrypt.

Adding new files to the encryption process starts with the following command:

blackbox_register_new_file path/to/file.ext