man/man8/monkeysphere-server.8

   1 .TH MONKEYSPHERE-SERVER "1" "June 2008" "monkeysphere 0.1" "User Commands"
   2
   3 .SH NAME
   4
   5 monkeysphere-server \- monkeysphere server admin user interface
   6
   7 .SH SYNOPSIS
   8
   9 .B monkeysphere-server \fIcommand\fP [\fIargs\fP]
  10
  11 .SH DESCRIPTION
  12
  13 \fBMonkeySphere\fP is a system to leverage the OpenPGP Web of Trust
  14 for ssh authentication and encryption.  OpenPGP keys are tracked via
  15 GnuPG, and added to the ssh authorized_keys and known_hosts files to
  16 be used for authentication of ssh connections.
  17
  18 \fBmonkeysphere-server\fP is the MonkeySphere server admin utility.
  19
  20 .SH SUBCOMMANDS
  21
  22 \fBmonkeysphere-server\fP takes various subcommands:
  23 .TP
  24 .B update-users [USER]...
  25 Update the admin-controlled authorized_keys files for user.  For each
  26 user specified, user ID's listed in the user's authorized_user_ids
  27 file are processed, and the user's authorized_keys file in
  28 /var/cache/monkeysphere/authorized_keys/USER.  See `man monkeysphere'
  29 for more info.  If the RAW_AUTHORIZED_KEYS variable is set, then a
  30 user-controlled authorized_keys file (usually
  31 ~USER/.ssh/authorized_keys) is added to the authorized_keys file.  `u'
  32 may be used in place of `update-users.
  33 .TP
  34 .B gen-key
  35 Generate a gpg key pair for the host.  `g' may be used in place of
  36 `gen-key'.
  37 .TP
  38 .B show-fingerprint
  39 Show the fingerprint for the host's OpenPGP key.  `f' may be used in place of
  40 `show-fingerprint'.
  41 .TP
  42 .B publish-key
  43 Publish the host's gpg key to the keyserver.  `p' may be used in place
  44 of `publish-key'.
  45 .TP
  46 .B add-certifier KEYID
  47 Add a certifier key to host keyring.  The key with specified key ID
  48 will be retrieved from the keyserver and imported to the host keyring.
  49 It will then be given a non-exportable trust signature, with default
  50 depth of 1, so that the key may certifier users to log into the
  51 system.  `a' may be used in place of `add-certifier'.
  52 .TP
  53 .B remove-certifier KEYID
  54 Remove a certifier key from the host keyring.  The key with specified
  55 key ID will be removed entirely from the host keyring so that the key
  56 will not longer be able to certify users on the system.  `r' may be
  57 used in place of `remove-certifier'.
  58 .TP
  59 .B list-certifiers KEYID
  60 Add key to certify system users.  If LEVEL is not specified, then the program
  61 will prompt for an owner trust level to set for KEYID.  This function
  62 lsigns the key as well so that it will have a known validity.  `l' may
  63 be used in place of `list-certifiers'.
  64 .TP
  65 .B help
  66 Output a brief usage summary.  `h' or `?' may be used in place of
  67 `help'.
  68
  69 .SH SETUP
  70
  71 In order to start using the monkeysphere, you must first generate an
  72 OpenPGP key for the server and convert that key to an ssh key that can
  73 be used by ssh for host authentication.  To do this, run the "gen-key"
  74 subcommand to generate the host key pair:
  75
  76 $ monkeysphere-server gen-key
  77
  78 To enable host verification via the monkeysphere, you must then
  79 publish the host's key to the Web of Trust using the "publish-key"
  80 command to push the key to a keyserver.  Then modify the sshd_config
  81 to tell sshd where the new server host key is located:
  82
  83 HostKey /var/lib/monkeysphere/ssh_host_rsa_key
  84
  85 For users logging into the system to be able to verify the host via
  86 the monkeysphere, at least one person (ie. a server admin) will need
  87 to sign the host's key.  This is done in the same way that key signing
  88 is usually done, by pulling the host's key from the keyserver, signing
  89 the key, and re-publishing the signature.  Once that is done, users
  90 logging into the host will be able to certify the host's key via the
  91 signature of the host admin.
  92
  93 If the server will also handle user authentication through
  94 monkeysphere-generated authorized_keys files, the server must be told
  95 which keys will act as user certifiers.  This is done with the
  96 "add-certifier" command:
  97
  98 $ monkeysphere-server add-certifier KEYID
  99
 100 where KEYID is the key ID of the server admin, or whoever's signature
 101 will be certifying users to the system.  Certifiers can be later
 102 remove with the "remove-certifier" command, and listed with the
 103 "list-certifiers" command.
 104
 105 Remote user's will then be granted access to a local user account
 106 based on the appropriately signed and valid keys associated with user
 107 IDs listed in the authorized_user_ids file of the local user.  By
 108 default, the authorized_user_ids file for local users is found in
 109 ~/.config/monkeysphere/authorized_user_ids.  This can be changed in
 110 the monkeysphere-server.conf file.
 111
 112 The "update-users" command can then be used to generate
 113 authorized_keys file for local users that sshd can use to grant access
 114 to user accounts for remote users:
 115
 116 $ monkeysphere-server update-users [USER]
 117
 118 If no user is specified, authorized_keys files will be generated for
 119 all users on the system.  You must also tell sshd to look at the
 120 monkeysphere-generated authorized_keys file for user authentication by
 121 setting the following in the sshd_config:
 122
 123 AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u
 124
 125 It is recommended to add "monkeysphere-server update-users" to a
 126 system crontab, so that user keys are kept up-to-date, and key
 127 revokations and expirations can be processed in a timely manor.
 128
 129 .SH FILES
 130
 131 .TP
 132 /etc/monkeysphere/monkeysphere-server.conf
 133 System monkeysphere-server config file.
 134 .TP
 135 /etc/monkeysphere/monkeysphere.conf
 136 System-wide monkeysphere config file.
 137 .TP
 138 /var/lib/monkeysphere/authorized_keys/USER
 139 Monkeysphere-generated user authorized_keys files.
 140 .TP
 141 /var/lib/monkeysphere/ssh_host_rsa_key
 142 Copy of the host's private key in ssh format, suitable for use by
 143 sshd.
 144 .TP
 145 /var/lib/monkeysphere/gnupg-host
 146 Monkeysphere host GNUPG home directory.
 147 .TP
 148 /var/lib/monkeysphere/gnupg-authentication
 149 Monkeysphere authentication GNUPG home directory.
 150
 151 .SH AUTHOR
 152
 153 Written by Jameson Rollins <jrollins@fifthhorseman.net>
 154
 155 .SH SEE ALSO
 156
 157 .BR monkeysphere (1),
 158 .BR gpg (1),
 159 .BR ssh (1)