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