Securing sensitive information

The f5-ansible repository contains sensitive information and needs to be secure.

This sensitive information includes, but is not limited to:

  • Product keys
  • Internal URLs
  • System configurations not relevant to the general public

To prevent exposing this information in plain text, F5 uses a series of GPG encrypted files.

Tools used to secure information

Many tools help prevent the storage of secret information in an otherwise public place. These include, but are not limited to:

  • blackbox (from StackExchange)
  • git-crypt
  • git-secret
  • Keyringer
  • Pass
  • Transcrypt

The tool that F5 uses is blackbox, primarily because:

  • It works in Docker containers
  • It has many stars and forks
  • It is just shell wrappers around GPG
  • It automatically ignores registered files
  • StackExchange

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:
You selected this USER-ID:
    "Alice User <>"

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.

< Please enter the passphrase to                       │
< protect your new key                                 │
<                                                      │
< Passphrase: ________________________________________ │
<                                                      │
<       <OK>                              <Cancel>     │

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:

Complete your key

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

< Please re-enter this passphrase                      │
<                                                      │
< Passphrase: ________________________________________ │
<                                                      │
<       <OK>                              <Cancel>     │

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]
uid                      Alice User <>
sub   rsa2048 2017-09-26 [E] [expires: 2019-09-26]


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 <>
sub   2048R/0B29438A 2017-09-26 [expires: 2019-09-26]


By default, your key has an expiration date two years in the future. You must renew your key before it expires. Instructions can be found here.

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


The suite of blackbox_ commands is your interface to the process of encryption and decryption. The commands you are most likely to use are:

  • blackbox_register_new_file
  • blackbox_decrypt_all_files
  • blackbox_deregister_file
  • blackbox_edit_start
  • blackbox_edit_end
  • blackbox_list_files