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.  OpenPGP keys are tracked via GnuPG, and added
  15 to the ssh authorized_keys and known_hosts files to be used for
  16 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 admin-controlled authorized_keys files at
  26 /var/cache/monkeysphere/authorized_keys/USER.  For each specified
  27 user, the user ID's listed in the user's authorized_user_ids file are
  28 processed.  For each user ID, gpg will be queried for keys associated
  29 with that user ID, querying a keyserver if specified.  If a key is
  30 found, it will be converted to an ssh key, and any matching ssh keys
  31 will be removed from the user's authorized_keys file.  If the found
  32 key is acceptable (see KEY ACCEPTABILITY), then the key will be
  33 updated and re-added to the authorized_keys file.  If no gpg key is
  34 found for the user ID, then nothing is done.  If the
  35 RAW_AUTHORIZED_KEYS variable is set, then a user-controlled
  36 authorized_keys file (usually ~USER/.ssh/authorized_keys) is added to
  37 the authorized_keys file.  If no users are specified, then all users
  38 listed in /etc/passwd are processed.  `u' may be used in place of
  39 `update-users.
  40 .TP
  41 .B gen-key
  42 Generate a OpenPGP key pair for the host.  `g' may be used in place of
  43 `gen-key'.
  44 .TP
  45 .B show-fingerprint
  46 Show the fingerprint for the host's OpenPGP key.  `f' may be used in place of
  47 `show-fingerprint'.
  48 .TP
  49 .B publish-key
  50 Publish the host's OpenPGP key to the keyserver.  `p' may be used in
  51 place of `publish-key'.
  52 .TP
  53 .B add-certifier KEYID
  54 Add a certifier key to host keyring.  The key with specified key ID
  55 will be retrieved from the keyserver and imported to the host keyring.
  56 It will then be given a non-exportable trust signature, with default
  57 depth of 1, so that the key may certifier users to log into the
  58 system.  `a' may be used in place of `add-certifier'.
  59 .TP
  60 .B remove-certifier KEYID
  61 Remove a certifier key from the host keyring.  The key with specified
  62 key ID will be removed entirely from the host keyring so that the key
  63 will not longer be able to certify users on the system.  `r' may be
  64 used in place of `remove-certifier'.
  65 .TP
  66 .B list-certifiers
  67 List certifier keys.  `l' may be used in place of `list-certifiers'.
  68 .TP
  69 .B help
  70 Output a brief usage summary.  `h' or `?' may be used in place of
  71 `help'.
  72
  73 .SH SETUP
  74
  75 In order to start using the monkeysphere, you must first generate an
  76 OpenPGP key for the server and convert that key to an ssh key that can
  77 be used by ssh for host authentication.  This can be done with the
  78 \fBgen-key\fP subcommand:
  79
  80 $ monkeysphere-server gen-key
  81
  82 To enable host verification via the monkeysphere, you must then
  83 publish the host's key to the Web of Trust using the \fBpublish-key\fP
  84 command to push the key to a keyserver.  Then modify the sshd_config
  85 to tell sshd where the new server host key is located:
  86
  87 HostKey /var/lib/monkeysphere/ssh_host_rsa_key
  88
  89 In order for users logging into the system to be able to verify the
  90 host via the monkeysphere, at least one person (ie. a server admin)
  91 will need to sign the host's key.  This is done in the same way that
  92 key signing is usually done, by pulling the host's key from the
  93 keyserver, signing the key, and re-publishing the signature.  Once
  94 that is done, users logging into the host will be able to certify the
  95 host's key via the signature of the host admin.
  96
  97 If the server will also handle user authentication through
  98 monkeysphere-generated authorized_keys files, the server must be told
  99 which keys will act as user certifiers.  This is done with the
 100 \fBadd-certifier\fP command:
 101
 102 $ monkeysphere-server add-certifier KEYID
 103
 104 where KEYID is the key ID of the server admin, or whoever's signature
 105 will be certifying users to the system.  Certifiers can be later
 106 remove with the \fBremove-certifier\fP command, and listed with the
 107 \fBlist-certifiers\fP command.
 108
 109 Remote user's will then be granted access to a local user account
 110 based on the appropriately signed and valid keys associated with user
 111 IDs listed in the authorized_user_ids file of the local user.  By
 112 default, the authorized_user_ids file for local users is found in
 113 ~/.config/monkeysphere/authorized_user_ids.  This can be changed in
 114 the monkeysphere-server.conf file.
 115
 116 The \fBupdate-users\fP command can then be used to generate
 117 authorized_keys file for local users based on the authorized user IDs
 118 listed in the user's authorized_user_ids file:
 119
 120 $ monkeysphere-server update-users USER
 121
 122 sshd can then use these files to grant access to user accounts for
 123 remote users.  If no user is specified, authorized_keys files will be
 124 generated for all users on the system.  You must also tell sshd to
 125 look at the monkeysphere-generated authorized_keys file for user
 126 authentication by setting the following in the sshd_config:
 127
 128 AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u
 129
 130 It is recommended to add "monkeysphere-server update-users" to a
 131 system crontab, so that user keys are kept up-to-date, and key
 132 revokations and expirations can be processed in a timely manor.
 133
 134 .SH KEY ACCEPTABILITY
 135
 136 GPG keys are considered acceptable if the following criteria are met:
 137 .TP
 138 .B capability
 139 The key must have the "authentication" ("a") usage flag set.
 140 .TP
 141 .B validity
 142 The key must be "fully" valid (ie. signed by a trusted certifier), and
 143 must not be expired or revoked.
 144
 145 .SH FILES
 146
 147 .TP
 148 /etc/monkeysphere/monkeysphere-server.conf
 149 System monkeysphere-server config file.
 150 .TP
 151 /etc/monkeysphere/monkeysphere.conf
 152 System-wide monkeysphere config file.
 153 .TP
 154 /var/lib/monkeysphere/authorized_keys/USER
 155 Monkeysphere-generated user authorized_keys files.
 156 .TP
 157 /var/lib/monkeysphere/ssh_host_rsa_key
 158 Copy of the host's private key in ssh format, suitable for use by
 159 sshd.
 160 .TP
 161 /var/lib/monkeysphere/gnupg-host
 162 Monkeysphere host GNUPG home directory.
 163 .TP
 164 /var/lib/monkeysphere/gnupg-authentication
 165 Monkeysphere authentication GNUPG home directory.
 166
 167 .SH AUTHOR
 168
 169 Written by Jameson Rollins <jrollins@fifthhorseman.net>
 170
 171 .SH SEE ALSO
 172
 173 .BR monkeysphere (1),
 174 .BR gpg (1),
 175 .BR ssh (1)