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 automatically verify it, 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 two pieces are independent: you can do one without the other.
  14
  15 Monkeysphere for host verification (monkeysphere-host)
  16 ======================================================
  17
  18 Server host key publication
  19 ---------------------------
  20
  21 To begin, you must first import an ssh host key.  This assumes that
  22 you have the ssh server installed, and that you have generated a host
  23 RSA key.  Once that has been done, import the key:
  24
  25         # monkeysphere-host import-key /etc/ssh/ssh\_host\_rsa\_key
  26
  27 This will generate an OpenPGP certificate for server containing the
  28 service URI (`ssh://server.example.net`).  Now you can display
  29 information about the host key's certificate with the 'show-key'
  30 command:
  31
  32         # monkeysphere-host show-key
  33
  34 Once the host key's certificate has been generated, you'll probably
  35 want to publish it to the public keyservers which distribute the Web
  36 of Trust:
  37
  38         # monkeysphere-host publish-key
  39
  40 But anyone could publish a simple self-signed certificate to the WoT
  41 with any name attached.  Your users should be able to tell that
  42 someone they know and trust with the machine (e.g. *you*, the
  43 administrator) has verified that this particular key is indeed the
  44 correct key.  So your next step is to sign the host's key with your
  45 own OpenPGP key.
  46
  47 On your (the admin's) local machine retrieve the host key (it may take
  48 several minutes for the key to propagate across the keyserver
  49 network), and sign it:
  50
  51         $ gpg --search '=ssh://server.example.net'
  52         $ gpg --sign-key '=ssh://server.example.net'
  53
  54 Make sure you compare the fingerprint of the retrieved certificate
  55 with the output from the 'show-key' command above!
  56
  57 Finally, publish your signatures back to the keyservers, so that your
  58 users can automatically verify your machine when they connect:
  59
  60         $ gpg --send-key '=ssh://server.example.net'
  61
  62 See http://web.monkeysphere.info/signing-host-keys/ for more info
  63 signing host keys.
  64
  65 Monkeysphere for user authentication (monkeysphere-authentication)
  66 ==================================================================
  67
  68 A host can maintain ssh-style `authorized_keys` files automatically
  69 for its users with the Monkeysphere.  This frees you (the
  70 administrator) from the task of manually checking/placing SSH keys,
  71 and enables users to do relatively painless key transitions, and to
  72 quickly and universally revoke access if they find that their ssh key
  73 has become compromised.
  74
  75 You simply tell the system what *person* (identified by her OpenPGP
  76 User ID) should have access to an account, the Monkeysphere takes care
  77 of generating the proper `authorized_keys` file and keeping it
  78 up-to-date, and `sshd` reads the generated `authorized_keys` files
  79 directly.
  80
  81 Monkeysphere authorized_keys maintenance
  82 ----------------------------------------
  83
  84 For each user account on the server, the userids of people authorized
  85 to log into that account would be placed in:
  86
  87         ~/.monkeysphere/authorized_user_ids
  88
  89 The server will use the Monkeysphere to look up matching OpenPGP
  90 certificates, validate them, and generate an `authorized_keys` file.
  91
  92 To validate the OpenPGP certificates, the server needs to know who it
  93 can trust to correctly identify users.  The individuals trusted to
  94 identify users like this are known in the Monkeysphere as "Identity
  95 Certifiers".  One obvious choice is to trust *you*, the administrator,
  96 to be an Identity Certifier.  If your OpenPGP keyid is `$GPGID`, then
  97 run the following command on the server:
  98
  99         # monkeysphere-authentication add-identity-certifier $GPGID
 100
 101 You'll probably only set up Identity Certifiers when you set up the
 102 machine.  After that, you'll only need to add or remove Identity
 103 Certifiers when the roster of admins on the machine changes, or when
 104 one of the admins switches OpenPGP keys.
 105
 106 Now that the server knows who to trust to identify users, the
 107 Monkeysphere can generate ssh-style `authorized_keys` quickly and
 108 easily:
 109
 110 To update the Monkeysphere-generated `authorized_keys` file for user
 111 "bob", run:
 112
 113         # monkeysphere-authentication update-users bob
 114
 115 To update the monkeysphere `authorized_keys` file for all users on the
 116 the system, run the same command with no arguments:
 117
 118         # monkeysphere-authentication update-users
 119
 120 You probably want to set up a regularly scheduled job (e.g. with cron)
 121 to do this automatically.
 122
 123 Update OpenSSH server AuthorizedKeysFile configuration
 124 ------------------------------------------------------
 125
 126 Generating the `authorized_keys` files is not quite enough, because
 127 `sshd` needs to know where to find the generated keys.
 128
 129 You can do this by adding the following line to
 130 `/etc/ssh/sshd_config`, commenting out any other `AuthorizedKeysFile`
 131 directives:
 132
 133         AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u
 134
 135 You'll need to restart `sshd` to have your changes take effect.  As
 136 with any change to `sshd_config`, if you're doing this remotely, be
 137 sure to retain an existing session to the machine while you test your
 138 changes so you don't get locked out if something went wrong.