man/man8/monkeysphere-authentication.8

   1 .TH MONKEYSPHERE-SERVER "8" "June 2008" "monkeysphere" "User Commands"
   2
   3 .SH NAME
   4
   5 monkeysphere-authentication \- Monkeysphere authentication admin tool.
   6
   7 .SH SYNOPSIS
   8
   9 .B monkeysphere-authentication \fIsubcommand\fP [\fIargs\fP]
  10 .br
  11 .B monkeysphere-authentication expert \fIexpert-subcommand\fP [\fIargs\fP]
  12
  13 .SH DESCRIPTION
  14
  15 \fBMonkeysphere\fP is a framework to leverage the OpenPGP web of trust for
  16 OpenSSH authentication.  OpenPGP keys are tracked via GnuPG, and added to the
  17 authorized_keys and known_hosts files used by OpenSSH for connection
  18 authentication.
  19
  20 \fBmonkeysphere-authentication\fP is a Monkeysphere server admin utility.
  21
  22 .SH SUBCOMMANDS
  23 \fBmonkeysphere-authentication\fP takes various subcommands.(Users may use the
  24 abbreviated subcommand in parentheses):
  25
  26 .TP
  27 .B update-users (u) [ACCOUNT]...
  28 Rebuild the monkeysphere-controlled authorized_keys files.  For each specified
  29 account, the user ID's listed in the account's authorized_user_ids file are
  30 processed.  For each user ID, gpg will be queried for keys associated with that
  31 user ID, optionally querying a keyserver.  If an acceptable key is found (see
  32 KEY ACCEPTABILITY in monkeysphere(7)), the key is added to the account's
  33 monkeysphere-controlled authorized_keys file.  If the RAW_AUTHORIZED_KEYS
  34 variable is set, then a separate authorized_keys file (usually
  35 ~USER/.ssh/authorized_keys) is appended to the monkeysphere-controlled
  36 authorized_keys file.  If no accounts are specified, then all accounts on the
  37 system are processed.  `u' may be used in place of `update-users'.
  38
  39 \" XXX
  40
  41 .TP
  42 .B add-id-certifier (c+) KEYID
  43 Instruct system to trust user identity certifications made by KEYID.
  44 Using the `-n' or `--domain' option allows you to indicate that you
  45 only trust the given KEYID to make identifications within a specific
  46 domain (e.g. "trust KEYID to certify user identities within the
  47 @example.org domain").  A certifier trust level can be specified with
  48 the `-t' or `--trust' option (possible values are `marginal' and
  49 `full' (default is `full')).  A certifier trust depth can be specified
  50 with the `-d' or `--depth' option (default is 1).  `c+' may be used in
  51 place of `add-id-certifier'.
  52 .TP
  53 .B remove-id-certifier (c-) KEYID
  54 Instruct system to ignore user identity certifications made by KEYID.
  55 `c-' may be used in place of `remove-id-certifier'.
  56 .TP
  57 .B list-id-certifiers (c)
  58 List key IDs trusted by the system to certify user identities.  `c'
  59 may be used in place of `list-id-certifiers'.
  60 .TP
  61 .B help
  62 Output a brief usage summary.  `h' or `?' may be used in place of
  63 `help'.
  64 .TP
  65 .B version
  66 show version number
  67
  68 .SH "EXPERT" SUBCOMMANDS
  69 Some commands are very unlikely to be needed by most administrators.
  70 These commands must follow the word `expert'.
  71 .TP
  72 .B diagnostics (d)
  73 Review the state of the server with respect to authentication.
  74 .TP
  75 .B gpg-cmd
  76 Execute a gpg command on the gnupg-authentication keyring as the
  77 monkeysphere user.  This takes a single command (multiple gpg
  78 arguments need to be quoted).  Use this command with caution, as
  79 modifying the gnupg-authentication keyring can affect ssh user
  80 authentication.
  81
  82 .SH SETUP
  83
  84 If the server will handle user authentication through
  85 monkeysphere-generated authorized_keys files, the server must be told
  86 which keys will act as identity certifiers.  This is done with the
  87 \fBadd-id-certifier\fP command:
  88
  89 $ monkeysphere-authentication add-id-certifier KEYID
  90
  91 where KEYID is the key ID of the server admin, or whoever's
  92 certifications should be acceptable to the system for the purposes of
  93 authenticating remote users.  You can run this command multiple times
  94 to indicate that multiple certifiers are trusted.  You may also
  95 specify a filename instead of a key ID, as long as the file contains a
  96 single OpenPGP public key.  Certifiers can be removed with the
  97 \fBremove-id-certifier\fP command, and listed with the
  98 \fBlist-id-certifiers\fP command.
  99
 100 Remote users will then be granted access to a local account based on
 101 the appropriately-signed and valid keys associated with user IDs
 102 listed in that account's authorized_user_ids file.  By default, the
 103 authorized_user_ids file for an account is
 104 ~/.monkeysphere/authorized_user_ids.  This can be changed in the
 105 monkeysphere-authentication.conf file.
 106
 107 The \fBupdate-users\fP command can then be used to generate
 108 authorized_keys file for local accounts based on the authorized user
 109 IDs listed in the account's authorized_user_ids file:
 110
 111 $ monkeysphere-authentication update-users USER
 112
 113 Not specifying USER will cause all accounts on the system to updated.
 114 sshd can then use these monkeysphere generated authorized_keys files
 115 to grant access to user accounts for remote users.  You must also tell
 116 sshd to look at the monkeysphere-generated authorized_keys file for
 117 user authentication by setting the following in the sshd_config:
 118
 119 AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u
 120
 121 It is recommended to add "monkeysphere-authentication update-users" to a
 122 system crontab, so that user keys are kept up-to-date, and key
 123 revocations and expirations can be processed in a timely manner.
 124
 125 .SH ENVIRONMENT
 126
 127 The following environment variables will override those specified in
 128 (defaults in parentheses):
 129 .TP
 130 MONKEYSPHERE_MONKEYSPHERE_USER
 131 User to control authentication keychain (monkeysphere).
 132 .TP
 133 MONKEYSPHERE_LOG_LEVEL
 134 Set the log level (INFO).  Can be SILENT, ERROR, INFO, VERBOSE, DEBUG, in
 135 increasing order of verbosity.
 136 .TP
 137 MONKEYSPHERE_KEYSERVER
 138 OpenPGP keyserver to use (subkeys.pgp.net).
 139 .TP
 140 MONKEYSPHERE_AUTHORIZED_USER_IDS
 141 Path to user authorized_user_ids file
 142 (%h/.monkeysphere/authorized_user_ids).
 143 .TP
 144 MONKEYSPHERE_RAW_AUTHORIZED_KEYS
 145 Path to user-controlled authorized_keys file.  `-' means not to add
 146 user-controlled file (%h/.ssh/authorized_keys).
 147
 148 .SH FILES
 149
 150 .TP
 151 /etc/monkeysphere/monkeysphere-authentication.conf
 152 System monkeysphere-authentication config file.
 153 .TP
 154 /var/lib/monkeysphere/authentication/authorized_keys/USER
 155 Monkeysphere-generated user authorized_keys files.
 156
 157 .SH AUTHOR
 158
 159 Written by Jameson Rollins <jrollins@fifthhorseman.net>, Daniel Kahn
 160 Gillmor <dkg@fifthhorseman.net>
 161
 162 .SH SEE ALSO
 163
 164 .BR monkeysphere (1),
 165 .BR monkeysphere-host (8),
 166 .BR monkeysphere (7),
 167 .BR gpg (1),
 168 .BR ssh (1)