The f5-ansible repository contains sensitive information and needs to be secure.
This sensitive nformation includes, but is not limited to:
To prevent exposing this information in plain text, F5 uses a series of GPG encrypted files.
The remainder of this document explains how this system works.
Many tools help prevent the storing of secret information in an otherwise public place. These include, but are not limited to:
The tool that F5 uses is blackbox, primarily because:
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: email@example.com You selected this USER-ID: "Alice User <firstname.lastname@example.org>" 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.
A practice referred to as Diceware allows you to choose a passphrase that is sufficiently difficult to computationally discover.
You can read about Diceware in detail here:
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:
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 <email@example.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:
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 <firstname.lastname@example.org> 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.
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 we encrypt anything that is “F5 specific”. This is kind of vague though, so here are some examples.
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: