Edit a GPG-Encrypted File Safely with vigpg

You need to fix one line in a GPG-encrypted password file without ever writing its plaintext to disk, and vigpg is built for exactly that. This guide has you edit one encrypted file, verify that an unchanged file is not rewritten, and confirm what happens when you save a change. The command is a small wrapper around your editor and GPG, so the useful safety boundary is understanding the wrapper's defaults before you use it on sensitive data.

Allow about fifteen minutes for a first run. You need a shell, the byobu package's vigpg command, GPG, a working sensible-editor, and access to the key that will decrypt the file. The examples use byobu 6.11-0ubuntu1.1 and the installed vigpg from /usr/bin/vigpg.

Security boundary: Vigpg places cleartext in a temporary file under /dev/shm while you edit it. The installed script removes that temporary file on exit, but it explicitly cannot make the file non-swappable with mlock(2). Do not treat this workflow as protection against a hostile or already-compromised machine.

1. Check the installed command and prerequisites

Start with read-only checks. These do not need elevated privileges:

$ command -v vigpg
/usr/bin/vigpg
$ dpkg-query -W -f='${Package} ${Version}\n' byobu
byobu 6.11-0ubuntu1.1
$ command -v gpg sensible-editor run-one-until-success
/usr/bin/gpg
/usr/bin/sensible-editor
/usr/bin/run-one-until-success

The last command is part of the installed wrapper's re-encryption path. If any prerequisite is missing, stop and fix the package or editor setup through your normal system administration process. Do not begin with sudo vigpg: running the editor as root can create root-owned files and exposes your cleartext to a privileged process.

Checkpoint: confirm which editor sensible-editor will choose for your account. The exact output depends on your configured editor:

$ sensible-editor --version
...

If that option is not supported by the selected editor, inspect your VISUAL, EDITOR and desktop environment settings instead. The important point is that vigpg calls sensible-editor; it does not accept an editor option of its own.

2. Prepare an encrypted file you can identify

Use a path whose contents and permissions you understand. The documented form is a single file argument:

$ ls -l /path/to/passwords.txt.gpg
$ gpg --list-packets /path/to/passwords.txt.gpg

gpg --list-packets inspects packet structure without displaying the decrypted text. It is optional, and its output varies by GPG version. The filename ending in .gpg is only a naming convention: vigpg passes the path to GPG and does not infer a recipient from the suffix.

Before opening the editor, make a separate backup if the encrypted file matters:

$ cp --preserve=all /path/to/passwords.txt.gpg /path/to/passwords.txt.gpg.before-vigpg

This backup is encrypted data, but it is still sensitive. Keep it in a protected directory and remove it deliberately after you have verified the new file. Do not overwrite the only copy while testing.

3. Open the file without changing it

Run vigpg with the encrypted path:

$ vigpg /path/to/passwords.txt.gpg

GPG decrypts the file into the temporary workspace, then sensible-editor opens that cleartext. Read or inspect the contents, then exit the editor without saving. On the installed version, vigpg compares a SHA-512 checksum from before and after the editing session.

Expected result:

The encrypted file was not modified [/path/to/passwords.txt.gpg]

The message means the cleartext checksum did not change, so vigpg did not re-encrypt or overwrite the target. It does not mean the file was never decrypted: the editor session still had access to the temporary cleartext.

Checkpoint: If you expected to save a change but see this message, repeat the command and use the editor's explicit save action before quitting. A modified buffer that was discarded is indistinguishable from an untouched file to vigpg.

4. Save a controlled change

Run the same command again and make a small, reversible test edit. For example, add a line such as vigpg-test: remove me to a disposable encrypted file, save it, and quit:

$ vigpg /path/to/passwords.txt.gpg

Successfully encrypted update file [/path/to/passwords.txt.gpg]

When the checksum changes, vigpg asks GPG to sign and encrypt the temporary cleartext with --default-recipient-self, then copies the resulting ciphertext over the original argument. That default targets the current GPG user, not necessarily the person who originally created the file. Confirm that your account has a usable secret key before relying on this path.

Verify the result without printing cleartext:

$ gpg --list-packets /path/to/passwords.txt.gpg
$ stat --format='encrypted file: %n, %s bytes' /path/to/passwords.txt.gpg
encrypted file: /path/to/passwords.txt.gpg, ... bytes

Packet listings and ciphertext sizes are implementation details, so the exact lines and byte count vary. The useful checks are that GPG can inspect the file and the target still exists. To check the contents, run vigpg again, verify the test line, and remove it with the editor before saving a second time.

Recovery: If the saved test was wrong, edit it out and save. If the replacement was otherwise unacceptable, stop using the file and restore the encrypted backup only after checking its path:

$ cmp --silent /path/to/passwords.txt.gpg.before-vigpg /path/to/passwords.txt.gpg; printf 'comparison status: %s\n' "$?"
$ cp --preserve=all /path/to/passwords.txt.gpg.before-vigpg /path/to/passwords.txt.gpg

The second command is destructive to the current encrypted file. Run it only when the backup is the intended recovery point.

5. Create a new encrypted file deliberately

vigpg also accepts a path that does not exist. In that case it starts with an empty temporary file. Saving any content causes the wrapper to create an encrypted file for the current GPG user:

$ vigpg /path/to/new-notes.txt.gpg

Successfully encrypted update file [/path/to/new-notes.txt.gpg]
$ test -s /path/to/new-notes.txt.gpg && echo 'new ciphertext exists'
new ciphertext exists

Saving an empty buffer is different: the checksum remains the checksum of the empty temporary file, so vigpg reports that the encrypted file was not modified and does not create a useful target. Put in content before saving.

This creation behaviour is security-sensitive because the recipient is selected by --default-recipient-self. If another person or service must decrypt the file, do not assume vigpg's default is appropriate. Encrypt a copy with an explicit recipient using your normal GPG workflow, or configure and verify the GPG defaults before using vigpg. The manpage does not document a vigpg option for choosing a recipient.

6. Handle failures without losing the source

A decryption failure leaves the original encrypted file in place, but vigpg exits non-zero. Capture the status immediately:

$ vigpg /path/to/passwords.txt.gpg
gpg: decryption failed: No secret key
$ printf 'vigpg exit status: %s\n' "$?"
vigpg exit status: 1

The exact GPG diagnostic depends on the key, trust and file. Check that the correct secret key is available with gpg --list-secret-keys, and confirm the path. Do not delete the encrypted file to make the error go away.

If the editor cannot start or cannot exit successfully, vigpg reports an edit failure and does not publish a replacement. A GPG re-encryption failure follows the same pattern. Preserve the original and the backup, record the diagnostic, and fix the editor or key configuration before trying again.

Do not interrupt the process casually after saving. The wrapper traps common exit signals and attempts to shred its temporary cleartext and intermediate ciphertext, but interruption is not a guarantee that every copy of sensitive data has disappeared from memory, swap or editor recovery files. Check your editor's recovery and swap settings separately.

Done means