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)
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
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:
This command will ask for your name and address.
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: firstname.lastname@example.org You selected this USER-ID: "Alice User <email@example.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:
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.
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 <firstname.lastname@example.org> 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:
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 <email@example.com> 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.
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:
The suite of blackbox_ commands is your interface to the process of encryption and decryption. The commands you are most likely to use are: