[[pacman|Install]] {{Pkg|gnupg}}, available in the [[official repositories]].

[[pacman|Install]] {{Pkg|gnupg}}, available in the [[official repositories]].

+

+

==Environment Variables==

+

* {{ic|$GNUPGHOME}} is used by {{ic|GnuPGP}} to point to the directory where all configuration files are stored. By default {{ic|$GNUPGHOME}} isn't set and your {{ic|$HOME}} is used instead, thus you will find a {{ic|~/.gnupg}} directory right after the install. You may change this default setting by putting this line in one of your regular [[Startup_files|startup files]]

+

export GNUPGHOME&#61;"/path/to/gnupg/directory"

+

{{Note| by default, the gnupg directory has a particular [[Permissions]] set to ''600''. Only the owner of the directory has permission to read and write (''r'',''w''). This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.}}

+

* {{ic|GPG_AGENT_INFO}} used to locate the pgp-agent. Consists of 3 colon delimited fields:

+

**1. path to Unix Domain Socket

+

**2. PID of gpg-agent

+

**3. protocol version set to 1

+

E.g : {{ic|GPG_AGENT_INFO&#61;/tmp/gpg-eFqmSC/S.gpg-agent:7795:1}}. When starting the gpg-agent, this variable is set to the correct value.

+

+

==Configuration file==

+

Default is {{ic|~/.gnupg/gpg.conf}}. If you want to change the default location, either run gpg this way {{ic|$ gpg --homedir ''path/to/file''}} or use {{ic|$GNUPGHOME}} variable.

+

+

Append in this file any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. You will find a skeleton file {{ic|usr/share/gnupg/gpg-conf.skel}}.

+

Following is a basic configuration file:

+

{{hc|~/.gnupg/gpg.conf|

+

default-key ''name'' # useful in case you manage several keys and want to set a default one

+

keyring ''file'' # will add ''file'' to the current list of keyrings

+

trustdb-name ''file'' # use ''file'' instead of the default trustdb

+

homedir ''dir'' # set the name of the gnupg home dir to ''dir'' instead of ~/.gnupg

If you want to set up default options for a multi-user system, the configuration file of defaults is expected in {{ic|/etc/skel/.gnupg/}}. With that in place the new user configuration can be created with

+

# addgnupghome user1 user2

+

which will add the respective {{ic|/home/userX/.gnupg/}} and copy the files from the skeleton directory to it.

You’ll have to answer a bunch of questions but generally, you can accept the defaults.

+

You will be asked several questions. In general, most users will want both a RSA (sign only) and a RSA (encrypt only) key. It is advised to use a keysize of 4096 bits (default is 2048).

While having an expiration date for subkeys isn't technically necessary, it is considered good practice. A period of a year is generally good enough for the average user. This way even if you lose access to your keyring, it will allow others to know that it is no longer valid.

While having an expiration date for subkeys isn't technically necessary, it is considered good practice. A period of a year is generally good enough for the average user. This way even if you lose access to your keyring, it will allow others to know that it is no longer valid.

−

* Set expiration date (repeat for both/all subkeys)

+

=== Manage your key ===

−

# gpg --edit-key 'Your Name'

+

* Running the {{ic|gpg --edit-key ''key ID''}} or {{ic|gpg --edit-key ''User_name_uid''}} command will present a menu which enables you to do most of your key management related tasks. Following is an example to set your expiration date:

−

# key [number]

+

−

# expire

+

$ gpg --edit-key ''User_name_uid''

−

# save

+

> key ''number''

+

> expire ''yyyy-mm-dd''

+

> save

+

> quit

+

+

Some useful commands:

+

> passwd # change the passphrase

+

> clean # compact any user ID that is no longer usable (e.g revoked or expired)

+

> revkey # revoke a key

+

> addkey # add a subkey to this key

* Generate an ASCII version of your public key (e.g. to distribute it by e-mail):

* Generate an ASCII version of your public key (e.g. to distribute it by e-mail):

−

# gpg --armor --output public.key --export 'Your Name'

+

$ gpg --armor --output public.key --export 'Your Name'

+

+

* Register your key with a public PGP key server, so that others can retrieve your key without having to contact you directly:

+

$ gpg --keyserver pgp.mit.edu --send-keys ''Key Id''

+

+

* Sign and encrypt for user Bob

+

$ gpg se -r Bob ''file''

−

* Register your key with a public PGP key server, so that others can retrieve your key without having to contact you directly.:

+

* make a clear text signature

−

# gpg --keyserver hkp://subkeys.pgp.net --send-keys ''Key Id''

+

$ gpg --clearsign ''file''

=== Rotating subkeys ===

=== Rotating subkeys ===

Line 36:

Line 88:

* Create new subkey (repeat for both signing and encrypting key)

* Create new subkey (repeat for both signing and encrypting key)

−

# gpg --edit-key 'Your Name'

+

$ gpg --edit-key 'Your Name'

−

# addkey

+

> addkey

−

And answer the following questions it asks.

+

And answer the following questions it asks (see previous section for suggested settings).

* Save changes

* Save changes

−

# save

+

> save

* Update it to a keyserver.

* Update it to a keyserver.

−

# gpg --keyserver hkp://subkeys.pgp.net --send-keys ''Key Id''

+

$ gpg --keyserver pgp.mit.edu --send-keys ''Key Id''

{{Note|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}

{{Note|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}

Line 52:

Line 104:

* Import a public key to your public key ring:

* Import a public key to your public key ring:

−

# gpg --import public.key

+

$ gpg --import public.key

* Import a private key to your secret key ring:

* Import a private key to your secret key ring:

−

# gpg --import private.key

+

$ gpg --import private.key

=== List keys ===

=== List keys ===

* Keys in your public key ring:

* Keys in your public key ring:

−

# gpg --list-keys

+

$ gpg --list-keys

* Keys in your secret key ring:

* Keys in your secret key ring:

−

# gpg --list-secret-keys

+

$ gpg --list-secret-keys

== Basic usage ==

== Basic usage ==

Line 69:

Line 121:

You can use gnupg to encrypt your sensitive documents, but only individual files at a time.

You can use gnupg to encrypt your sensitive documents, but only individual files at a time.

−

For example, to decrypt a file data, use:

+

For example, to decrypt a file, use:

−

# gpg -d secret.tar.gpg

+

$ gpg -d secret.tar.gpg

You'll be prompted to enter your passphrase.

You'll be prompted to enter your passphrase.

−

If you want to encrypt directories or a whole file-system you should consider use [[truecrypt|Truecrypt]], though you can always tarball various files and then encrypt them.

+

If you want to encrypt directories or a whole file-system you should consider using [[TrueCrypt]], though you can always tarball various files and then encrypt them.

−

−

=== Symmetric Encryption ===

== gpg-agent ==

== gpg-agent ==

−

{{Ic|gpg-agent}} is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client. It can be activated by adding following line in {{ic|~/.gnupg/gpg.conf}}:

+

{{Ic|Gpg-agent}} is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client. It can be activated by adding following line in {{ic|~/.gnupg/gpg.conf}}:

use-agent

use-agent

−

This tells GnuPG to use the agent whenever it needs the password. However, the agent needs to run already. To autostart it, create the following file and make it executable:

+

This tells GnuPG to use the agent whenever it needs the password. However, the agent needs to run already. To autostart it, create the following file and make it executable, and remember to change the envfile path if you changed your $GNUPGHOME:

export GPG_AGENT_INFO # the env file does not contain the export statement

+

export SSH_AUTH_SOCK # enable gpg-agent for ssh

fi

fi

−

export GPG_AGENT_INFO # the env file does not contain the export statement

</nowiki>}}

</nowiki>}}

−

Add an entry in your {{Ic|.xinitrc}}

+

If you don't want gpg-agent to autostart for all users or just want to keep user daemons in the users own configuration files you can add the following entry to your {{Ic|.xinitrc}}:

eval $(gpg-agent --daemon) &

eval $(gpg-agent --daemon) &

−

Log out your Xsession and login. Check {{Ic|gpg-agent}} is actived

+

Log out of your Xsession and log back in. Check if {{Ic|gpg-agent}} is activated

−

# ps aux | grep agent

+

$ pgrep agent

−

−

If you would like to use {{Ic|gpg-agent}} to manage your SSH keys see [[SSH Keys#GnuPG Agent]].

==== Pinentry ====

==== Pinentry ====

Line 118:

Line 167:

For more options see {{Ic|man gpg-agent}} and {{ic|info pinentry}}.

For more options see {{Ic|man gpg-agent}} and {{ic|info pinentry}}.

−

== Keysigning-Partys ==

+

== Keysigning Parties ==

−

To be sure I key you can find on a keyserver is realy from the person who claims it to be, PGP/GPG

+

To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses a so-called "Web of Trust". To build this Web of Trust, many hacker events include keysigning parties.

−

uses a socalled Web-of-Trust. To build this, there a Keysigning-Partys at a lot of

−

hackerevents.

−

The Zimmermann–Sassaman key-signing protocol is a way of making these very effective. See the [https://en.wikipedia.org/wiki/Zimmermann%E2%80%93Sassaman_key-signing_protocol Wikipedia article] for an description. [http://cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you'll find an How-To-article.

+

The [https://en.wikipedia.org/wiki/Zimmermann%E2%80%93Sassaman_key-signing_protocol Zimmermann-Sassaman] key-signing protocol is a way of making these very effective. [http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you'll find a How-To-article.

=== Caff ===

=== Caff ===

−

For an easier process of signing keys an sending the signatures to the owner, after a keysigning-party, you can use the tool 'caff'. It cam be installed from the AUR ether with the package {{AUR|caff-svn}} or better together with some other useful tools as the package {{AUR|signing-party-svn}}.

+

For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool 'caff'. It can be installed from the AUR with the package {{AUR|caff-svn}} or bundled together with other useful tools in the package {{AUR|signing-party-svn}}.

−

In both ways there will be a lot of dependencies to install from the AUR, alternately you can install them with

+

Either way, there will be a lot of dependencies installing from the AUR. Alternatively you can install them with

cpanm Any:Moose

cpanm Any:Moose

cpanm GnuPG::Interface

cpanm GnuPG::Interface

−

To send the signatures to its owner you need an working [https://en.wikipedia.org/wiki/Message_transfer_agent MTA], if you don't have already one install [[SSMTP]].

+

To send the signatures to their owners you need a working [https://en.wikipedia.org/wiki/Message_transfer_agent MTA]. If you don't have already one, install [[msmtp]].

== Smartcards ==

== Smartcards ==

Line 170:

Line 217:

The default pinentry program is pinentry-gtk-2, which needs a DBus session bus to run properly. See [[General Troubleshooting#Session permissions]] for details.

The default pinentry program is pinentry-gtk-2, which needs a DBus session bus to run properly. See [[General Troubleshooting#Session permissions]] for details.

−

Alternatively you can use the qt pinentry.

+

Alternatively, you can use {{ic|pinentry-qt}}. See [[GnuPG#Pinentry]].

+

+

=== KGpg configuration permissions ===

+

+

There have been issues with {{Pkg|kdeutils-kgpg}} being able to access the {{ic|~/.gnupg/}} options. One issue might be a result of a deprecated ''options'' file, see the [https://bugs.kde.org/show_bug.cgi?id=290221 bug] report.

−

# ln -sf /usr/bin/pinentry-qt4 /usr/bin/pinentry

+

Another user reported that ''KGpg'' failed to start until the {{ic|~/.gnupg}} folder is set to {{ic|drwxr-xr-x}} permissions. If you require this work-around, ensure that the directory contents retain {{ic|-rw-------}} permissions! Further, report it as a bug to the [https://bugs.kde.org/buglist.cgi?quicksearch=kgpg developers].

Installation

Environment Variables

$GNUPGHOME is used by GnuPGP to point to the directory where all configuration files are stored. By default $GNUPGHOME isn't set and your $HOME is used instead, thus you will find a ~/.gnupg directory right after the install. You may change this default setting by putting this line in one of your regular startup files

export GNUPGHOME="/path/to/gnupg/directory"

Note: by default, the gnupg directory has a particular Permissions set to 600. Only the owner of the directory has permission to read and write (r,w). This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.

GPG_AGENT_INFO used to locate the pgp-agent. Consists of 3 colon delimited fields:

1. path to Unix Domain Socket

2. PID of gpg-agent

3. protocol version set to 1

E.g : GPG_AGENT_INFO=/tmp/gpg-eFqmSC/S.gpg-agent:7795:1. When starting the gpg-agent, this variable is set to the correct value.

Configuration file

Default is ~/.gnupg/gpg.conf. If you want to change the default location, either run gpg this way $ gpg --homedir path/to/file or use $GNUPGHOME variable.

Append in this file any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. You will find a skeleton file usr/share/gnupg/gpg-conf.skel.
Following is a basic configuration file:

~/.gnupg/gpg.conf

default-key name # useful in case you manage several keys and want to set a default one
keyring file # will add file to the current list of keyrings
trustdb-name file # use file instead of the default trustdb
homedir dir # set the name of the gnupg home dir to dir instead of ~/.gnupg
display-charset utf-8 # bypass all translation and assume that the OS uses native UTF-8 encoding
keyserver name # use name as your keyserver
no-greeting # suppress the initial copyright message
armor # create ASCII armored output. Default is binary OpenPGP format

If you want to set up default options for a multi-user system, the configuration file of defaults is expected in /etc/skel/.gnupg/. With that in place the new user configuration can be created with

# addgnupghome user1 user2

which will add the respective /home/userX/.gnupg/ and copy the files from the skeleton directory to it.

You will be asked several questions. In general, most users will want both a RSA (sign only) and a RSA (encrypt only) key. It is advised to use a keysize of 4096 bits (default is 2048).

While having an expiration date for subkeys isn't technically necessary, it is considered good practice. A period of a year is generally good enough for the average user. This way even if you lose access to your keyring, it will allow others to know that it is no longer valid.

Manage your key

Running the gpg --edit-key key ID or gpg --edit-key User_name_uid command will present a menu which enables you to do most of your key management related tasks. Following is an example to set your expiration date:

Generate an ASCII version of your public key (e.g. to distribute it by e-mail):

$ gpg --armor --output public.key --export 'Your Name'

Register your key with a public PGP key server, so that others can retrieve your key without having to contact you directly:

$ gpg --keyserver pgp.mit.edu --send-keys Key Id

Sign and encrypt for user Bob

$ gpg se -r Bob file

make a clear text signature

$ gpg --clearsign file

Rotating subkeys

Warning: Never delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please only delete expired or revoked keys from other users to clean your keyring.

If you have set your subkeys to expire after a set time, you will have to create new ones. Do this a few weeks in advanced to allow others to update their keyring.

Create new subkey (repeat for both signing and encrypting key)

$ gpg --edit-key 'Your Name'
> addkey

And answer the following questions it asks (see previous section for suggested settings).

Save changes

> save

Update it to a keyserver.

$ gpg --keyserver pgp.mit.edu --send-keys Key Id

Note: Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.

Import key

Import a public key to your public key ring:

$ gpg --import public.key

Import a private key to your secret key ring:

$ gpg --import private.key

List keys

Keys in your public key ring:

$ gpg --list-keys

Keys in your secret key ring:

$ gpg --list-secret-keys

Basic usage

You can use gnupg to encrypt your sensitive documents, but only individual files at a time.

For example, to decrypt a file, use:

$ gpg -d secret.tar.gpg

You'll be prompted to enter your passphrase.

If you want to encrypt directories or a whole file-system you should consider using TrueCrypt, though you can always tarball various files and then encrypt them.

gpg-agent

Gpg-agent is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client. It can be activated by adding following line in ~/.gnupg/gpg.conf:

use-agent

This tells GnuPG to use the agent whenever it needs the password. However, the agent needs to run already. To autostart it, create the following file and make it executable, and remember to change the envfile path if you changed your $GNUPGHOME:

If you don't want gpg-agent to autostart for all users or just want to keep user daemons in the users own configuration files you can add the following entry to your .xinitrc:

eval $(gpg-agent --daemon) &

Log out of your Xsession and log back in. Check if gpg-agent is activated

$ pgrep agent

Pinentry

Finally, the agent needs to know how to ask the user for the password. This can be set in ~/.gnupg/gpg-agent.conf

The default uses a gtk dialog. To change it to ncurses or qt, set the following in the above file

pinentry-program /usr/bin/pinentry-curses

or

pinentry-program /usr/bin/pinentry-qt4

For more options see man gpg-agent and info pinentry.

Keysigning Parties

To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses a so-called "Web of Trust". To build this Web of Trust, many hacker events include keysigning parties.

The Zimmermann-Sassaman key-signing protocol is a way of making these very effective. Here you'll find a How-To-article.

Caff

For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool 'caff'. It can be installed from the AUR with the package caff-svnAUR or bundled together with other useful tools in the package signing-party-svnAUR.
Either way, there will be a lot of dependencies installing from the AUR. Alternatively you can install them with

cpanm Any:Moose
cpanm GnuPG::Interface

To send the signatures to their owners you need a working MTA. If you don't have already one, install msmtp.

Smartcards

GnuPG only setups

If you do not plan to use other cards but those based on GnuPG, you should check the reader-port parameter in ~/.gnupg/scdaemon.conf. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.

GnuPG together with OpenSC

If you are using any smartcard with an opensc driver (e.g.: ID cards from some countries) you should pay some attention to GnuPG configuration. Out of the box you might receive a message like this when using gpg --card-status

gpg: selecting openpgp failed: ec=6.108

By default, scdaemon will try to connect directly to the device. This connection will fail if the reader is being used by another process. For example: the pcscd daemon used by OpenSC. To cope with this situation we should use the same underlying driver as opensc so they can work well together.
In order to point scdaemon to use pcscd you should remove reader-port from ~/gnupg/scdaemon.conf, specify the location to libpcsclite.so library and disable ccid so we make sure that we use pcscd.

~/scdaemon.conf

pcsc-driver /usr/lib/libpcsclite.so
card-timeout 5
disable-ccid

Please check man scdaemon if you do not use OpenSC.

Troubleshooting

Su

When using pinentry, you must have the proper permisions of the terminal device (e.g. /dev/tty1) in use. However, with su (or sudo), the ownership stays with the original user, not the new one. This means that pinentry will fail, even as root. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg

chown root /dev/ttyN # where N is the current tty

and then change it back after using gpg the first time. The equivalent is likely to be true with /dev/pts/.

Note: being part of the group ttydoes not seem to alleviate the issue, at least as root. (Please confirm with non-superusers)

KGpg configuration permissions

There have been issues with kdeutils-kgpg being able to access the ~/.gnupg/ options. One issue might be a result of a deprecated options file, see the bug report.

Another user reported that KGpg failed to start until the ~/.gnupg folder is set to drwxr-xr-x permissions. If you require this work-around, ensure that the directory contents retain -rw------- permissions! Further, report it as a bug to the developers.