summaryrefslogtreecommitdiff
path: root/man/man1/monkeysphere.1
blob: 6abd36c6caafcfb679428e9ba7ab920395360b2f (plain)
  1. .TH MONKEYSPHERE "1" "June 2008" "monkeysphere 0.1" "User Commands"
  2. .SH NAME
  3. monkeysphere - Monkeysphere client user interface
  4. .SH SYNOPSIS
  5. .B monkeysphere \fIsubcommand\fP [\fIargs\fP]
  6. .SH DESCRIPTION
  7. \fBMonkeysphere\fP is a framework to leverage the OpenPGP web of trust
  8. for OpenSSH and TLS key-based authentication. OpenPGP keys are
  9. tracked via GnuPG, and added to the authorized_keys and known_hosts
  10. files used by OpenSSH for connection authentication. Monkeysphere can
  11. also be used by a validation agent to validate TLS connections
  12. (e.g. https).
  13. \fBmonkeysphere\fP is the Monkeysphere client utility.
  14. .SH SUBCOMMANDS
  15. \fBmonkeysphere\fP takes various subcommands:
  16. .TP
  17. .B update\-known_hosts [HOST]...
  18. Update the known_hosts file. For each specified host, gpg will be
  19. queried for a key associated with the host URI (see HOST
  20. IDENTIFICATION in
  21. .BR monkeysphere(7)),
  22. optionally querying a keyserver.
  23. If an acceptable key is found for the host (see KEY ACCEPTABILITY in
  24. .BR monkeysphere(7)),
  25. the key is added to the user's known_hosts file. If a key is found
  26. but is unacceptable for the host, any matching keys are removed from
  27. the user's known_hosts file. If no gpg key is found for the host,
  28. nothing is done. If no hosts are specified, all hosts listed in the
  29. known_hosts file will be processed. This subcommand will exit with a
  30. status of 0 if at least one acceptable key was found for a specified
  31. host, 1 if no matching keys were found at all, and 2 if matching keys
  32. were found but none were acceptable. `k' may be used in place of
  33. `update\-known_hosts'.
  34. .TP
  35. .B update\-authorized_keys
  36. Update the authorized_keys file for the user executing the command
  37. (see MONKEYSPHERE_AUTHORIZED_KEYS in ENVIRONMENT, below). First all
  38. monkeysphere keys are cleared from the authorized_keys file. Then,
  39. for each user ID in the user's authorized_user_ids file, gpg will be
  40. queried for keys associated with that user ID, optionally querying a
  41. keyserver. If an acceptable key is found (see KEY ACCEPTABILITY in
  42. .BR monkeysphere (7)),
  43. the key is added to the user's authorized_keys file.
  44. If a key is found but is unacceptable for the user ID, any matching
  45. keys are removed from the user's authorized_keys file. If no gpg key
  46. is found for the user ID, nothing is done. This subcommand will exit
  47. with a status of 0 if at least one acceptable key was found for a user
  48. ID, 1 if no matching keys were found at all, and 2 if matching keys
  49. were found but none were acceptable. `a' may be used in place of
  50. `update\-authorized_keys'.
  51. .TP
  52. .B gen\-subkey [KEYID]
  53. Generate an authentication subkey for a private key in your GnuPG
  54. keyring. KEYID is the key ID for the primary key for which the subkey
  55. with "authentication" capability will be generated. If no key ID is
  56. specified, but only one key exists in the secret keyring, that key
  57. will be used. The length of the generated key can be specified with
  58. the `\-\-length' or `\-l' option. `g' may be used in place of
  59. `gen\-subkey'.
  60. .TP
  61. .B ssh\-proxycommand [--no-connect] HOST [PORT]
  62. An ssh ProxyCommand that can be used to trigger a monkeysphere update
  63. of the ssh known_hosts file for a host that is being connected to with
  64. ssh. This works by updating the known_hosts file for the host first,
  65. before an attempted connection to the host is made. Once the
  66. known_hosts file has been updated, a TCP connection to the host is
  67. made by exec'ing netcat(1). Regular ssh communication is then done
  68. over this netcat TCP connection (see ProxyCommand in ssh_config(5) for
  69. more info).
  70. This command is meant to be run as the ssh "ProxyCommand". This can
  71. either be done by specifying the proxy command on the command line:
  72. .B ssh \-o ProxyCommand="monkeysphere ssh\-proxycommand %h %p" ...
  73. or by adding the following line to your ~/.ssh/config script:
  74. .B ProxyCommand monkeysphere ssh\-proxycommand %h %p
  75. The script can easily be incorporated into other ProxyCommand scripts
  76. by calling it with the "\-\-no\-connect" option, i.e.:
  77. .B monkeysphere ssh\-proxycommand \-\-no\-connect "$HOST" "$PORT"
  78. This will run everything except the final exec of netcat to make the
  79. TCP connection to the host. In this way this command can be added to
  80. another proxy command that does other stuff, and then makes the
  81. connection to the host itself.
  82. KEYSERVER CHECKING:
  83. The proxy command has a fairly nuanced policy for when keyservers are
  84. queried when processing a host. If the host userID is not found in
  85. either the user's keyring or in the known_hosts file, then the
  86. keyserver is queried for the host userID. If the host userID is found
  87. in the user's keyring, then the keyserver is not checked. This
  88. assumes that the keyring is kept up-to-date, in a cronjob or the like,
  89. so that revocations are properly handled. If the host userID is not
  90. found in the user's keyring, but the host is listed in the known_hosts
  91. file, then the keyserver is not checked. This last policy might
  92. change in the future, possibly by adding a deferred check, so that
  93. hosts that go from non-monkeysphere-enabled to monkeysphere-enabled
  94. will be properly checked.
  95. Setting the CHECK_KEYSERVER variable in the config file or the
  96. MONKEYSPHERE_CHECK_KEYSERVER environment variable to either `true' or
  97. `false' will override the keyserver-checking policy defined above and
  98. either always or never check the keyserver for host key updates.
  99. .TP
  100. .B subkey\-to\-ssh\-agent [ssh\-add arguments]
  101. Push all authentication-capable subkeys in your GnuPG secret keyring
  102. into your running ssh-agent. Additional arguments are passed through
  103. to
  104. .BR ssh\-add (1).
  105. For example, to remove the authentication subkeys, pass an additional
  106. `\-d' argument. To require confirmation on each use of the key, pass
  107. `\-c'. The MONKEYSPHERE_SUBKEYS_FOR_AGENT environment can be used to
  108. specify the full fingerprints of specific keys to add to the agent
  109. (space separated), instead of adding them all. `s' may be used in
  110. place of `subkey\-to\-ssh\-agent'.
  111. .TP
  112. .B sshfpr KEYID
  113. Output the ssh fingerprint of a key in your gpg keyring. `f' may be
  114. used in place of `fingerprint'.
  115. .TP
  116. .B keys\-for\-userid USERID
  117. Output to stdout all acceptable keys for a given user ID literal.
  118. `u' may be used in place of `keys\-for\-userid'.
  119. .TP
  120. .B version
  121. Show the monkeysphere version number. `v' may be used in place of
  122. `version'.
  123. .TP
  124. .B help
  125. Output a brief usage summary. `h' or `?' may be used in place of
  126. `help'.
  127. .SH ENVIRONMENT
  128. The following environment variables will override those specified in
  129. the monkeysphere.conf configuration file (defaults in parentheses):
  130. .TP
  131. MONKEYSPHERE_LOG_LEVEL
  132. Set the log level. Can be SILENT, ERROR, INFO, VERBOSE, DEBUG,
  133. in increasing order of verbosity. (INFO)
  134. .TP
  135. MONKEYSPHERE_GNUPGHOME, GNUPGHOME
  136. GnuPG home directory. (~/.gnupg)
  137. .TP
  138. MONKEYSPHERE_KEYSERVER
  139. OpenPGP keyserver to use. (pool.sks-keyservers.net)
  140. .TP
  141. MONKEYSPHERE_CHECK_KEYSERVER
  142. Whether or not to check keyserver when making gpg queries. (true)
  143. .TP
  144. MONKEYSPHERE_KNOWN_HOSTS
  145. Path to ssh known_hosts file. (~/.ssh/known_hosts)
  146. .TP
  147. MONKEYSPHERE_HASH_KNOWN_HOSTS
  148. Whether or not to hash to the known_hosts file entries. (true)
  149. .TP
  150. MONKEYSPHERE_AUTHORIZED_KEYS
  151. Path to ssh authorized_keys file. (~/.ssh/authorized_keys)
  152. .TP
  153. MONKEYSPHERE_PROMPT
  154. If set to `false', never prompt the user for confirmation. (true)
  155. .TP
  156. MONKEYSPHERE_STRICT_MODES
  157. If set to `false', ignore too-loose permissions on known_hosts,
  158. authorized_keys, and authorized_user_ids files. NOTE: setting this to
  159. false may expose you to abuse by other users on the system. (true)
  160. .TP
  161. MONKEYSPHERE_SUBKEYS_FOR_AGENT
  162. A space-separated list of authentication-capable subkeys to add to the
  163. ssh agent with subkey-to-ssh-agent.
  164. .SH FILES
  165. .TP
  166. ~/.monkeysphere/monkeysphere.conf
  167. User monkeysphere config file.
  168. .TP
  169. /etc/monkeysphere/monkeysphere.conf
  170. System-wide monkeysphere config file.
  171. .TP
  172. ~/.monkeysphere/authorized_user_ids
  173. A list of OpenPGP user IDs, one per line. OpenPGP keys with an
  174. exactly-matching User ID (calculated valid by the designated identity
  175. certifiers), will have any valid authorization-capable keys or subkeys
  176. added to the given user's authorized_keys file.
  177. .SH AUTHOR
  178. Written by:
  179. Jameson Rollins <jrollins@fifthhorseman.net>,
  180. Daniel Kahn Gillmor <dkg@fifthhorseman.net>
  181. .SH SEE ALSO
  182. .BR monkeysphere\-host (8),
  183. .BR monkeysphere\-authentication (8),
  184. .BR monkeysphere (7),
  185. .BR ssh (1),
  186. .BR ssh\-add (1),
  187. .BR gpg (1)