doc/GnuPG-signature.md

   1 #GnuPG signature
   2 ## Introduction
   3 ### PGP and GPG
   4 [Gnu Privacy Guard](https://gnupg.org/) (GnuPG) is an Open Source implementation of the [Pretty Good [](.html)
   5 Privacy](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP) (OpenPGP) specification. Its main purposes are digital authentication,
   6 signature and encryption.
   7
   8 It is often used by the [FLOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software) community to verify:[](.html)
   9 - Linux package signatures: Debian [SecureApt](https://wiki.debian.org/SecureApt), ArchLinux [Master [](.html)
  10 Keys](https://www.archlinux.org/master-keys/)
  11 - [SCM](https://en.wikipedia.org/wiki/Revision_control) releases & maintainer identity[](.html)
  12
  13 ### Trust
  14 To quote Phil Pennock (the author of the [SKS](https://bitbucket.org/skskeyserver/sks-keyserver/wiki/Home) key server - http://sks.spodhuis.org/):[](.html)
  15
  16 > You MUST understand that presence of data in the keyserver (pools) in no way connotes trust. Anyone can generate a key, with any name or email address, and upload it. All security and trust comes from evaluating security at the “object level”, via PGP Web-Of-Trust signatures. This keyserver makes it possible to retrieve keys, looking them up via various indices, but the collection of keys in this public pool is KNOWN to contain malicious and fraudulent keys. It is the common expectation of server operators that users understand this and use software which, like all known common OpenPGP implementations, evaluates trust accordingly. This expectation is so common that it is not normally explicitly stated.
  17
  18 Trust can be gained by having your key signed by other people (and signing their key back, too :) ), for instance during [key signing parties](https://en.wikipedia.org/wiki/Key_signing_party), see:[](.html)
  19 - [The Keysigning party HOWTO](http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html)[](.html)
  20 - [Web of trust](https://en.wikipedia.org/wiki/Web_of_trust)[](.html)
  21
  22 ## Generate a GPG key
  23 See [Generating a GPG key for Git tagging](http://stackoverflow.com/a/16725717).[](.html)
  24
  25 ### gpg - provide identity information
  26 ```bash
  27 $ gpg --gen-key
  28
  29 gpg (GnuPG) 2.1.6; Copyright (C) 2015 Free Software Foundation, Inc.
  30 This is free software: you are free to change and redistribute it.
  31 There is NO WARRANTY, to the extent permitted by law.
  32
  33 Note: Use "gpg2 --full-gen-key" for a full featured key generation dialog.
  34
  35 GnuPG needs to construct a user ID to identify your key.
  36
  37 Real name: Marvin the Paranoid Android
  38 Email address: marvin@h2g2.net
  39 You selected this USER-ID:
  40     "Marvin the Paranoid Android <marvin@h2g2.net>"
  41
  42 Change (N)ame, (E)mail, or (O)kay/(Q)uit? o
  43 We need to generate a lot of random bytes. It is a good idea to perform
  44 some other action (type on the keyboard, move the mouse, utilize the
  45 disks) during the prime generation; this gives the random number
  46 generator a better chance to gain enough entropy.
  47 ```
  48
  49 ### gpg - entropy interlude
  50 At this point, you will:
  51 - be prompted for a secure password to protect your key (the input method will depend on your Desktop Environment and configuration)
  52 - be asked to use your machine's input devices (mouse, keyboard, etc.) to generate random entropy; this step _may take some time_
  53
  54 ### gpg - key creation confirmation
  55 ```bash
  56 gpg: key A9D53A3E marked as ultimately trusted
  57 public and secret key created and signed.
  58
  59 gpg: checking the trustdb
  60 gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
  61 gpg: depth: 0  valid:   2  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 2u
  62 pub   rsa2048/A9D53A3E 2015-07-31
  63       Key fingerprint = AF2A 5381 E54B 2FD2 14C4  A9A3 0E35 ACA4 A9D5 3A3E
  64 uid       [ultimate] Marvin the Paranoid Android <marvin@h2g2.net>[](.html)
  65 sub   rsa2048/8C0EACF1 2015-07-31
  66 ```
  67
  68 ### gpg - submit your public key to a PGP server (Optional)
  69 ``` bash
  70 $ gpg --keyserver pgp.mit.edu --send-keys A9D53A3E
  71 gpg: sending key A9D53A3E to hkp server pgp.mit.edu
  72 ```
  73
  74 ## Create and push a GPG-signed tag
  75 See  [Git - Maintaining a project - Tagging your [](.html)
  76 releases](http://git-scm.com/book/en/v2/Distributed-Git-Maintaining-a-Project#Tagging-Your-Releases).
  77
  78 ### Prerequisites
  79 This guide assumes that you have:
  80 - a GPG key matching your GitHub authentication credentials
  81     - i.e., the email address identified by the GPG key is the same as the one in your `~/.gitconfig`
  82 - a GitHub fork of Shaarli
  83 - a local clone of your Shaarli fork, with the following remotes:
  84     - `origin` pointing to your GitHub fork
  85     - `upstream` pointing to the main Shaarli repository
  86 - maintainer permissions on the main Shaarli repository (to push the signed tag)
  87
  88 ### Bump Shaarli's version
  89 ```bash
  90 $ cd /path/to/shaarli
  91
  92 # create a new branch
  93 $ git fetch upstream
  94 $ git checkout upstream/master -b v0.5.0
  95
  96 # bump the version number
  97 $ vim index.php shaarli_version.php
  98
  99 # commit the changes
 100 $ git add index.php shaarli_version.php
 101 $ git commit -s -m "Bump version to v0.5.0"
 102
 103 # push the commit on your GitHub fork
 104 $ git push origin v0.5.0
 105 ```
 106
 107 ### Create and merge a Pull Request
 108 This one is pretty straightforward ;-)
 109
 110 ### Create and push a signed tag
 111 ```bash
 112 # update your local copy
 113 $ git checkout master
 114 $ git fetch upstream
 115 $ git pull upstream master
 116
 117 # create a signed tag
 118 $ git tag -s -m "Release v0.5.0" v0.5.0
 119
 120 # push it to "upstream"
 121 $ git push --tags upstream
 122 ```
 123
 124 ### Verify a signed tag
 125 [`v0.5.0`](https://github.com/shaarli/Shaarli/releases/tag/v0.5.0) is the first GPG-signed tag pushed on the Community Shaarli.[](.html)
 126
 127 Let's have a look at its signature!
 128
 129 ```bash
 130 $ cd /path/to/shaarli
 131 $ git fetch upstream
 132
 133 # get the SHA1 reference of the tag
 134 $ git show-ref tags/v0.5.0
 135 f7762cf803f03f5caf4b8078359a63783d0090c1 refs/tags/v0.5.0
 136
 137 # verify the tag signature information
 138 $ git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1
 139 gpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F
 140 gpg: Good signature from "VirtualTam <virtualtam@flibidi.net>" [ultimate][](.html)
 141 ```