website/getting-started-admin.mdwn

   1 Monkeysphere Server Administrator README
   2 ========================================
   3
   4         Note: This documentation is for Monkeysphere version 0.28 or later.
   5         If you are running a version prior to 0.28, we recommend that you upgrade.
   6
   7 As the administrator of an SSH server, you can take advantage of the
   8 Monkeysphere in two ways:
   9
  10 1. you can publish the host key of your machine to the Web of Trust
  11 (WoT) so that your users can automatically verify it, and
  12
  13 2. you can set up your machine to automatically identify connecting
  14 users by their presence in the OpenPGP Web of Trust.
  15
  16 These two pieces are independent: you can do one without the other.
  17
  18 Monkeysphere for host verification (monkeysphere-host)
  19 ======================================================
  20
  21 Server host key publication
  22 ---------------------------
  23
  24 To begin, you must first import an ssh host key.  This assumes that
  25 you have the ssh server installed, and that you have generated a host
  26 RSA key.  Once that has been done, import the key:
  27
  28         # monkeysphere-host import-key /etc/ssh/ssh_host_rsa_key ssh://server.example.net
  29
  30 This will generate an OpenPGP certificate for the server.  The primary
  31 user ID for this certificate will be the ssh service URI for the host,
  32 (e.g. `ssh://server.example.net`).  Remember that the name you provide
  33 here should probably be a fully qualified domain name for the host in
  34 order for your users to find it.
  35
  36 Now you can display information about the host key's certificate with
  37 the 'show-key' command:
  38
  39         # monkeysphere-host show-key
  40
  41 Once the host key's certificate has been generated, you'll probably
  42 want to publish it to the public keyservers which distribute the Web
  43 of Trust:
  44
  45         # monkeysphere-host publish-key
  46
  47 But anyone could publish a simple self-signed certificate to the WoT
  48 with any name attached.  Your users should be able to tell that
  49 someone they know and trust with the machine (e.g. *you*, the
  50 administrator) has verified that this particular key is indeed the
  51 correct key.  So your next step is to sign the host's key with your
  52 own OpenPGP key.
  53
  54 On your (the admin's) local machine retrieve the host key (it may take
  55 several minutes for the key to propagate across the keyserver
  56 network), and sign it:
  57
  58         $ gpg --search '=ssh://server.example.net'
  59         $ gpg --sign-key '=ssh://server.example.net'
  60
  61 Make sure you compare the fingerprint of the retrieved certificate
  62 with the output from the 'show-key' command above!
  63
  64 Next, find out your key's Key ID, which is a hexadecimal string like "ABCDEF19"
  65
  66         $ gpg --list-keys '=ssh://server.example.net'
  67
  68 which will output something like:
  69
  70         pub   2048R/ABCDEF19 2009-05-07
  71         uid       [  full  ] ssh://server.example.net
  72
  73 Finally, publish your signatures back to the keyservers, so that your
  74 users can automatically verify your machine when they connect:
  75
  76         $ gpg --send-key ABCDEF19
  77
  78 See http://web.monkeysphere.info/signing-host-keys/ for more info
  79 signing host keys.
  80
  81 Monkeysphere for user authentication (monkeysphere-authentication)
  82 ==================================================================
  83
  84 A host can maintain ssh-style `authorized_keys` files automatically
  85 for its users with the Monkeysphere.  This frees you (the
  86 administrator) from the task of manually checking/placing SSH keys,
  87 and enables users to do relatively painless key transitions, and to
  88 quickly and universally revoke access if they find that their ssh key
  89 has become compromised.
  90
  91 You simply tell the system what *person* (identified by her OpenPGP
  92 User ID) should have access to an account, the Monkeysphere takes care
  93 of generating the proper `authorized_keys` file and keeping it
  94 up-to-date, and `sshd` reads the generated `authorized_keys` files
  95 directly.
  96
  97 Monkeysphere authorized_keys maintenance
  98 ----------------------------------------
  99
 100 For each user account on the server, the userids of people authorized
 101 to log into that account would be placed, one per line, in:
 102
 103         ~/.monkeysphere/authorized_user_ids
 104
 105 For example, this file could contain:
 106
 107         Joe User <joe@example.net>
 108         Joe User at Work <joe@example.org>
 109
 110 Provided that those exact strings are among the uids for which the user's gpg
 111 key is valid.
 112
 113 The server will use the Monkeysphere to look up matching OpenPGP
 114 certificates, validate them, and generate an `authorized_keys` file.
 115
 116 To validate the OpenPGP certificates, the server needs to know who it
 117 can trust to correctly identify users.  The individuals trusted to
 118 identify users like this are known in the Monkeysphere as "Identity
 119 Certifiers".  One obvious choice is to trust *you*, the administrator,
 120 to be an Identity Certifier.
 121
 122 You will need to know your full 40 hex character gpg fingerprint. This can be learned by doing:
 123
 124         gpg --with-colons --fingerprint user@example.org
 125
 126 Replacing "user@example.org" with either your gpg key id, or your gpg uid.
 127 The output of this command is very long and difficult to read. Look for a line like:
 128
 129         fpr:::::::::D8E6414012D371BFC5AB8E2540D6B49E0E708ADF:
 130
 131 The portion between the ":::::::::" and ":" is your 40 digit fingerprint.
 132
 133 With your OpenPGP 40-digit hex fingerprint replacing `$GPGFPR`, then
 134 run the following command on the server:
 135
 136         # monkeysphere-authentication add-identity-certifier $GPGFPR
 137
 138 You'll probably only set up Identity Certifiers when you set up the
 139 machine.  After that, you'll only need to add or remove Identity
 140 Certifiers when the roster of admins on the machine changes, or when
 141 one of the admins switches OpenPGP keys.
 142
 143 Now that the server knows who to trust to identify users, the
 144 Monkeysphere can generate ssh-style `authorized_keys` quickly and
 145 easily:
 146
 147 To update the Monkeysphere-generated `authorized_keys` file for user
 148 "bob", run:
 149
 150         # monkeysphere-authentication update-users bob
 151
 152 To update the monkeysphere `authorized_keys` file for all users on the
 153 the system, run the same command with no arguments:
 154
 155         # monkeysphere-authentication update-users
 156
 157 You probably want to set up a regularly scheduled job (e.g. with cron)
 158 to do this automatically.
 159
 160 Update OpenSSH server AuthorizedKeysFile configuration
 161 ------------------------------------------------------
 162
 163 Generating the `authorized_keys` files is not quite enough, because
 164 `sshd` needs to know where to find the generated keys.
 165
 166
 167 You can do this by adding the following line to
 168 `/etc/ssh/sshd_config`, commenting out any other `AuthorizedKeysFile`
 169 directives.
 170
 171         AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u
 172
 173 Warning: Be aware that with this change in configuration, only those users whose
 174 authorized keys files appear under the above path will be able to log in via
 175 ssh. This includes the root user if root has ssh access. Remember to run
 176 'monkeysphere-authentication update-users' if you are unsure whether any users'
 177 authorized_keys files have been updated.
 178
 179 You'll need to restart `sshd` to have your changes take effect.  As
 180 with any change to `sshd_config`, if you're doing this remotely, be
 181 sure to retain an existing session to the machine while you test your
 182 changes so you don't get locked out if something went wrong.