The pacman-key tool is used to set up and manage package signing in Arch Linux.

−

pacman-key is a new tool available with pacman 4. It allows the user to manage pacman's list of trusted keys in the new package signing implementation.

+

==Introduction==

+

Pacman uses [http://www.gnupg.org/ GnuPG keys] in a [http://www.gnupg.org/gph/en/manual.html#AEN385 web of trust] model to determine if packages are authentic. There are currently five [https://www.archlinux.org/master-keys/ Master Signing Keys]. At least three of these Master Signing Keys are used to sign each of the Developer's and Trusted User's own keys which then in turn are used to sign their packages. The user also has a unique PGP key which is generated when you set up pacman-key. So the web of trust links the user's key to the five Master Keys.

−

==How it works==

+

Examples of webs of trust:

−

Package signing in pacman uses the "web of trust" model to ensure that packages come from the developers and not from someone impersonating them. Package developers and TUs have individual PGP keys which they use to sign their packages. This signature means they vouch for the contents of the package. You also have a unique PGP key which is generated when you set up pacman-key.

+

−

Keys can also be used to sign ''other'' keys, which means the owner of the signing key vouches for the authenticity of the signed key. In order to trust a package, you need to have a chain of signatures from your own PGP key to the package itself. With the Arch key structure, this can happen in three ways:

* '''Custom packages''': You made the package yourself and signed it with your own key.

* '''Custom packages''': You made the package yourself and signed it with your own key.

* '''Unofficial packages''': A developer made the package and signed it. You used your key to sign that developer's key.

* '''Unofficial packages''': A developer made the package and signed it. You used your key to sign that developer's key.

* '''Official packages''': A developer made the package and signed it. The developer's key was signed by the Arch Linux master keys. You used your key to sign the master keys, and you trust them to vouch for developers.

* '''Official packages''': A developer made the package and signed it. The developer's key was signed by the Arch Linux master keys. You used your key to sign the master keys, and you trust them to vouch for developers.

−

For some background on this issue, see these blog entries [http://allanmcrae.com/2011/08/pacman-package-signing-1-makepkg-and-repo-add/][http://allanmcrae.com/2011/08/pacman-package-signing-2-pacman-key/][http://allanmcrae.com/2011/08/pacman-package-signing-3-pacman/][http://allanmcrae.com/2011/12/pacman-package-signing-4-arch-linux/] and the [[Package Signing Proposal for Pacman|package signing proposal]] wiki page.

+

{{Note| The HKP protocol uses 11371/tcp for communication. In order to get the signed keys from the servers (using pacman-key), this port is required for communication.}}

==Setup==

==Setup==

=== Configuring pacman ===

=== Configuring pacman ===

−

First, you need to decide what level of checking you want. This is configured using the {{ic|SigLevel}} option in {{ic|/etc/pacman.conf}}. Several possibilities are mentioned in the comments in that file, and you can read the [https://www.archlinux.org/pacman/pacman.conf.5.html#_package_and_database_signature_checking {{ic|pacman.conf}} man page] for full details. Basically, you can allow signature checking globally or per repository. Keep in mind that if you set the SigLevel globally in the [options] section, you will not be able to install your own packages using {{ic|pacman -U}} anymore if they are not signed by a trusted key.

+

The {{ic|SigLevel}} option in {{ic|/etc/pacman.conf}} determines how much trust is required to install a package. For a detailed explanation of {{ic|SigLevel}} see the [https://www.archlinux.org/pacman/pacman.conf.5.html#_package_and_database_signature_checking pacman.conf man page] and the comments in the file itself. Signature checking may be set globally or per repository. If {{ic|SigLevel}} is set globally in the [options] section to require all packages to be signed, then packages you build will also need to be signed using {{ic|makepkg}}.

−

+

{{Note|Although all official packages are now signed, as of June 2012 signing of the databases is a work in progress. If {{ic|Required}} is set then {{ic|DatabaseOptional}} should also be set.}}

−

{{warning|The {{ic|SigLevel}} {{ic|TrustAll}} option exists for debugging purposes and makes it very easy to trust keys that have not been verified. You should use {{ic|TrustedOnly}} for all official repositories.}}

+

A default configuration of {{hc|1=/etc/pacman.conf|output=SigLevel = Required DatabaseOptional}}can be used to only install packages that are signed by trusted keys. This is because {{ic|TrustOnly}} is a default compiled-in pacman parameter. So above leads to the same result as a global option of {{bc|1=SigLevel = Required DatabaseOptional TrustedOnly}}The above can be achieved too on a repository level further below in the configuration, e.g.

−

+

−

{{Note|As of April 2012, database signing has not been implemented yet, so you will need to add the {{ic|DatabaseOptional}} option if you use {{ic|Required}}, for example:

+

−

{{bc|1=SigLevel = Required DatabaseOptional TrustedOnly}}

+

−

This way pacman will only install packages that are signed by keys that you trust.}}

+

−

+

−

{{Note|It looks like {{ic|1=SigLevel = PackageRequired}} is going to be standard for verifying official packages:

+

−

+

{{bc|1=[core]

{{bc|1=[core]

−

SigLevel = PackageRequired

+

SigLevel = PackageRequired # ’Optional’ here would turn off a global ’Required’ for this repository

−

Include = /etc/pacman.d/mirrorlist}}}}

+

Include = /etc/pacman.d/mirrorlist}}

+

explicitly adds signature checking for the packages of the repository, but does not require the database to be signed.

+

{{warning|The SigLevel {{ic|TrustAll}} option exists for debugging purposes and makes it very easy to trust keys that have not been verified. You should use {{ic|TrustedOnly}} for all official repositories.}}

−

===Initializing keyring===

+

===Initializing the keyring===

To set up the pacman keyring use:

To set up the pacman keyring use:

# pacman-key --init

# pacman-key --init

−

This will set up a new keyring in {{ic|/etc/pacman.d/gnupg}} and generate a unique master key for your system.

+

For this initialization, [[Wikipedia:Entropy_(computing)|entropy]] is required. Moving your mouse around, pressing random characters at the keyboard or running some disk-based activity (for example in another console running {{ic|ls -R /}} or {{ic|find / -name foo}} or {{ic|1=dd if=/dev/sda8 of=/dev/tty7}}) should generate entropy. If your system does not already have sufficient entropy, this step may take hours; if you actively generate entropy, it will complete much more quickly.

−

For pacman to start checking package signatures you have to import the developers keys to your keyring. The next section explains how to do so.

+

−

==Managing the keyring==

+

The randomness created is used to set up a keyring ({{ic|/etc/pacman.d/gnupg}}) and the GPG signing key of your system.

−

The keys which are needed to verify package signatures are stored in a "keyring" managed by pacman-key. When a key is needed which is not in the keyring, pacman and pacman-key can retrieve it from a keyserver. The keyserver to use is configured in {{ic|/etc/pacman.d/gnupg/gpg.conf}}, and you can override it by using the {{ic|--keyserver}} option on the command line. (If you are looking for different keyservers, you can find a short list on the [[wikipedia:Key server (cryptographic)|Wikipedia article]].)

+

−

PGP keys are usually too large (2048 bits or more) for humans to work with, so they are usually hashed to create a 40-hex-digit fingerprint. The last eight digits are known as the key ID, and are used as a "name" for the key. The longer fingerprint is used when you want to check by hand that two keys are the same.

+

{{Note|If you need to run {{ic|pacman-key --init}} over SSH, install the {{Pkg|haveged}} package on the target machine. Connect via SSH and run the following:

There are five Arch Linux master keys which are used to sign the keys of developers and TUs. These keys should be in your keyring, signed by you and given a marginal level of trust for pacman to trust these PGP keys.

+

# pkill haveged

+

# pacman -Rs haveged

+

The {{Pkg|haveged}} solution is not just for use over SSH: it's a great way to get some entropy quickly. If you're having problems with {{ic|pacman-key --init}} taking ages then you should try this solution.

Take time to verify the [https://www.archlinux.org/master-keys/ Master Signing Keys] when prompted as these are used to co-sign (and therefore trust) all other packager's keys.

−

{{Warning|

+

PGP keys are too large (2048 bits or more) for humans to work with, so they are usually hashed to create a 40-hex-digit fingerprint which can be used to check by hand that two keys are the same. The last eight digits of the fingerprint serve as a name for the key known as the 'key ID'.

−

You should check if master keys above match [https://www.archlinux.org/master-keys/ these fingerprints].}}

+

−

===Official developer keys===

+

===Adding Developer keys===

−

The official developer and TU keys are signed by the master keys, so you do not need to use pacman-key to sign them yourself. Whenever pacman encounters a key it does not recognize, it will ask you if you want to download it from a keyserver. Once you have downloaded a developer key, you will not have to download it again, and it can be used to verify any other packages signed by that developer.

+

The official developer and TU keys are signed by the master keys, so you do not need to use pacman-key to sign them yourself. Whenever pacman encounters a key it does not recognize, it will promt to download it from a {{ic|keyserver}} configured in {{ic|/etc/pacman.d/gnupg/gpg.conf}} (or by using the {{ic|--keyserver}} option on the command line). Wikipedia maintains a [[wikipedia:Key server (cryptographic)|list of keyservers]].

−

If the developer's and TU's keys were added some time ago, their signatures by the master keys might not be present in the local keyring database.

+

Once you have downloaded a developer key, you will not have to download it again, and it can be used to verify any other packages signed by that developer.

While doing {{ic|--refresh-keys}}, your local key will also be looked up on the remote keyserver, and you will receive a message about it being not found. This is nothing to be concerned about.}}

−

{{Note|While doing {{ic|--refresh-keys}}, your local key will also be looked up on the remote keyserver, and you will receive a message about it being not found. This is nothing to be concerned about.}}

+

===Adding Unofficial keys===

−

+

First, get the ID from the owner of the key. Run:

−

===Importing Developers and Trusted Users Keys===

+

−

Get all keys from Arch Linux developers and Trusted Users on a shot (taken from [http://bbs.archbang.org/viewtopic.php?pid=9971#p9971 this thread]):

Arch Linux provides the {{Pkg|archlinux-keyring}} package that will automatically load your keyring with the master and developers keys when installed. It will also contain updated keys eliminating need for executing {{Ic|pacman-key --refresh-keys}}. If you do not have the master keys in your keyring when you install this package, it will ask you to sign the master keys.

+

−

+

−

{{Warning| Installing {{Pkg|archlinux-keyring}} '''before''' enabling package validation may cause dangerous results in case of a hacked mirror or intercepted connection. Ensure you have enabled package validation in {{ic|/etc/pacman.conf}} and added the correct Master Signing Keys before installing the package.}}

+

−

+

−

===Unofficial keys===

+

−

If you want to add an unofficial key to your keyring, you will need to do it manually using pacman-key. First, get the ID from the owner of the key. Run:

+

{{bc|# pacman-key -r <keyid>}}

{{bc|# pacman-key -r <keyid>}}

to download it from a keyserver. Be sure to verify the fingerprint, as you would with a master key, or any other key which you are going to sign. After verifying the fingerprint, you need to locally sign this key:

to download it from a keyserver. Be sure to verify the fingerprint, as you would with a master key, or any other key which you are going to sign. After verifying the fingerprint, you need to locally sign this key:

Line 83:

Line 76:

You now trust this key to sign packages.

You now trust this key to sign packages.

−

===By gpg===

+

===Using gpg===

If pacman-key is not enough, you can manage pacman's keyring by '''gpg''' like this:

If pacman-key is not enough, you can manage pacman's keyring by '''gpg''' like this:

# gpg --homedir /etc/pacman.d/gnupg $OPTIONS

# gpg --homedir /etc/pacman.d/gnupg $OPTIONS

Line 90:

Line 83:

==Troubleshooting==

==Troubleshooting==

−

===How can I collect entropy?===

−

Moving your mouse around, pressing random characters at the keyboard or running some disk-based activity e.g. {{ic|updatedb}} in another virtual console can solve it. '''It may take a while so please be patient.'''

−

If you need to run {{ic|pacman-key --init}} over ssh, install the {{Pkg|haveged}} package on the target machine. Connect via ssh and do the following:

+

{{Warning|Pacman-key depends on [[time]] if your system clock is wrong, you'll get

Some ISPs block the port used to import PGP keys. One solution is to use the MIT keyserver, which provides an alternate port. To do this, edit {{ic|/etc/pacman.d/gnupg/gpg.conf}} and change the keyserver line to:

Some ISPs block the port used to import PGP keys. One solution is to use the MIT keyserver, which provides an alternate port. To do this, edit {{ic|/etc/pacman.d/gnupg/gpg.conf}} and change the keyserver line to:

{{bc|keyserver hkp://pgp.mit.edu:11371}}

{{bc|keyserver hkp://pgp.mit.edu:11371}}

+

+

If you happen to forget to run {{ic|pacman-key --populate archlinux}} you might get some errors while importing keys.

===Disabling signature checking===

===Disabling signature checking===

Line 117:

Line 107:

If you want to remove or reset all the keys installed in your system, you can remove {{ic|/etc/pacman.d/gnupg}} folder as root and rerun {{ic|pacman-key --init}} and following that add the keys as preferred.

If you want to remove or reset all the keys installed in your system, you can remove {{ic|/etc/pacman.d/gnupg}} folder as root and rerun {{ic|pacman-key --init}} and following that add the keys as preferred.

+

+

===Removing stale packages===

+

+

If the same packages keep failing and you are sure you did all the pacman-key stuff right, try removing them like so {{ic|rm /var/cache/pacman/pkg/badpackage*}} so that they are freshly downloaded.

+

+

This might actually be the solution if you get a message like <code>error: linux: signature from "Some Person <Some.Person@example.com>" is invalid</code> or similar when upgrading (ie. you might not be the victim of a MITM attack after all, your downloaded file was simply corrupt).

Introduction

Pacman uses GnuPG keys in a web of trust model to determine if packages are authentic. There are currently five Master Signing Keys. At least three of these Master Signing Keys are used to sign each of the Developer's and Trusted User's own keys which then in turn are used to sign their packages. The user also has a unique PGP key which is generated when you set up pacman-key. So the web of trust links the user's key to the five Master Keys.

Examples of webs of trust:

Custom packages: You made the package yourself and signed it with your own key.

Unofficial packages: A developer made the package and signed it. You used your key to sign that developer's key.

Official packages: A developer made the package and signed it. The developer's key was signed by the Arch Linux master keys. You used your key to sign the master keys, and you trust them to vouch for developers.

Note: The HKP protocol uses 11371/tcp for communication. In order to get the signed keys from the servers (using pacman-key), this port is required for communication.

Setup

Configuring pacman

The SigLevel option in /etc/pacman.conf determines how much trust is required to install a package. For a detailed explanation of SigLevel see the pacman.conf man page and the comments in the file itself. Signature checking may be set globally or per repository. If SigLevel is set globally in the [options] section to require all packages to be signed, then packages you build will also need to be signed using makepkg.

Note: Although all official packages are now signed, as of June 2012 signing of the databases is a work in progress. If Required is set then DatabaseOptional should also be set.

A default configuration of

/etc/pacman.conf

SigLevel = Required DatabaseOptional

can be used to only install packages that are signed by trusted keys. This is because TrustOnly is a default compiled-in pacman parameter. So above leads to the same result as a global option of

SigLevel = Required DatabaseOptional TrustedOnly

The above can be achieved too on a repository level further below in the configuration, e.g.

[core]
SigLevel = PackageRequired # ’Optional’ here would turn off a global ’Required’ for this repository
Include = /etc/pacman.d/mirrorlist

explicitly adds signature checking for the packages of the repository, but does not require the database to be signed.

Warning: The SigLevel TrustAll option exists for debugging purposes and makes it very easy to trust keys that have not been verified. You should use TrustedOnly for all official repositories.

Initializing the keyring

To set up the pacman keyring use:

# pacman-key --init

For this initialization, entropy is required. Moving your mouse around, pressing random characters at the keyboard or running some disk-based activity (for example in another console running ls -R / or find / -name foo or dd if=/dev/sda8 of=/dev/tty7) should generate entropy. If your system does not already have sufficient entropy, this step may take hours; if you actively generate entropy, it will complete much more quickly.

The randomness created is used to set up a keyring (/etc/pacman.d/gnupg) and the GPG signing key of your system.

Note: If you need to run pacman-key --init over SSH, install the haveged package on the target machine. Connect via SSH and run the following:

The haveged solution is not just for use over SSH: it's a great way to get some entropy quickly. If you're having problems with pacman-key --init taking ages then you should try this solution.

Managing the keyring

Verifying the five Master keys

The initial setup of keys is achieved using:

# pacman-key --populate archlinux

Take time to verify the Master Signing Keys when prompted as these are used to co-sign (and therefore trust) all other packager's keys.

PGP keys are too large (2048 bits or more) for humans to work with, so they are usually hashed to create a 40-hex-digit fingerprint which can be used to check by hand that two keys are the same. The last eight digits of the fingerprint serve as a name for the key known as the 'key ID'.

Adding Developer keys

The official developer and TU keys are signed by the master keys, so you do not need to use pacman-key to sign them yourself. Whenever pacman encounters a key it does not recognize, it will promt to download it from a keyserver configured in /etc/pacman.d/gnupg/gpg.conf (or by using the --keyserver option on the command line). Wikipedia maintains a list of keyservers.

Once you have downloaded a developer key, you will not have to download it again, and it can be used to verify any other packages signed by that developer.

Note: The archlinux-keyring package (a dependancy of pacman) contains the latest keys. However keys can also be updated using:

# pacman-key --refresh-keys

While doing --refresh-keys, your local key will also be looked up on the remote keyserver, and you will receive a message about it being not found. This is nothing to be concerned about.

Adding Unofficial keys

First, get the ID from the owner of the key. Run:

# pacman-key -r <keyid>

to download it from a keyserver. Be sure to verify the fingerprint, as you would with a master key, or any other key which you are going to sign. After verifying the fingerprint, you need to locally sign this key:

# pacman-key --lsign-key <keyid>

You now trust this key to sign packages.

Using gpg

If pacman-key is not enough, you can manage pacman's keyring by gpg like this:

# gpg --homedir /etc/pacman.d/gnupg $OPTIONS

or

# env GNUPGHOME=/etc/pacman.d/gnupg gpg $OPTIONS

Troubleshooting

Warning: Pacman-key depends on time if your system clock is wrong, you'll get

Cannot import keys

Some ISPs block the port used to import PGP keys. One solution is to use the MIT keyserver, which provides an alternate port. To do this, edit /etc/pacman.d/gnupg/gpg.conf and change the keyserver line to:

keyserver hkp://pgp.mit.edu:11371

If you happen to forget to run pacman-key --populate archlinux you might get some errors while importing keys.

Disabling signature checking

If you are not concerned about package signing, you can disable PGP signature checking completely. Edit /etc/pacman.conf and uncomment the following line under [options]:

SigLevel = Never

You need to comment out any repository-specific SigLevel settings too because they override the global settings.
This will result in no signature checking, which was the behavior before pacman 4. If you decide to do this, you do not need to set up a keyring with pacman-key. You can change this option later if you decide to enable package verification.

Resetting all the keys

If you want to remove or reset all the keys installed in your system, you can remove /etc/pacman.d/gnupg folder as root and rerun pacman-key --init and following that add the keys as preferred.

Removing stale packages

If the same packages keep failing and you are sure you did all the pacman-key stuff right, try removing them like so rm /var/cache/pacman/pkg/badpackage* so that they are freshly downloaded.

This might actually be the solution if you get a message like error: linux: signature from "Some Person <Some.Person@example.com>" is invalid or similar when upgrading (ie. you might not be the victim of a MITM attack after all, your downloaded file was simply corrupt).