~bzr-pqm/bzr/bzr.dev

GnuPG Signatures

=============================

Reasons to Sign Your Repository

--------------------------------

Bazaar can sign revisions using GnuPG, a Free Software implementation of the

OpenPGP digital signature format.  By signing commits a person wanting to

make use of a branch can be confident where the code came from, assuming the

GnuPG keys used can be verified.  This could for example prevent worry about

compromised code in the case where a server hosting Bazaar branches has been

hacked into.  It could also be used to verify that all code is written by a

select group of people, such as if contributor agreements are needed.

Signatures are passed around with commits during branch, push, merge and other

operations.

Setting up GnuPG

----------------

There are many guides to creating a digital signature key with GnuPG.  See

for example the `GnuPG Handbook

<http://www.gnupg.org/gph/en/manual.html#AEN26>`_ or the `Launchpad Wiki

<https://help.launchpad.net/YourAccount/ImportingYourPGPKey>`_.

Signing Commits

---------------

To sign commits as they are made turn on the ``create_signatures``

configuration option in your ``bazaar.conf`` or ``locations.conf`` file::

  create_signatures = always

When you next make a commit it will ask for the pass phrase for your GnuPG key. 

If you want GnuPG to remember your password ensure you have ``gnupg-agent``

installed.

To sign previous commits to a branch use ``sign-my-commits``.  This will go

through all revisions in the branch and sign any which match your

commit name.  You can also pass the name of a contributor to ``sign-my-commits``

to sign someone else's commits or if your GnuPG key does not match your Bazaar

name and e-mail::

  bzr sign-my-commits . "Amy Pond <amy@example.com>"

It will not sign commits which already have a signature.

To sign a single commit or a range of commits use the (hidden) command

``re-sign``::

  bzr re-sign -r 24

``re-sign`` is also useful to change an existing signature.

By default Bazaar will tell GnuPG to use a key with the same user

identity as the one set with ``whoami``.  To override this set

``gpg_signing_key`` in bazaar.conf or locations.conf.

  ``gpg_signing_key=DD4D5088``

  ``gpg_signing_key=amy@example.com``

Verifying Commits

-----------------

Signatures can be verified with the ``bzr verify-signatures`` command.  By

default this will check all commits in the branch and notify that all commits

are signed by known trusted signatures.  If not all commits have trusted

signatures it will give a summary of the number of commits which are invalid,

having missing keys or are not signed.

The ``verify-signatures`` command can be given a comma separated list of key

patters to specify a list of acceptable keys.  It can also take a range of

commits to verify in the current branch.  Finally using the verbose option will

list each key that is valid or authors for commits which failed::

  $bzr verify-signatures -kamy -v -r 1..5

  1 commit with valid signature

    Amy Pond <amy@example.com> signed 4 commits

  0 commits with unknown keys

  1 commit not valid

    1 commit by author The Doctor <doctor@example.com>

  0 commits not signed

Work in Progress

----------------

There is still a number of digital signature related features which

are hoped to be added to Bazaar soon.  These include bzr explorer

integration and setting branches to require signatures.