gpg

Created Saturday 23/02/2008

GnuPG is the GNU implementation of PGP (Pretty Good Privacy). This document describes using gpg to manage signatures and both public and private keys. GnuPG stores signatures and keys in a keychain, which are typically kept in the directory ~/.gnupg. In this document the GnuPG command prompt is indicated by Command>

Note 1: The GnuPG command prompt is indicated by Command> Note 2: Preferences are maintained in the file ~/.gnupg/options

1. Keychain management

This is a quick guide and simple overview of keychain managment. The likely most common actions for keychains are listing keys (signatures, public keys and private keys), removing keys, editing private keys, verifying a gpg file (perhaps received in an email or similar), encrypting a file using a specific public key and of course decrypting a gpg file using your private key (where the file has previously been encrypted using your public key).

1.A. Examining keychain contents

The keychains, are kept in ~/.gnupg, with the public keys and signatures in pubring.gpg and the private keys in secring.gpg. The commands --list-keys, --list-secret-keys and --list-sigs do just what they say; List public keys in the public key ring, list private keys in the private key ring and list signatures in the public keyring. The following commands with example output illustrate this:

bash $ gpg --list-keys
bash $ gpg --list-secret-keys
bash $ gpg --list-sigs

1.B Key management

To remove or alter a key in either the the public or private keyrings use the --delete-key and --edit-key commands. Both edit and delete are options that require an argument, which is the Key ID, which can be either the key same, such as 'Foo' or the Key ID such as 0x364AD91E. Clearly only private keys can be edited and so use the --list-secret-keys (see #1.A) to determine the ID of the key to edit and then use the selected ID an a argument to the --edit-key command. The edit command starts a subshell, which in the following is indicated by Command> from within the GnuPG edit shell, attributes of the named key can be altered. Type help for a command list.

bash $ gpg --delete-key 'Foo'

bash $ gpg --edit-key 'Foo'
gpg (GnuPG) 1.4.7; Copyright (C) 2006 Free Software Foundation, Inc.
Command> help

1.B.I add image(s) to a key

Multiple images can be added to a private key. The image must be in JPEG format, see convert(1), part of ImageMagic and should be close to 240x288 pixels. Enter the edit mode, providing the private key id (hex id or string key ) as the argument:

Note: Remember to issue a save command to commit the changes. Typing quit will also ask if uncommitted changes should first be saved.

bash $ gpg --edit-key 0x765AB4D2 
Command> addphoto
Enter JPEG filename for photo ID: myphoto.jpg
Is this photo correct (y/N/q)? y

You need a passphrase to unlock the secret key for
user: "Foo Bar (GPG Key) <foo@bar.com>"
128-bit DSA key, ID 765AB4D2, created 2001-01-01

Enter passphrase: xxxxx
pub  128D/765AB4D2  created: 2001-01-01  expires: never       usage: SC  
                     trust: ultimate      validity: ultimate
sub  128g/8763AE2F  created: 2001-01-01  expires: never       usage: E   
[ultimate] (1). Foo Bar (GPG Key) <foo@bar.com>
[ultimate] (2)  Foo Bar
[ultimate] (3)  [jpeg image of size 8901]
[ unknown] (4)  [jpeg image of size 4567]
[ unknown] (5)  [jpeg image of size 1234]

Command> save

In this case, there are three photos in this particular private key. The showphoto command will open the default image viewer, successively, for each of the jpeg's in the key.

1.B.II Displaying images(s) in a key

Tip #1: Use list to display sub-components of a keys, then use uid to select individual image sub-components, followed by showphoto to display the images Tip #2: The image viewer used by GPG is specified by the photo-viewer preference, which can be set in the options file (in ~/.gnupg)

The showphoto command of gpg's edit mode will display the first image in the selected key. To display multiple images or a different image, use the uid sub-command to toggle the sub-component marker. The sub-component marker is indicated with the asterisk * next to the sub-component. The following example key contains 3 images and, in this edit session, images 1 and 3 set have their sub-component marker active. Issuing a showphoto command in this situation invokes the default image viewer twice, once for each of the selected images.

bash $ gpg --edit-key 0x765AB4D2 
Command> list

pub  128D/765AB4D2  created: 2001-01-01  expires: never       usage: SC  
                     trust: ultimate      validity: ultimate
sub  128g/8763AE2F  created: 2001-01-01  expires: never       usage: E   
[ultimate] (1). Foo Bar (GPG Key) <foo@bar.com>
[ultimate] (2)  Foo Bar
[ultimate] (3)  [jpeg image of size 8901]
[ unknown] (4)  [jpeg image of size 4567]
[ unknown] (5)  [jpeg image of size 1234]

Command> uid 3
Command> uid 5
Command> list

pub  128D/765AB4D2  created: 2001-01-01  expires: never       usage: SC  
                     trust: ultimate      validity: ultimate
sub  128g/8763AE2F  created: 2001-01-01  expires: never       usage: E   
[ultimate] (1). Foo Bar (GPG Key) <foo@bar.com>
[ultimate] (2)  Foo Bar
[ultimate] (3) *[jpeg image of size 8901]
[ unknown] (4)  [jpeg image of size 4567]
[ unknown] (5) *[jpeg image of size 1234]

Command> showphoto

1.B.III Removing a image from a key

Note: There is no specific remove image command. Use a combination of uid n (or just type n) followed by deluid to remove the image

There is now specific delete photo command in the gpg edit mode. Each image in the key is a subkey and can therefore be removed with the deluid command, in gpg edit mode. To start edit mode, invoke gpg's --edit-key option, prividing the private key ID (hex or string identifier). Use the list command to show the key content, followed by the uid command to select the sub-component and deluid to actually remove the photo. The following interaction removes the first and last images as shown in the key content for #1.B.I.

Tip: Enter the numbers of the images/subkeys to delete, one after the other, then use deluid to remove all of them at once

bash $ gpg --edit-key 0x765AB4D2 
Command> list

pub  128D/765AB4D2  created: 2001-01-01  expires: never       usage: SC  
                     trust: ultimate      validity: ultimate
sub  128g/8763AE2F  created: 2001-01-01  expires: never       usage: E   
[ultimate] (1). Foo Bar (GPG Key) <foo@bar.com>
[ultimate] (2)  Foo Bar
[ultimate] (3)  [jpeg image of size 8901]
[ unknown] (4)  [jpeg image of size 4567]
[ unknown] (5)  [jpeg image of size 1234]

Command> uid 3
Command> uid 5
Command> deluid
Really remove all selected user IDs? (y/N) y
Command> save

1.C Verification

The --verify command can be used to check the veracity of an encrypted using a detached ASCII armoured signature. In the following, the example, the file foo.asc contains the detached signature (ASCII Armoured) and the foo.bin is the encypted file.

bash $ gpg --verify foo.asc foo.bin

1.D. Encyption and Decryption

If the public keyring contains the Public Key the user for which the encrypted contents are for, then use the sign and encrypt command (-se). The target public key must be specified with the -r option, which requires the Public Key ID as an argument. Use the --list-keys command (see #1.A) to list the contents of the public keyring. In the following example, we encrypt a file foo.txt for user 'Foo <foo@bar.com>'. The resulting cypher text is written to the file foo.txt.gpg

bash $ gpg -se -r 'Foo <foo@bar.com' foo.txt

Decrypting a file that has been encrypted with your own public key is trivial and is done with the decrypt command (-d). The cleartext are written to stdout, so it is often desirable to redirect the output of the decrypt command. In the following example, the cyphertext in foo.txt.gpg is decrypted to stdout:

bash $ gpg -d foo.txt.gpg	

2. Write ASCII Armoured signature to a file

To dump the signature identified with the User ID 'Foo' (could also use the hex id, with or without a leading 0x):

bash $ (gpg --list-sigs 'Foo' && gpg --armor --export 'Foo') >> foo.sig

3. Keyservers

Keyservers provide a central repository for pgp keys. The keyservers share keys between them, so generally it's enough to query just the one. GnuPG can query and then import keys from a keyserver. Queries to keyservers are specified using a url and a variety of schemes are supported. The simplest is the hkp:// scheme, which is uses http as the underlying protocol. Other schemes include ldap:// which uses NAI LDAP and mailto:// for Graff Email Servers.

Tip: Protocol schemes are not case sensitive.

The server subkeys.pgp.net uses a round robbin algorithm to query a different keyserver with each search. Query for keys matching the user id of 'Foo':

bash $ gpg --keyserver "hkp://subkeys.pgp.net" --search-keys  'Foo'

Update the key with id "765AB4D2" from a keyserver:

bash $ gpg --keyserver "hkp://subkeys.pgp.net" --refresh-keys 765AB4D2

4. Preferences

The GnuPG global preferences are maintained in the ~/.gnupg directory in a file called options. The file format is key-name value, (most key names being hyphenated). Each global preference has a default value, which may or may not be in the default options file as a commented out entry. Examples of useful preferences are the characterset and the image viewer.

4.1. photo-viewer

Tip: specify photo-viewer "gthumb %i" to use gthumb(1)

The photo-viewer property sets the image viewer for photos. Provide the pathname of the application to use followed by arguments to the application, which should include the pathname of the image. The image pathname is made available by GnuPG based on the following variables:

• %i is expanded to a temporary file that contains the photo.
• %I is the same as %i, but the file isn't deleted afterwards by GnuPG.
• %k is expanded to the key ID of the key.
• %K is expanded to the long OpenPGP key ID of the key.
• %t is expanded to the extension of the image (e.g. "jpg").
• %T is expanded to the MIME type of the image (e.g. "image/jpeg").
• %f is expanded to the fingerprint of the key.
• %% is %, of course.

If %i or %I are not present, then the photo is supplied to the viewer on standard input. If your platform supports it, standard input is the best way to do this as it avoids the time and effort in generating and then cleaning up a secure temp file. The default program is:

photo-viewer xloadimage -fork -quiet -title 'KeyID 0x%k' stdin

4.2 Passphrase agent

The GnuPG can communicate with an ssh-agent, if running. Specify the use-agent option, which looks for the agent pid using the GPG_AGENT_INFO variable. If this is not available, then the command line gpg option --can be used, which specifies the path to the ssh-agent program, the pid of the running instance of the agent and a key offset. E.g.,

bash $ gpg --gpg-agent-info=/usr/bin/ssh-agent:17570:1 --edit-key 765AB4D2

Error: Problems exist with old agent protocol (even with --gpg-agent-info). Use new Assuan protocol, from newpg (ftp.gnupg.org) package.

Stuart Moorfoot © 23 February 2008 foo@bund.com.au