Updating a DD key
=================

- Key updates should be for a reason (i.e. lost control of earlier
  key, or moving to stronger key).

- Request must include:
  - Old key (full fingerprint)
  - New key (full fingerprint)
  - Inline signature with OLD key

- New key must be signed by at least two DDs (and more if possible);
  if the old key is particularly well connected, we have requested the
  person to get more signatures in order to avoid weakening the
  overall web of trust. The new key must also be signed with the old
  one (except in cases, say, where the old one was lost).

- Procedure

  I am following the request for Giovanni Mascellani (RT #2473). Of
  course, replace keys with adequate values. As you can see, this
  request mentioned only the key IDs, so full fingerprint was
  requested. 

      # Before anything else, retrieve both keys, to be able to do the
      # following checks
  $ gpg --keyserver $KEYSERVER --recv-key \
      1EB63D43E2014DDF67BD003FFCB0BB5C5F1FBF70 \
      82D119A840C6EFCA6F5AF9459EDCC991D9AB457E
  gpg: requesting key 5F1FBF70 from hkp server nisamox.fciencias.unam.mx
  gpg: requesting key D9AB457E from hkp server nisamox.fciencias.unam.mx
  gpg: key 5F1FBF70: public key "Giovanni Mascellani (Poisson)
        # <mascellani@poisson.phc.unipi.it>" imported
  gpg: key D9AB457E: public key "Giovanni Mascellani
        # <mascellani@poisson.phc.unipi.it>" imported
  gpg: 3 marginal(s) needed, 1 complete(s) needed, classic trust model
  gpg: depth: 0  valid:   3  signed: 163  trust: 0-, 0q, 0n, 0m, 0f, 3u
  gpg: depth: 1  valid: 163  signed: 409  trust: 154-, 0q, 0n, 5m, 4f,
        # 0u
  gpg: depth: 2  valid:  12  signed:  99  trust: 12-, 0q, 0n, 0m, 0f, 0u
  gpg: next trustdb check due at 2010-09-10
  gpg: Total number processed: 2
  gpg:               imported: 2  (RSA: 1)

  $ gpg --verify < (copy of RT message)
  (...)
  gpg: Signature made Sun 29 Aug 2010 07:30:03 AM CDT using RSA key ID E1889B00
  gpg: Good signature from "Giovanni Mascellani (Poisson) <mascellani@poisson.phc.unipi.it>"
  gpg:                 aka "Giovanni Mascellani <gio@debian.org>"
  gpg:                 aka "Giovanni Mascellani <g.mascellani@gmail.com>"
  gpg:                 aka "Giovanni Mascellani <g.mascellani@tiscali.it>"
  gpg:                 aka "Giovanni Mascellani (DM) <mascellani@mail.dm.unipi.it>"
  gpg:                 aka "Giovanni Mascellani (SNS) <giovanni.mascellani@sns.it>"
  gpg:                 aka "[jpeg image of size 8171]"
  gpg: WARNING: This key is not certified with a trusted signature!
  gpg:          There is no indication that the signature belongs to the owner.
  Primary key fingerprint: 1EB6 3D43 E201 4DDF 67BD  003F FCB0 BB5C 5F1F BF70
       Subkey fingerprint: 409F 2383 802D B40C CA04  9AF9 810A 9F69 E188 9B00

  - Helper script

    We have a script called "replace-key". When called, it takes care to
    do all of the steps described from here until the commit step.

    You should call it using both keys' long (64 bit) keyids:

    $ ./script/replace-key FCB0BB5C5F1FBF70 9EDCC991D9AB457E


  $ gpg --export D9AB457E > /tmp/key
      # DD keys (past and present), names and identities are kept in
      # the plaintext file 'keyids' - Confirm and get the requester's
      # Debian account name in case it's not listed as one of the
      # identities 

  $ grep 5F1FBF70 keyids 
  0xFCB0BB5C5F1FBF70 Giovanni Mascellani <gio>
      # We don't delete old kys, but move them to removed-keys-gpg/

  $ git mv debian-keyring-gpg/0xFCB0BB5C5F1FBF70 removed-keys-gpg
  debian-keyring-gpg/0xFCB0BB5C5F1FBF70 => removed-keys-gpg/0xFCB0BB5C5F1FBF70
  
  $ ./scripts/add-key /tmp/key debian-keyring-gpg/
      # A screen listing all of the requester's signatures which are
      # in the Debian keyring appears. At very least, two DD should
      # have signed his key, unless specific reasons
      # (i.e. geographical) have been already discussed. Take note of
      # the respective key IDs. If they are too many, just note the
      # first four or five, in this case: F2C423BC 33FC40A4.
      # Also take note that the old key (5F1FBF70) has also signed
      # it. 
  Are you sure you want to update this key? (y/n)
  y
  adding debian-keyring-gpg/0x9EDCC991D9AB457E
  Enter full name of new key: Giovanni Mascellani
  Enter Debian login of new key: gio

      # Note this addition in debian/changelog - Just make sure before
      # doing this you are not modifying an already uploaded changelog
      # entry! 
  $ dch -a 'Replace 0xFCB0BB5C5F1FBF70 with 0x9EDCC991D9AB457E (Giovanni Mascellani) (RT #2473)'

- Git commit

  In order for the parse-git-changelog script to work, we adhere to
  machine-parsable information in the changelog. If you used the
  replace-key script, you will find it creates a git-commit-template
  file. It just needs you to fill in the Debian user IDs for the
  New-key-certified-by field.
