man/man1/monkeysphere.1

   1 .TH MONKEYSPHERE "1" "June 2008" "monkeysphere 0.1" "User Commands"
   2
   3 .SH NAME
   4
   5 monkeysphere \- MonkeySphere client user interface
   6
   7 .SH SYNOPSIS
   8
   9 .B monkeysphere \fIcommand\fP [\fIargs\fP]
  10
  11 .SH DESCRIPTION
  12
  13 MonkeySphere is a system to leverage the OpenPGP Web of Trust for ssh
  14 authentication and encryption.  OpenPGP keys are tracked via GnuPG,
  15 and added to the ssh authorized_keys and known_hosts files to be used
  16 for authentication and encryption of ssh connection.
  17
  18 \fBmonkeysphere\fP is the MonkeySphere client utility.
  19
  20 .SH SUBCOMMANDS
  21
  22 \fBmonkeysphere\fP takes various subcommands:
  23 .TP
  24 .B update-known_hosts [HOST]...
  25 Update the known_hosts file.  For each specified host, gpg will be
  26 queried for a key associated with the host URI (see HOST URIs),
  27 querying a keyserver if none is found in the user's keychain. search
  28 for a gpg key for the host in the Web of Trust.  If a key is found, it
  29 will be added to the host_keys cache (see KEY CACHES) and any ssh keys
  30 for the host will be removed from the user's known_hosts file.  If the
  31 found key is acceptable (see KEY ACCEPTABILITY), then the host's gpg
  32 key will be added to the known_hosts file.  If no gpg key is found for
  33 the host, then nothing is done.  If no hosts are specified, all hosts
  34 listed in the known_hosts file will be processed.  `k' may be used in
  35 place of `update-known_hosts'.
  36 .TP
  37 .B update-userids [USERID]...
  38 Add/update a user ID to the authorized_user_ids file.  The user IDs
  39 specified should be exact matches to OpenPGP user IDs.  For each
  40 specified user ID, gpg will be queried for a key associated with that
  41 user ID, querying a keyserver if none is found in the user's keychain.
  42 If a key is found, it will be added to the user_keys cache (see KEY
  43 CACHES) and the user ID will be added to the user's
  44 authorized_user_ids file (if it wasn't already present).  `u' may be
  45 used in place of `update-userids'.
  46 .TP
  47 .B remove-userids [USERID]...
  48 Remove a user ID from the authorized_user_ids file.  The user IDs
  49 specified should be exact matches to OpenPGP user IDs.  `r' may be
  50 used in place of `remove-userids'.
  51 .TP
  52 .B update-authorized_keys
  53 Update the monkeysphere authorized_keys file.  The monkeysphere
  54 authorized_keys file will be regenerated from the valid keys in the
  55 user_key cache, and the user's independently controlled
  56 authorized_keys file (usually ~/.ssh/authorized_keys).  `a' may be
  57 used in place of `update-authorized_keys'.
  58 .TP
  59 .B gen-subkey KEYID
  60 Generate an `a` capable subkey.  For the primary key with the
  61 specified key ID, generate a subkey with "authentication" capability
  62 that can be used for MonkeySphere transactions.  `g' may be used in
  63 place of `gen-subkey'.
  64 .TP
  65 .B help
  66 Output a brief usage summary.  `h' or `?' may be used in place of
  67 `help'.
  68
  69 .SH HOST URIs
  70
  71 Host OpenPGP keys have associated user IDs that use the ssh URI
  72 specification for the host, ie. "ssh://host.full.domain".
  73
  74 .SH KEY ACCEPTABILITY
  75
  76 GPG keys are considered acceptable if the following criteria are met:
  77 .TP
  78 .B capability
  79 For host keys, the key must have both the "authentication" ("a") and
  80 "encrypt" ("e") capability flags.  For user keys, the key must have
  81 the "authentication" ("a") capability flag.
  82 .TP
  83 .B validity
  84 The key must be "fully" valid, and must not be expired or revoked.
  85
  86 .SH KEY CACHES
  87
  88 Monkeysphere keeps track of keys in key cache directories.  The files
  89 in the cache are named with the format "USERID_HASH.PUB_KEY_ID", where
  90 USERID_HASH is a hash of the exact OpenPGP user ID, and PUB_KEY_ID is
  91 the key ID of the primary key.  If the user/key ID combo exists in the
  92 Web of Trust but is not acceptable, then the file is empty.  If the
  93 primary key has at least one acceptable sub key, then an ssh-style
  94 key, converted from the OpenPGP key, of all acceptable subkeys will be
  95 stored in the cache file, one per line.  known_hosts style key lines
  96 will be stored in the host_keys cache files, and authorized_keys style
  97 key lines will be stored in the user_keys cache files.  OpenPGP keys
  98 are converted to ssh-style keys with the openpgp2ssh utility (see `man
  99 openpgp2ssh').
 100
 101 .SH FILES
 102
 103 .TP
 104 ~/.config/monkeysphere/monkeysphere.conf
 105 User monkeysphere config file.
 106 .TP
 107 /etc/monkeysphere/monkeysphere.conf
 108 System-wide monkeysphere config file.
 109 .TP
 110 ~/.config/monkeysphere/authorized_user_ids
 111 OpenPGP user IDs associated with keys that will be checked for
 112 addition to the authorized_keys file.
 113 .TP
 114 ~/.config/monkeysphere/authorized_keys
 115 Monkeysphere generated authorized_keys file.
 116 .TP
 117 ~/.config/monkeysphere/user_keys
 118 User keys cache directory.
 119 .TP
 120 ~/.config/monkeysphere/host_keys
 121 Host keys cache directory.
 122
 123 .SH AUTHOR
 124
 125 Written by Jameson Rollins <jrollins@fifthhorseman.net>
 126
 127 .SH SEE ALSO
 128
 129 .BR monkeysphere-ssh-proxycommand (1),
 130 .BR monkeysphere-server (8),
 131 .BR ssh (1),
 132 .BR gpg (1)