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 so that your users can
   8 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
  22 ==================================
  23
  24 Server host key publication
  25 ---------------------------
  26
  27 To begin, you must first generate a server host key:
  28
  29         # monkeysphere-server gen-key
  30
  31 This will generate the key for server with the service URI
  32 (`ssh://server.example.net`).  Output the new key information with the
  33 'show-key' command:
  34
  35         # monkeysphere-server show-key
  36
  37 Once the key has been generated, it needs to be publish to the Web of
  38 Trust:
  39
  40         # monkeysphere-server publish-key
  41
  42 The server admin should now sign the server key so that people in the
  43 admin's web of trust can identify the server without manual host key
  44 checking.  On your (the admin's) local machine retrieve the host key:
  45
  46         $ gpg --search '=ssh://server.example.net'
  47
  48 Now sign the server key:
  49
  50         $ gpg --sign-key '=ssh://server.example.net'
  51
  52 Make sure you compare the fingerprint of the retrieved with the one
  53 output with the 'show-key' command above, to verify you are signing
  54 the correct key.  Finally, publish your signatures back to the
  55 keyservers:
  56
  57         $ gpg --send-key '=ssh://server.example.net'
  58
  59 Update OpenSSH configuration files
  60 ----------------------------------
  61
  62 To use the newly-generated host key for ssh connections, put the
  63 following line in `/etc/ssh/sshd_config` (be sure to comment out or
  64 remove any other HostKey references):
  65
  66         HostKey /var/lib/monkeysphere/ssh_host_rsa_key
  67
  68 FIXME: What about DSA host keys?  The SSH RFC seems to require
  69 implementations support DSA, though OpenSSH will work without a DSA
  70 host key.
  71
  72
  73 Monkeysphere for user authentication
  74 ====================================
  75
  76 A host can maintain ssh `authorized_keys` files automatically for its
  77 users with the Monkeysphere.  These `authorized_keys` files can then
  78 be used to enable users to use the monkeysphere to authenticate to
  79 your machine using the OpenPGP web of trust.
  80
  81 Before this can happen, the host must first have a host key to use for
  82 user key verification.  If you have not already generated a host key
  83 (as in the host verification instructions above), generate one now:
  84
  85         # monkeysphere-server gen-key
  86
  87 Update OpenSSH configuration files
  88 ----------------------------------
  89
  90 SSH must be configured to point to the monkeysphere generated
  91 `authorized_keys` file.  Add this line to `/etc/ssh/sshd_config`
  92 (again, making sure that no other AuthorizedKeysFile directive is left
  93 uncommented):
  94
  95         AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u
  96
  97 You'll need to restart `sshd` to have your changes take effect.  As
  98 with any change to `sshd_config`, be sure to retain an existing
  99 session to the machine while you test your changes so you don't get
 100 locked out.
 101
 102 Monkeysphere authorized_keys maintenance
 103 ----------------------------------------
 104
 105 For each user account on the server, the userids of people authorized
 106 to log into that account would be placed in:
 107
 108         ~/.monkeysphere/authorized_user_ids
 109
 110 However, in order for users to become authenticated, the server must
 111 determine that the user IDs on their keys have "full" validity.  This
 112 means that the server must fully trust at least one person whose
 113 signature on the connecting user's key would validate the relevant
 114 user ID.  The individuals trusted to identify users like this are
 115 known in the Monkeysphere as "Identity Certifiers".  In a simple
 116 scenario, the host's administrator would be trusted identity certifer.
 117 If the admin's OpenPGP keyid is `$GPGID`, then on the server run:
 118
 119         # monkeysphere-server add-identity-certifier $GPGID
 120
 121 To update the monkeysphere `authorized_keys` file for user "bob" using
 122 the current set of identity certifiers, run:
 123
 124         # monkeysphere-server update-users bob
 125
 126 To update the monkeysphere `authorized_keys` file for all users on the
 127 the system, run the same command with no arguments:
 128
 129         # monkeysphere-server update-users
 130
 131 You probably want to set up a regularly scheduled job (e.g. with cron)
 132 to take care of this automatically.
 133
 134 FIXME: document other likely problems and troubleshooting techniques