summaryrefslogtreecommitdiff
path: root/man/man1/monkeysphere.1
blob: 0e8004700159d1bd4d88b0691dd779cf664be097 (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. For the primary key with the specified key ID, generate a
  53. subkey with "authentication" capability that can be used for
  54. monkeysphere transactions. An expiration length can be specified with
  55. the `-e' or `--expire' option (prompt otherwise). If no key ID is
  56. specified, but only one key exists in the secret keyring, that key
  57. will be used. `g' may be used in place of `gen-subkey'.
  58. .TP
  59. .B ssh-proxycommand
  60. an ssh proxy command that can be used
  61. to trigger a monkeysphere update of the ssh known_hosts file for a
  62. host that is being connected to with ssh. This works by updating the
  63. known_hosts file for the host first, before an attempted connection to
  64. the host is made. Once the known_hosts file has been updated, a TCP
  65. connection to the host is made by exec'ing netcat(1). Regular ssh
  66. communication is then done over this netcat TCP connection (see
  67. ProxyCommand in ssh_config(5) for 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 MONKEYSPHERE_CHECK_KEYSERVER
  94. variable (to `true' or `false') will override the keyserver-checking policy
  95. defined above.
  96. .TP
  97. .B subkey-to-ssh-agent [ssh-add arguments]
  98. Push all authentication-capable subkeys in your GnuPG secret keyring
  99. into your running ssh-agent. Additional arguments are passed through
  100. to
  101. .BR ssh-add (1).
  102. For example, to remove the authentication subkeys, pass an additional
  103. `-d' argument. To require confirmation on each use of the key, pass
  104. `-c'. `s' may be used in place of `subkey-to-ssh-agent'.
  105. .TP
  106. .B help
  107. Output a brief usage summary. `h' or `?' may be used in place of
  108. `help'.
  109. .SH ENVIRONMENT
  110. The following environment variables will override those specified in
  111. the monkeysphere.conf configuration file (defaults in parentheses):
  112. .TP
  113. MONKEYSPHERE_LOG_LEVEL
  114. Set the log level (INFO). Can be SILENT, ERROR, INFO, VERBOSE, DEBUG,
  115. in increasing order of verbosity.
  116. .TP
  117. MONKEYSPHERE_GNUPGHOME, GNUPGHOME
  118. GnuPG home directory (~/.gnupg).
  119. .TP
  120. MONKEYSPHERE_KEYSERVER
  121. OpenPGP keyserver to use (subkeys.pgp.net).
  122. .TP
  123. MONKEYSPHERE_CHECK_KEYSERVER
  124. Whether or not to check keyserver when making gpg queries (`true').
  125. .TP
  126. MONKEYSPHERE_KNOWN_HOSTS
  127. Path to ssh known_hosts file (~/.ssh/known_hosts).
  128. .TP
  129. MONKEYSPHERE_HASH_KNOWN_HOSTS
  130. Whether or not to hash to the known_hosts file entries (`true').
  131. .TP
  132. MONKEYSPHERE_AUTHORIZED_KEYS
  133. Path to ssh authorized_keys file (~/.ssh/authorized_keys).
  134. .SH FILES
  135. .TP
  136. ~/.monkeysphere/monkeysphere.conf
  137. User monkeysphere config file.
  138. .TP
  139. /etc/monkeysphere/monkeysphere.conf
  140. System-wide monkeysphere config file.
  141. .TP
  142. ~/.monkeysphere/authorized_user_ids
  143. OpenPGP user IDs associated with keys that will be checked for
  144. addition to the authorized_keys file.
  145. .SH AUTHOR
  146. Written by:
  147. Jameson Rollins <jrollins@fifthhorseman.net>,
  148. Daniel Kahn Gillmor <dkg@fifthhorseman.net>
  149. .SH SEE ALSO
  150. .BR monkeysphere-host (8),
  151. .BR monkeysphere-authentication (8),
  152. .BR monkeysphere (7),
  153. .BR ssh (1),
  154. .BR ssh-add (1),
  155. .BR gpg (1)