docs/signing.rst

   1 Signing Gerrit Commits
   2 ======================
   3
   4 1. Generate your GPG key.
   5
   6    The following instructions work on a Mac, but the general approach
   7    should be the same on other OSes.
   8
   9    .. code-block:: bash
  10
  11       brew install gpg2 # if you don't have homebrew, get that here: http://brew.sh/
  12       gpg2 --gen-key
  13       # pick 1 for "RSA and RSA"
  14       # enter 4096 to creat a 4096-bit key
  15       # enter an expiration time, I picked 2y for 2 years
  16       # enter y to accept the expiration time
  17       # pick O or Q to accept your name/email/comment
  18       # enter a pass phrase twice. it seems like backspace doesn't work, so type carefully
  19       gpg2 --fingerprint
  20       # you'll get something like this:
  21       # spectre:~ ckd$ gpg2 --fingerprint
  22       # /Users/ckd/.gnupg/pubring.gpg
  23       # -----------------------------
  24       # pub   4096R/F566C9B1 2015-04-06 [expires: 2017-04-05]
  25       #       Key fingerprint = 7C37 02AC D651 1FA7 9209  48D3 5DD5 0C4B F566 C9B1
  26       # uid       [ultimate] Colin Dixon <colin at colindixon.com>
  27       # sub   4096R/DC1497E1 2015-04-06 [expires: 2017-04-05]
  28       # you're looking for the part after 4096R, which is your key ID
  29       gpg2 --send-keys <key-id>
  30       # in the above example, the key-id would be F566C9B1
  31       # you should see output like this:
  32       # gpg: sending key F566C9B1 to hkp server keys.gnupg.net
  33
  34    If you're trying to participate in an OpenDaylight keysigning, then
  35    send the output of ``gpg2 --fingerprint <key-id>`` to
  36    keysigning@opendaylight.org
  37
  38    .. code-block:: bash
  39
  40       gpg2 --fingerprint <key-id>
  41       # in the above example, the key-id would be F566C9B1
  42       # in my case, the output was:
  43       # pub   4096R/F566C9B1 2015-04-06 [expires: 2017-04-05]
  44       #       Key fingerprint = 7C37 02AC D651 1FA7 9209  48D3 5DD5 0C4B F566 C9B1
  45       # uid       [ultimate] Colin Dixon <colin at colindixon.com>
  46       # sub   4096R/DC1497E1 2015-04-06 [expires: 2017-04-05]
  47
  48 2. Install gpg, instead of or addition to gpg2. It appears as though
  49    gpg2 has annoying things that it does when asking for your
  50    passphrase, which I haven't debugged yet.
  51
  52    .. note:: you can tell git to use gpg by doing:
  53      ``git config --global gpg.program gpg2``
  54      but that then will seem to struggle asking for your
  55      passphrase unless you have your gpg-agent set up right.
  56
  57 3. Add you GPG to Gerrit
  58
  59    a. Run the following at the CLI:
  60
  61       .. code-block:: bash
  62
  63          gpg --export -a <fingerprint>
  64          # e.g., gpg --export -a F566C9B1
  65          # in my case the output looked like:
  66          # -----BEGIN PGP PUBLIC KEY BLOCK-----
  67          # Version: GnuPG v2
  68          #
  69          # mQINBFUisGABEAC/DkcjNUhxQkRLdfbfdlq9NlfDusWri0cXLVz4YN1cTUTF5HiW
  70          # ...
  71          # gJT+FwDvCGgaE+JGlmXgjv0WSd4f9cNXkgYqfb6mpji0F3TF2HXXiVPqbwJ1V3I2
  72          # NA+l+/koCW0aMReK
  73          # =A/ql
  74          # -----END PGP PUBLIC KEY BLOCK-----
  75
  76    b. Browse to https://git.opendaylight.org/gerrit/#/settings/gpg-keys
  77    c. Click Add Key...
  78    d. Copy the output from the above command, paste it into the box,
  79       and click Add
  80
  81 3. Set up your git to sign commits and push signatures
  82
  83    .. code-block:: bash
  84
  85       git config commit.gpgsign true
  86       git config push.gpgsign true
  87       git config user.signingkey <fingerprint>
  88       # e.g., git config user.signingkey F566C9B1
  89
  90    .. note:: you can do this instead with ``git commit -S``
  91       You can use ``git commit -S`` and ``git push --signed``
  92       on the CLI instead of configuring it in config if you
  93       want to control which commits use your signature.
  94
  95 4. Commit and push a change
  96
  97    a. change a file
  98    b. ``git commit -asm "test commit"``
  99
 100       .. note:: this should result in git asking you for your passphrase
 101
 102    c. ``git review``
 103
 104       .. note:: this should result in git asking you for your passphrase
 105
 106       .. note:: annoyingly, the presence of a gpgp signature or pushing
 107         of a gpg signature isn't recognized as a "change" by
 108         Gerrit, so if you forget to do either, you need to change
 109         something about the commit to get Gerrit to accept the
 110         patch again. Slightly tweaking the commit message is a
 111         good way.
 112
 113       .. note:: this assumes you have git review set up and push.gpgsign
 114         set to true. Otherwise:
 115
 116         ``git push --signed gerrit HEAD:refs/for/master``
 117
 118         .. note:: this assumes you have your gerrit remote set up, if
 119             not it's something like:
 120             ``ssh://ckd@git.opendaylight.org:29418/<repo>.git``
 121             where repo is something like docs or controller
 122
 123 5. Verify that your commit is signed by going to the change in Gerrit
 124    and checking for a green check (instead of a blue ?) next to your
 125    name.
 126
 127
 128 Setting up gpg-agent on a Mac
 129 -----------------------------
 130
 131 #. Install ``gpg-agent`` and ``pinentry-mac`` using ``brew``::
 132
 133       brew install gpg-agent pinentry-mac
 134
 135 #. Edit your ``~/.gnupg/gpg.conf`` contain the line::
 136
 137       use-agent
 138
 139 #. Edit your ``~/.gnupg/gpg-agent.conf`` to something like::
 140
 141       use-standard-socket
 142       enable-ssh-support
 143       default-cache-ttl 600
 144       max-cache-ttl 7200
 145       pinentry-program /usr/local/bin/pinentry-mac
 146
 147 #. Edit your ``.bash_profile`` or equivalent file to contain the
 148    following:
 149
 150    .. code-block:: bash
 151
 152       [ -f ~/.gpg-agent-info ] && source ~/.gpg-agent-info
 153       if [ -S "${GPG_AGENT_INFO%%:*}" ]; then
 154         export GPG_AGENT_INFO
 155       else
 156         eval $( gpg-agent --daemon --write-env-file ~/.gpg-agent-info )
 157       fi
 158
 159 #. Kill any stray ``gpg-agent`` daemons running::
 160
 161       sudo killall gpg-agent
 162
 163 #. Restart your terminal (or log in and out) to reload the your
 164    ``.bash_profile`` or equivalent file
 165
 166 #. The next time a git operation makes a call to gpg, it should use
 167    your gpg-agent to run a GUI window to ask for your passphrase and
 168    give you an option to save your passphrase in the keychain.
 169
 170    .. image:: images/pinentry-mac.png