website/getting-started-admin.mdwn

   1 Monkeysphere Server Administrator README
   2 ========================================
   3
   4 As the administrator of an SSH server, you can take advantage of the
   5 monkeysphere in two ways:
   6
   7 1. you can publish the host key of your machine to the Web of Trust
   8 (WoT) so that your users can have it automatically verified, and
   9
  10 2. you can set up your machine to automatically identify connecting
  11 users by their presence in the OpenPGP Web of Trust.
  12
  13 These things are not mutually required, and it is in fact possible to
  14 do one without the other.  However, it is highly recommend that you at
  15 least do the first.  Even if you decide that you do not want to use
  16 the monkeysphere to authenticate users to your system, you should at
  17 least the host key into the Web of Trust so that your users can be
  18 sure they're connecting to the correct machine.
  19
  20
  21 Monkeysphere for host verification (monkeysphere-host)
  22 ======================================================
  23
  24 Server host key publication
  25 ---------------------------
  26
  27 To begin, you must first import an ssh host key.  This assumes that
  28 you have the ssh server installed, and that you have generated a host
  29 RSA key.  Once that has been done, import the key:
  30
  31         # monkeysphere-host /etc/ssh/ssh\_host\_rsa\_key
  32
  33 This will generate the key for server with the service URI
  34 (`ssh://server.example.net`).  You can output the new key information
  35 with the 'show-key' command:
  36
  37         # monkeysphere-host show-key
  38
  39 Once the key has been imported, it needs to be publish to the Web of
  40 Trust:
  41
  42         # monkeysphere-host publish-key
  43
  44 The server admin should now sign the server key so that people in the
  45 admin's web of trust can identify the server without manual host key
  46 checking.  On your (the admin's) local machine retrieve the host key:
  47
  48         $ gpg --search '=ssh://server.example.net'
  49
  50 Now sign the server key:
  51
  52         $ gpg --sign-key '=ssh://server.example.net'
  53
  54 Make sure you compare the fingerprint of the retrieved with the one
  55 output with the 'show-key' command above, to verify you are signing
  56 the correct key.  Finally, publish your signatures back to the
  57 keyservers:
  58
  59         $ gpg --send-key '=ssh://server.example.net'
  60
  61 See http://web.monkeysphere.info/signing-host-keys/ for more info
  62 signing host keys.
  63
  64 Monkeysphere for user authentication (monkeysphere-authentication)
  65 ==================================================================
  66
  67 A host can maintain ssh `authorized_keys` files automatically for its
  68 users with the Monkeysphere.  These `authorized_keys` files can then
  69 be used to enable users to use the monkeysphere to authenticate to
  70 your machine using the OpenPGP web of trust.
  71
  72 Monkeysphere authorized_keys maintenance
  73 ----------------------------------------
  74
  75 For each user account on the server, the userids of people authorized
  76 to log into that account would be placed in:
  77
  78         ~/.monkeysphere/authorized_user_ids
  79
  80 However, in order for users to become authenticated, the server must
  81 determine that the user IDs on their keys have "full" validity.  This
  82 means that the server must fully trust at least one person whose
  83 signature on the connecting user's key would validate the relevant
  84 user ID.  The individuals trusted to identify users like this are
  85 known in the Monkeysphere as "Identity Certifiers".  In a simple
  86 scenario, the host's administrator would be a trusted identity
  87 certifer.  If the admin's OpenPGP keyid is `$GPGID`, then on the
  88 server run:
  89
  90         # monkeysphere-authentication add-identity-certifier $GPGID
  91
  92 To update the monkeysphere `authorized_keys` file for user "bob" using
  93 the current set of identity certifiers, run:
  94
  95         # monkeysphere-authentication update-users bob
  96
  97 To update the monkeysphere `authorized_keys` file for all users on the
  98 the system, run the same command with no arguments:
  99
 100         # monkeysphere-authentication update-users
 101
 102 You probably want to set up a regularly scheduled job (e.g. with cron)
 103 to take care of this automatically.
 104
 105 Update OpenSSH server AuthorizedKeysFile configuration
 106 ------------------------------------------------------
 107
 108 SSH must be configured to point to the monkeysphere generated
 109 `authorized_keys` file.  Add this line to `/etc/ssh/sshd_config`
 110 (again, making sure that no other AuthorizedKeysFile directive is left
 111 uncommented):
 112
 113         AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u
 114
 115 You'll need to restart `sshd` to have your changes take effect.  As
 116 with any change to `sshd_config`, be sure to retain an existing
 117 session to the machine while you test your changes so you don't get
 118 locked out.