doc/README

   1 Monkeysphere README
   2 ===================
   3
   4 Default files locations (by variable):
   5
   6 MS_HOME=~/.config/monkeysphere
   7 MS_CONF=$MS_HOME/monkeysphere.conf
   8 AUTH_HOST_FILE=$MS_HOME/auth_host_ids
   9 AUTH_USER_FILE=$MS_HOME/auth_user_ids
  10 GNUPGHOME=~/.gnupg
  11 STAGING_AREA=$MS_HOME
  12
  13 $STAGING_AREA/host_keys/KEYHASH
  14 $STAGING_AREA/known_hosts
  15 $STAGING_AREA/user_keys/KEYHASH
  16 $STAGING_AREA/authorized_keys
  17
  18 user usage
  19 ----------
  20 For a user to update their ms known_hosts file:
  21
  22 $ rhesus --known_hosts
  23
  24 For a user to update their ms authorized_keys file:
  25
  26 $ rhesus --authorized_keys
  27
  28 server service publication
  29 --------------------------
  30 To publish a server host key use the "howler" component:
  31
  32 # howler gen-key
  33 # howler publish-key
  34
  35 This will generate the key for server with the service URI
  36 (ssh://server.hostname).  The server admin should now sign the server
  37 key so that people in the admin's web of trust can authenticate the
  38 server without manual host key checking:
  39
  40 $ gpg --search ='ssh://server.hostname'
  41 $ gpg --sign-key 'ssh://server.hostname'
  42
  43 server authorized_keys maintenance
  44 ----------------------------------
  45 A system can maintain ms authorized_keys files for it's users.  Some
  46 different variables need to be defined to help manage this.  The way
  47 this is done is by first defining a new MS_HOME:
  48
  49 MS_HOME=/etc/monkeysphere
  50
  51 This directory would then have a monkeysphere.conf which defines the
  52 following variables:
  53
  54 AUTH_USER_FILE="$MS_HOME"/auth_user_ids/"$USER"
  55 STAGING_AREA=/var/lib/monkeysphere/stage/$USER
  56 GNUPGHOME=$MS_HOME/gnupg
  57
  58 For each user account on the server, the userids of people authorized
  59 to log into that account would be placed in the AUTH_USER_FILE for
  60 that user.  However, in order for users to become authenticated, the
  61 server must determine that the user keys have "full" validity.  This
  62 means that the server must fully trust at least one person whose
  63 signature on the connecting users key would validate the user.  This
  64 would generally be the server admin.  If the server admin's keyid is
  65 XXXXXXXX, then on the server run:
  66
  67 # howler trust-key XXXXXXXX
  68
  69 To update the ms authorized_keys file for user "bob", the system would
  70 then run the following:
  71
  72 # USER=bob MS_HOME=/etc/monkeysphere rhesus --authorized_keys
  73
  74 To update the ms authorized_keys file for all users on the the system:
  75
  76 MS_HOME=/etc/monkeysphere
  77 for USER in $(ls -1 /etc/monkeysphere/auth_user_ids) ; do
  78     rhesus --authorized_keys
  79 done