Using v02enc

The v02enc tool offers a pleasantly straightforward experience. It only requires PHP 8 as a dependency. To get started, grab v02enc from Niehage's GitHub sources by running git clone against the project's URL. The installation process is a little tricky, because v02enc essentially consists of three PHP files, which you have to copy to a local path on disk and make executable using chmod +x (/usr/local/bin/ is a good choice for the default path).

As soon as v02enc is installed and executable, the first step is to create a random passphrase (Listing 1, line 1), which acts as a secret key for v02enc. The specified path corresponds to the path where v02enc searches for the key to be used by default. If you do not want the key to be stored in the clear on disk, you can safeguard it separately using a password. The v02enc source code contains detailed instructions on how to do this. In the next step, the second command from Listing 1 (lines 2-4) creates an encrypted version of the example.txt file in example.txt.v02enc, using the secret key it just created.

01 $ head -c 32 /dev/random > ~/.v02enc
02 $ v02enc --encrypt --key ~/.v02enc \
03          --input ./example.txt \
04          --output ./example.txt.v02enc
05 $ v02enc --update ./new-text.txt --key ~/.v02enc \
06          --input ./example.txt.v02enc \
07          --output ./example.txt.v02enc.tmp && \
08   mv ./example.txt.v02enc.tmp ./example.txt.v02enc

If you want to encrypt a file with multiple keys for multiple recipients, you need to specify the -k option multiple times (Figure 4). While this may seem strange at first, it makes sense if you assume that users protect their keys with a password. This makes it possible to maintain the various keys in a central directory and use, say, Ansible to roll them out to the users' personal directories on all relevant systems.

Figure 4: v02enc encrypts a file symmetrically for multiple recipients, making it far easier to use on target systems and a more powerful alternative to tools such as Ansible Vault.

If a user then decrypts a file that v02enc previously encrypted for the user's key, the tool automatically accesses the matching key in the user's personal folder. Updating existing files is similarly straightforward. The last command from Listing 1 (starting in line 5) is all you need to do this.

v02enc first creates a new encrypted file with new content and then uses this file in the next step to overwrite the old file. Overall, this isn't that convenient, but Niehage has come up with a simplification, at least for Vim users: If your key is in the default location on disk and you have installed both v02enc and vim02enc, the vim02enc example.txt.v02enc command opens the file directly in Vim and saves it again in an encrypted format when you are done.

Sensible Integration

While v02enc is explicitly intended for use in source code directories managed by Git, Git does not recognize v02enc by default. As a result, the output of git Duff, for example, would only display binary code if an encrypted file in the local directory changes. To address this issue, Niehage has developed a small utility, v02gitdiff, which requires having colordiff installed.

To use v02gitdiff, just add the two-liner from Listing 2 to your $HOME/.gitconfig file. When you now type git diff, Git no longer calls the classic diff, but instead calls v02gitdiff as a wrapper around colordiff. It dynamically decrypts the encrypted files and can display the differences in them accordingly. Anyone who regularly uses v02enc in combination with Git will find this useful.

[diff]
external = /PATH/TO/v02gitdiff

If you use Mercurial instead for your source code, you can use the v02hgdiff tool found in the encryption tool's source code. In this case, though, the changes to the local configuration file $HOME/.hgrc are a little more extensive, as shown in Listing 3. Again, colordiff must be installed for the combination of v02enc and Mercurial to work.

[extensions]
extdiff =
[extdiff]
cmd.v02hgdiff = /PATH/TO/v02hgdiff
[alias]
diff = !for FILE in $(hg status -n); do hg v02hgdiff "$(hg root)/${FILE}" -o "$(hg root)"; done

macOS Keychain

Because many admins and developers who work on Linux systems also work with Macs, v02enc also supports Apple's system-wide password manager, Keychain.

You can use Listing 4 to create a password named lmtest in Keychain at the command line (Figure 5). If you then call v02enc, you can pass the name lmtest into to v02enc as an argument using the -c parameter. Doing so retrieves the matching password from Keychain on macOS and uses it as the key for encryption; the security features envisaged for Keychain in macOS apply here.

$ security add-generic-password -a "$(whoami)" -s "lmtest" -T "" -U \
  -w "$(echo -n "Password: " > &2 && read -s password && \
        echo $password | xxd -p | tr -d "\n")"

Figure 5: Useful for macOS users, v02enc includes Keychain integration to make password management easier and more secure.

To display the password, you need to authenticate by entering your system password or using Touch ID. Anyone who works with macOS and wants to use v02enc will find this considerably easier. If you want to take this to the extreme, you can define an alias in the shell pointing from v02enc to v02enc -c NAME, which ensures that every call to v02enc automatically transfers the key stored in Keychain.