Un naufragio personal: GPG Cheat Sheet

This is a very basic guide to use GPG (GNU Privacy Guard), the free software version of the classic PGP (Pretty Good Privacy) tool for signing, encrypting and verifying information. It can be handy if your Email client does not directly support it. This guide explicitly does not cover creating and maintaining keys and keyrings.

For this tutorial we have the following two individuals: Angel, with email address angel@triptico.com and Johannes, with email address johannes@comam.es. They both have GPG installed on their systems and have valid keys. Additionally, each user have another one's public key installed in ther keyrings.

Also, there is a two line message they want to share:

I am the voice of Mother Earth,
from whence all horrors have their birth.

Signing

Angel wants to send the creepy message to Johannes. Also, he wants to be sure that Johannes can check that he is who really sent the message. So he runs the following command in its terminal:

gpg -s --clearsign

GPG politely says the following:

You need a passphrase to unlock the secret key for
user: "Angel angel@triptico.com"
1024-bit DSA key, ID 70C9B100, created 2012-11-07

Enter passphrase:

This operation implies the use of Angel's private key, that is password-protected inside his keyring. If the password is correctly entered, GPG waits silently for text from its standard input. Angel pastes the message and GPG dumps the following:

This piece of text (including the BEGIN... and END... lines) can be pasted to the email body of a message sent to Johannes. Please note that you can write whatever you want outside the PGP boundaries and the message will still be considered valid when the signature is checked. So this can be the full email body:

Hey, Johannes. This is what was said:

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

I am the voice of Mother Earth,
from whence all horrors have their birth.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1

iEYEARECAAYFAlvrxGIACgkQ5CXHVHDJsQBOagCfQAFQoZyFfegGZUa8oWwn/srg
1RwAoMFcDABbLpqaqpwIVqv5U4pYvdVb
=q64b
-----END PGP SIGNATURE-----

Best regards, Angel

Of course, the surrounding text must not be considered signed text. This is a common mistake.

Checking signatures

Johannes receives the message in his Inbox. He's absolutely unsure if it's really Angel who quoted the eerie text; so, he just calls GPG with no arguments:

gpg

And gets the following reply:

gpg: Go ahead and type your message ...

Johannes selects and copies the full message body and pastes it into GPG's standard input. Then the program replies:

I am the voice of Mother Earth,
from whence all horrors have their birth.
gpg: Signature made Tue Nov 13 15:02:38 2018 CET using DSA key ID 70C9B100
gpg: Good signature from "Angel angel@triptico.com"

So Johannes can be confident than Angel really sent the two-line message (the rest of the text is considered irrelevant and is ignored). GPG does not need any password to check the signature: all it needs is Angel's public key that it's stored in Johannes' keyring but not protected in any way (Angel's public key can be shown in his web home page or printed and glued on the street lamps of the town if he wants, as it's not sensible information).

Please note that, though GPG apparently mixed the message and its own information, the first one is sent to the standard output stream and the second one to its standard error/status stream; Johannes only sees them together because of the way his terminal shows these channels by default.

Tampering detection

Let's suppose some evil being tries to feed its dirty lies to Johannes, trying to take advantage of the confidence between both and impersonating as Angel. So it somehow obtains a copy of the message and does some subtle changes:

Hey, Johannes. This is what was said:

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

I am the voice of Mother Moon,
from whence all horrors have their doom.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1

iEYEARECAAYFAlvrxGIACgkQ5CXHVHDJsQBOagCfQAFQoZyFfegGZUa8oWwn/srg
1RwAoMFcDABbLpqaqpwIVqv5U4pYvdVb
=q64b
-----END PGP SIGNATURE-----

Best regards, Angel

Johannes repeats the previous operation but gets the following output

instead:

I am the voice of Mother Moon,
from whence all horrors have their doom.
gpg: Signature made Tue Nov 13 15:02:38 2018 CET using DSA key ID 70C9B100
gpg: BAD signature from "Angel angel@triptico.com"

That BAD signature... thing should trigger all kind of alarms.

The GPG tool also returns different output values for valid and invalid operations that can be useful in scripts and programs. If you are not a programmer nor a sysadmin, you can ignore this.

Encrypting

But Angel may occasionally consider that proving his authorship is not enough; he wants the message to be absolutely hidden to anyone but Johannes. So he opts for PGP/GPG encryption, invoking the command

gpg -e -a -r johannes@comam.es

and pasting the two-lines message into GPG's standard input. GPG barfs the following wall of text:

Given that GPG has everything it needs to encrypt a message to Johannes (i.e. his public key), no password nor any more information is requested.

Note that, when the message is encrypted, Angel has no way of decrypting it because he does not have Johannes' private key. There is no other way of decrypting this message than using that key.

As with signing, any text can be written surrounding the PGP boundaries. Also, it should not be trusted, as it's not really part of the message.

Decrypting

Johannes receives the block of garbage and proceeds the same as with the signed message:

gpg

But like every time a private key is involved, GPG asks for the password to the Johannes' keyring:

You need a passphrase to unlock the secret key for
user: "Johannes johannes@comam.es"
4096-bit ELG-E key, ID A31C97D9, created 2012-11-07 (main key ID 70C9B100)

Enter passphrase:

If it's entered correctly, GPG waits for text from its standard input. Johannes copies the full message into it and GPG dumps the omen from Mother Earth with some additional information:

gpg: encrypted with 4096-bit ELG-E key, ID A31C97D9, created 2012-11-07
     "Johannes johannes@comam.es"
I am the voice of Mother Earth,
from whence all horrors have their birth.

If the encrypted message is garbled someway, GPG will complain about the data block integrity:

gpg: CRC error; C73B95 - 357B2A

Encrypting and signing

For complete paranoia, a message can be encrypted AND signed. This is how it's done from Angel's view:

gpg -es -a -r johannes@comam.es

As it needs Angel's private key for signing, the passphrase for his keyring is requested. After pasting the two-line message into GPG's standard input, The response is another scary block of garbage:

The difference is that, when Johannes tries to check the message as he usually do:

gpg

The following is shown:

You need a passphrase to unlock the secret key for
user: "Johannes johannes@comam.es"
4096-bit ELG-E key, ID A31C97D9, created 2012-11-07 (main key ID 70C9B100)

Enter passphrase:

This should be expected, as it's a message for Johannes' eyes only. The output is a bit different, though:

gpg: encrypted with 4096-bit ELG-E key, ID A31C97D9, created 2012-11-07
     "Johannes johannes@comam.es"
I am the voice of Mother Earth,
from whence all horrors have their birth.
gpg: Signature made Tue Nov 13 16:03:20 2018 CET using DSA key ID 70C9B100
gpg: Good signature from "Angel <angel@triptico.com>"

GPG dumps information about the key the message was encrypted for, the message itself and the results of the validation test.

Signing binary files

Sometimes Angel may want to sign a binary file (a zip package, an image, etc.), for the purpose of helping people know that the file he has and the one they have has the same content. But adding PGP/GPG crap to this kind of files cannot be done because it corrupts them; so, you have to use a detached signature. Suppose you have the file

abraham_lincoln_nude.jpg

Then you can sign it by executing

gpg -ab abraham_lincoln_nude.jpg

A familiar prompt from GPG will be shown:

You need a passphrase to unlock the secret key for
user: "Angel angel@triptico.com"
1024-bit DSA key, ID 70C9B100, created 2012-11-07

Enter passphrase:

After a successful password GPG creates a file with the same name as the signed one, but with the .asc extension appended, and that looks like:

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1

iEYEABECAAYFAlvr2GAACgkQ5CXHVHDJsQCeagCfTn72ZUBeVlWwTMvTMcGIbZsL
9q4An0ZDXwAaMb5cyHUsybXoXZ/yjw8U
=R3uI
-----END PGP SIGNATURE-----

Both the file and the signature can now be made available to others.

Validating signed binary files

Johannes can validate that the binary file and Angel's signature on it match by calling

gpg abraham_lincoln_nude.jpg.asc

Note that both the file and the signature must be on the same folder. GPG shall return the following:

gpg: assuming signed data in `abraham_lincoln_nude.jpg'
gpg: Signature made Wed Nov 14 09:10:08 2018 CET using DSA key ID 70C9B100
gpg: Good signature from "Angel angel@triptico.com"

Summary

For signing text (will ask for sender's passphrase):

gpg -s --clearsign < msg.txt > msg.signed.txt

For checking a signed text (no passphrase needed):

gpg < msg.signed.txt

For encrypting text (no passphrase needed):

gpg -e -a -r user@destination < msg.txt > msg.encrypted.txt

For decrypting an encrypted text (will ask for receiver's passphrase):

gpg < msg.encrypted.txt

For encrypting and signing text (will ask for sender's passphrase):

gpg -e -a -r user@destination < msg.txt > msg.both.txt

For decrypting and checking text (will ask for receiver's passphrase):

gpg < msg.both.txt

For signing binary files (will ask for sender's passphrase):

gpg -ab binary_file

For checking signed binary files (no passphrase needed):

gpg binary_file.asc

End notes

Harry can sleep peacefully because he always encrypts and signs his email messages.

Though the examples here are given using GPG version 1, you should really use version 2 (the executable is called gpg2 in those systems that deploy both versions). I've used the older version because one of the features of version 2 is that it includes an agent that asks for passwords in GUI dialogs (if a GUI is available) and retains them for reasonable periods of time. This is of course convenient, but it may make less clear the cases where a passphrase to the keyring is needed.

If you found this post useful, you may buy Ángel a coffee.