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.
8 Maintaining a client SSH key
9 ----------------------------
11 You can generate a new SSH key attached to your PGP key with
13 $ monkeysphere gen-subkey
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]]).
19 You can export your new public key in the usual OpenSSH format with
21 $ monkeysphere keys-for-userid "Jane Doe <jdoe@example.com>"
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.
28 You can add the private part of your RSA key to your `ssh-agent` with
30 $ monkeysphere subkey-to-ssh-agent
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).
40 You can list the current SSH keys in your agent with `ssh-add -l`.
42 You can get the OpenSSH fingerprint for a key with
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
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)`).
51 Maintaining a host SSH key
52 --------------------------
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)
65 $ monkeysphere-host show-keys
67 If you don't want to publish this key on a public keyserver, you can
68 export it using the usual
70 $ GNUPGHOME=/var/lib/monkeysphere/host/ gpg --no-permission-warning --armor --export 01234567
71 -----BEGIN PGP PUBLIC KEY BLOCK-----
73 -----END PGP PUBLIC KEY BLOCK-----
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.
80 Once you've created the host key, you'll need to sign it. Import the
81 key as your usual user and run
83 $ gpg --sign-key '=ssh://server.example.net'
85 You can list current signatures on the key with
87 $ gpg --check-sigs '=ssh://server.example.net'
89 Now post that signed key somewhere (e.g. a keyserver). You should
90 also probably import the signature into the `monkeysphere-host`
93 $ gpg --armor --export '=ssh://server.example.net' \
94 | GNUPGHOME=/var/lib/monkeysphere/host/ gpg --no-permission-warning --import
96 Checking a host SSH key
97 -----------------------
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:
102 $ monkeysphere sshfprs-for-userid 'ssh://server.example.net'
104 You can add `known_hosts` entries for any host in your keyring with
106 $ monkeysphere update-known_hosts 'server.example.net'
108 and update any hosts in your `known_hosts` file that monkeysphere
109 already knows about with
111 $ MONKEYSPHERE_CHECK_KEYSERVER=false monkeysphere update-known_hosts
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.).
118 Validating HTTPS connections
119 ----------------------------
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.
123 There's a neat little server [msva-perl][] that checks your trust in a
124 particular (*context*, *peer*, *PKC type*, *peer type*, *PKC data*)
125 tuple (e.g. (`https`, `server.example.net`, `x509pem`, `server`,
126 `cert.pem`)), which you can do by hand (via `msva-query-agent`).
127 There's also a [XUL extension][xul] (works in Firefox and related
128 tools) that uses the `msva` server to validate HTTPS connections
131 If you don't want to use the the validation agent and plugin, you can
132 verify keys by hand using `openpgp2pem` (this patch has not yet been
135 $ gpg --export 'https://server.example.net' | openpgp2pem | openssl rsa -in /dev/stdin -pubin -text
136 Public-Key: (1024 bit)
139 Exponent: 65537 (0x10001)
141 -----BEGIN PUBLIC KEY-----
143 -----END PUBLIC KEY-----
145 Compare the modulus and exponent with those listed for the public key
146 offered by the target server.
151 I've added `app-crypt/monkeysphere`, `app-crypt/msva-perl`, and
152 `virtual/monkeysphere-validation-agent` ebuilds to my
153 [[Gentoo_overlay]], as they are not currently in the base tree.
155 [Monkeysphere]: http://web.monkeysphere.info/
156 [docs]: http://web.monkeysphere.info/doc/
157 [fifo]: https://bugzilla.mindrot.org/show_bug.cgi?id=1869
158 [msva-perl]: http://web.monkeysphere.info/validation-agent/
159 [xul]: https://archive.monkeysphere.info/xul-ext/monkeysphere.xpi