diff options
Diffstat (limited to 'man/man8/monkeysphere-authentication.8')
| -rw-r--r-- | man/man8/monkeysphere-authentication.8 | 168 |
1 files changed, 168 insertions, 0 deletions
diff --git a/man/man8/monkeysphere-authentication.8 b/man/man8/monkeysphere-authentication.8 new file mode 100644 index 0000000..68a7a1b --- /dev/null +++ b/man/man8/monkeysphere-authentication.8 @@ -0,0 +1,168 @@ +.TH MONKEYSPHERE-SERVER "8" "June 2008" "monkeysphere" "User Commands" + +.SH NAME + +monkeysphere-authentication \- Monkeysphere authentication admin tool. + +.SH SYNOPSIS + +.B monkeysphere-authentication \fIsubcommand\fP [\fIargs\fP] +.br +.B monkeysphere-authentication expert \fIexpert-subcommand\fP [\fIargs\fP] + +.SH DESCRIPTION + +\fBMonkeysphere\fP is a framework to leverage the OpenPGP web of trust for +OpenSSH authentication. OpenPGP keys are tracked via GnuPG, and added to the +authorized_keys and known_hosts files used by OpenSSH for connection +authentication. + +\fBmonkeysphere-authentication\fP is a Monkeysphere server admin utility. + +.SH SUBCOMMANDS +\fBmonkeysphere-authentication\fP takes various subcommands.(Users may use the +abbreviated subcommand in parentheses): + +.TP +.B update-users (u) [ACCOUNT]... +Rebuild the monkeysphere-controlled authorized_keys files. For each specified +account, the user ID's listed in the account's authorized_user_ids file are +processed. For each user ID, gpg will be queried for keys associated with that +user ID, optionally querying a keyserver. If an acceptable key is found (see +KEY ACCEPTABILITY in monkeysphere(7)), the key is added to the account's +monkeysphere-controlled authorized_keys file. If the RAW_AUTHORIZED_KEYS +variable is set, then a separate authorized_keys file (usually +~USER/.ssh/authorized_keys) is appended to the monkeysphere-controlled +authorized_keys file. If no accounts are specified, then all accounts on the +system are processed. `u' may be used in place of `update-users'. + +\" XXX + +.TP +.B add-id-certifier (c+) KEYID +Instruct system to trust user identity certifications made by KEYID. +Using the `-n' or `--domain' option allows you to indicate that you +only trust the given KEYID to make identifications within a specific +domain (e.g. "trust KEYID to certify user identities within the +@example.org domain"). A certifier trust level can be specified with +the `-t' or `--trust' option (possible values are `marginal' and +`full' (default is `full')). A certifier trust depth can be specified +with the `-d' or `--depth' option (default is 1). `c+' may be used in +place of `add-id-certifier'. +.TP +.B remove-id-certifier (c-) KEYID +Instruct system to ignore user identity certifications made by KEYID. +`c-' may be used in place of `remove-id-certifier'. +.TP +.B list-id-certifiers (c) +List key IDs trusted by the system to certify user identities. `c' +may be used in place of `list-id-certifiers'. +.TP +.B help +Output a brief usage summary. `h' or `?' may be used in place of +`help'. +.TP +.B version +show version number + +.SH "EXPERT" SUBCOMMANDS +Some commands are very unlikely to be needed by most administrators. +These commands must follow the word `expert'. +.TP +.B diagnostics (d) +Review the state of the server with respect to authentication. +.TP +.B gpg-cmd +Execute a gpg command on the gnupg-authentication keyring as the +monkeysphere user. This takes a single command (multiple gpg +arguments need to be quoted). Use this command with caution, as +modifying the gnupg-authentication keyring can affect ssh user +authentication. + +.SH SETUP + +If the server will handle user authentication through +monkeysphere-generated authorized_keys files, the server must be told +which keys will act as identity certifiers. This is done with the +\fBadd-id-certifier\fP command: + +$ monkeysphere-authentication add-id-certifier KEYID + +where KEYID is the key ID of the server admin, or whoever's +certifications should be acceptable to the system for the purposes of +authenticating remote users. You can run this command multiple times +to indicate that multiple certifiers are trusted. You may also +specify a filename instead of a key ID, as long as the file contains a +single OpenPGP public key. Certifiers can be removed with the +\fBremove-id-certifier\fP command, and listed with the +\fBlist-id-certifiers\fP command. + +Remote users will then be granted access to a local account based on +the appropriately-signed and valid keys associated with user IDs +listed in that account's authorized_user_ids file. By default, the +authorized_user_ids file for an account is +~/.monkeysphere/authorized_user_ids. This can be changed in the +monkeysphere-authentication.conf file. + +The \fBupdate-users\fP command can then be used to generate +authorized_keys file for local accounts based on the authorized user +IDs listed in the account's authorized_user_ids file: + +$ monkeysphere-authentication update-users USER + +Not specifying USER will cause all accounts on the system to updated. +sshd can then use these monkeysphere generated authorized_keys files +to grant access to user accounts for remote users. You must also tell +sshd to look at the monkeysphere-generated authorized_keys file for +user authentication by setting the following in the sshd_config: + +AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u + +It is recommended to add "monkeysphere-authentication update-users" to a +system crontab, so that user keys are kept up-to-date, and key +revocations and expirations can be processed in a timely manner. + +.SH ENVIRONMENT + +The following environment variables will override those specified in +(defaults in parentheses): +.TP +MONKEYSPHERE_MONKEYSPHERE_USER +User to control authentication keychain (monkeysphere). +.TP +MONKEYSPHERE_LOG_LEVEL +Set the log level (INFO). Can be SILENT, ERROR, INFO, VERBOSE, DEBUG, in +increasing order of verbosity. +.TP +MONKEYSPHERE_KEYSERVER +OpenPGP keyserver to use (subkeys.pgp.net). +.TP +MONKEYSPHERE_AUTHORIZED_USER_IDS +Path to user authorized_user_ids file +(%h/.monkeysphere/authorized_user_ids). +.TP +MONKEYSPHERE_RAW_AUTHORIZED_KEYS +Path to user-controlled authorized_keys file. `-' means not to add +user-controlled file (%h/.ssh/authorized_keys). + +.SH FILES + +.TP +/etc/monkeysphere/monkeysphere-authentication.conf +System monkeysphere-authentication config file. +.TP +/var/lib/monkeysphere/authentication/authorized_keys/USER +Monkeysphere-generated user authorized_keys files. + +.SH AUTHOR + +Written by Jameson Rollins <jrollins@fifthhorseman.net>, Daniel Kahn +Gillmor <dkg@fifthhorseman.net> + +.SH SEE ALSO + +.BR monkeysphere (1), +.BR monkeysphere-host (8), +.BR monkeysphere (7), +.BR gpg (1), +.BR ssh (1) |