posts/Monkeysphere.mdwn

   1 [Monkeysphere][] is a project to verify identities of sites using the
   2 [[PGP]] web of trust.  For example, you can verifiy [[SSH]] keys using
   3 the WoT, rather than by getting fingerprints directly from the server
   4 admin (or however it is that you currently decide to accept SSH keys.
   5 You don't just accept them without checking, do you? :p).  The
   6 [Monkeysphere docs][docs] have details on common tasks.
   7
   8 Maintaining a client SSH key
   9 ----------------------------
  10
  11 You can generate a new SSH key attached to your PGP key with
  12
  13     $ monkeysphere gen-subkey
  14
  15 Which adds a new RSA subkey to your `gpg` keyring.  The new key is set
  16 to never expire, so you may want to set an expiration date by hand
  17 (See [[GnuPG maintenance]]).
  18
  19 You can export your new public key in the usual OpenSSH format with
  20
  21     $ monkeysphere keys-for-userid "Jane Doe <jdoe@example.com>"
  22     ssh-rsa ...==
  23
  24 You can then use this public key in the usual way (see my [[SSH]]
  25 post), if you don't want to use Monkeysphere to manage your
  26 `~/.ssh/authorized-keys` file automatically.
  27
  28 You can add the private part of your RSA key to your `ssh-agent` with
  29
  30     $ monkeysphere subkey-to-ssh-agent
  31
  32 If you're running an OpenSSH version >=5.7p1 and <5.9, you may be bit
  33 by [this OpenSSH regression][fifo].  If you are affected by this bug
  34 but don't want to recompile a patched OpenSSH, you can work around the
  35 problem with [[these changes|fifo.patch]] to the current Monkeysphere
  36 source (the patch also removes the passphrase prompt, so you should
  37 only use the patch if you're using GnuPGv2+, which uses `pinentry` for
  38 out-of-band passphrase entry).
  39
  40 You can list the current SSH keys in your agent with `ssh-add -l`.
  41
  42 You can get the OpenSSH fingerprint for a key with
  43
  44     $ monkeysphere sshfprs-for-userid "Jane Doe <jdoe@example.com>"
  45     01:23:45:67:89:ab:cd:ef:01:23:45:67:89:ab:cd:ef
  46
  47 By default, `monkeysphere` will fetch that key from a keyserver if you
  48 do not already have it in your keyring (see
  49 `MONKEYSPHERE_CHECK_KEYSERVER` in `monkeyserver(1)`).
  50
  51 Maintaining a host SSH key
  52 --------------------------
  53
  54 Import a SSH key with
  55
  56     $ monkeysphere-host import-key /path/to/secret/key ssh://server.example.net
  57                 ms: host key imported:
  58     pub   2048R/01234567 2011-05-28
  59     uid                  ssh://server.example.net
  60     OpenPGP fingerprint: 0123456789ABCDF0123456789ABCDF0123456789
  61     ssh fingerprint: 2048 01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF (RSA)
  62
  63 Show known keys with
  64
  65     $ monkeysphere-host show-keys
  66
  67 If you don't want to publish this key on a public keyserver, you can
  68 export it using the usual
  69
  70     $ GNUPGHOME=/var/lib/monkeysphere/host/ gpg --no-permission-warning --armor --export 01234567
  71     -----BEGIN PGP PUBLIC KEY BLOCK-----
  72     ...
  73     -----END PGP PUBLIC KEY BLOCK-----
  74
  75 where `/var/lib/monkeysphere/host/` is the location in which
  76 `monkeysphere-host` keeps its keyrings and `--no-permission-warning`
  77 ignores the group read/write/execute permissions I'd set there so I
  78 could run `monkeysphere-host` as my usual user.
  79
  80 Once you've created the host key, you'll need to sign it.  Import the
  81 key as your usual user and run
  82
  83     $ gpg --sign-key '=ssh://server.example.net'
  84
  85 You can list current signatures on the key with
  86
  87     $ gpg --check-sigs '=ssh://server.example.net'
  88
  89 Now post that signed key somewhere (e.g. a keyserver).  You should
  90 also probably import the signature into the `monkeysphere-host`
  91 keyring:
  92
  93     $ gpg --armor --export '=ssh://server.example.net' \
  94       | GNUPGHOME=/var/lib/monkeysphere/host/ gpg --no-permission-warning --import
  95
  96 Checking a host SSH key
  97 -----------------------
  98
  99 Once you have a signed host key on your keyring, you can check the
 100 fingerprints with the same command you use check user fingerprints:
 101
 102     $ monkeysphere sshfprs-for-userid 'ssh://server.example.net'
 103
 104 You can add `known_hosts` entries for any host in your keyring with
 105
 106     $ monkeysphere update-known_hosts 'server.example.net'
 107
 108 and update any hosts in your `known_hosts` file that monkeysphere
 109 already knows about with
 110
 111     $ MONKEYSPHERE_CHECK_KEYSERVER=false monkeysphere update-known_hosts
 112
 113 Without the `MONKEYSPHERE_CHECK_KEYSERVER=false`, `monkeysphere` will
 114 search the keyserver for current keys which may be useful when you
 115 don't yet have a key for that server, or if you're worried the key you
 116 have may be out of date (expired, revoked, etc.).
 117
 118 Validating HTTPS connections
 119 ----------------------------
 120
 121 The OpenPGP side of this is similar to the SSH protocol, with public
 122 keys for `https://server.example.net` etc. stored in your keyring.  As
 123 far as I can tell, there is currently no way to print the key
 124 fingerprint for a given host (analagous to `sshfprs-for-userid`), but
 125 there's a neat little server `msva-perl` that checks your trust in a
 126 particular (*context*, *peer*, *PKC type*, *peer type*, *PKC data*)
 127 tuple (e.g. (`https`, `server.example.net`, `x509pem`, `server`,
 128 `cert.pem`)), which you can do by hand (via `msva-query-agent`).
 129 There's also a XUL extension (works in Firefox and related tools) that
 130 uses the `msva` server to validate HTTPS connections automatically.
 131 Nice.
 132
 133 Packages
 134 --------
 135
 136 I've added `app-crypt/monkeysphere`, `app-crypt/msva-perl`, and
 137 `virtual/monkeysphere-validation-agent` ebuilds to my [[Gentoo
 138 overlay]], as they are not currently in the base tree.
 139
 140 [Monkeysphere]: http://web.monkeysphere.info/
 141 [docs]: http://web.monkeysphere.info/doc/
 142 [fifo]: https://bugzilla.mindrot.org/show_bug.cgi?id=1869