diff options
| author | Wilmer van der Gaast <wilmer@gaast.net> | 2010-10-09 11:41:19 -0700 |
|---|---|---|
| committer | Wilmer van der Gaast <wilmer@gaast.net> | 2010-10-09 11:41:19 -0700 |
| commit | 619770237590e4a760346f2e12681d7e2220dda4 (patch) | |
| tree | 8d0d391407280ab74e1fc876d6f272110b474897 /doc/user-guide | |
| parent | 23b29c67968f3dd39e7d6970acc5669556f4c8b9 (diff) | |
| parent | 27b407fde1844a0e03f1a9d92d2a1c4a40435f9b (diff) | |
Merging OTR branch. It's more or less a plugin if you enable it, and
otherwise a no-op. DO NOT INSTALL THIS ON PUBLIC SERVERS.
Diffstat (limited to 'doc/user-guide')
| -rw-r--r-- | doc/user-guide/commands.xml | 202 |
1 files changed, 202 insertions, 0 deletions
diff --git a/doc/user-guide/commands.xml b/doc/user-guide/commands.xml index 6adc4001..6ccaab8c 100644 --- a/doc/user-guide/commands.xml +++ b/doc/user-guide/commands.xml @@ -366,6 +366,184 @@ </para> </description> </bitlbee-command> + + <bitlbee-command name="otr"> + <short-description>Off-the-Record encryption control</short-description> + <syntax>otr <subcommand> [<arguments>]</syntax> + + <description> + + <para> + Available subcommands: connect, disconnect, smp, smpq, trust, info, keygen, and forget. See <emphasis>help otr <subcommand></emphasis> for more information. + </para> + + </description> + + <bitlbee-command name="connect"> + <syntax>otr connect <nick></syntax> + + <description> + + <para> + Attempts to establish an encrypted connection with the specified user by sending a magic string. + </para> + + </description> + + </bitlbee-command> + + <bitlbee-command name="disconnect"> + <syntax>otr disconnect <nick></syntax> + + <description> + + <para> + Resets the connection with the specified user to cleartext. + </para> + + </description> + + </bitlbee-command> + + <bitlbee-command name="smp"> + <syntax>otr smp <nick> <secret></syntax> + + <description> + + <para> + Attempts to authenticate the given user's active fingerprint via the Socialist Millionaires' Protocol. + </para> + + <para> + If an SMP challenge has been received from the given user, responds with the specified secret/answer. Otherwise, sends a challenge for the given secret. + </para> + + <para> + Note that there are two flavors of SMP challenges: "shared-secret" and "question & answer". This command is used to respond to both of them, or to initiate a shared-secret style exchange. Use the <emphasis>otr smpq</emphasis> command to initiate a "Q&A" session. + </para> + + <para> + When responding to a "Q&A" challenge, the local trust value is not altered. Only the <emphasis>asking party</emphasis> sets trust in the case of success. Use <emphasis>otr smpq</emphasis> to pose your challenge. In a shared-secret exchange, both parties set their trust according to the outcome. + </para> + + </description> + + </bitlbee-command> + + <bitlbee-command name="smpq"> + <syntax>otr smpq <nick> <question> <answer></syntax> + + <description> + + <para> + Attempts to authenticate the given user's active fingerprint via the Socialist Millionaires' Protocol, Q&A style. + </para> + + <para> + Initiates an SMP session in "question & answer" style. The question is transmitted with the initial SMP packet and used to prompt the other party. You must be confident that only they know the answer. If the protocol succeeds (i.e. they answer correctly), the fingerprint will be trusted. Note that the answer must be entered exactly, case and punctuation count! + </para> + + <para> + Note that this style of SMP only affects the trust setting on your side. Expect your opponent to send you their own challenge. Alternatively, if you and the other party have a shared secret, use the <emphasis>otr smp</emphasis> command. + </para> + + </description> + + </bitlbee-command> + + <bitlbee-command name="trust"> + <syntax>otr trust <nick> <fp1> <fp2> <fp3> <fp4> <fp5></syntax> + + <description> + + <para> + Manually affirms trust in the specified fingerprint, given as five blocks of precisely eight (hexadecimal) digits each. + </para> + + </description> + + </bitlbee-command> + + <bitlbee-command name="info"> + <syntax>otr info</syntax> + <syntax>otr info <nick></syntax> + + <description> + + <para> + Shows information about the OTR state. The first form lists our private keys and current OTR contexts. The second form displays information about the connection with a given user, including the list of their known fingerprints. + </para> + + </description> + + </bitlbee-command> + + <bitlbee-command name="keygen"> + <syntax>otr keygen <account-no></syntax> + + <description> + + <para> + Generates a new OTR private key for the given account. + </para> + + </description> + + </bitlbee-command> + + <bitlbee-command name="forget"> + <syntax>otr forget <thing> <arguments></syntax> + + <description> + + <para> + Forgets some part of our OTR userstate. Available things: fingerprint, context, and key. See <emphasis>help otr forget <thing></emphasis> for more information. + </para> + + </description> + + <bitlbee-command name="fingerprint"> + <syntax>otr forget fingerprint <nick> <fingerprint></syntax> + + <description> + + <para> + Drops the specified fingerprint from the given user's OTR connection context. It is allowed to specify only a (unique) prefix of the desired fingerprint. + </para> + + </description> + + </bitlbee-command> + + <bitlbee-command name="context"> + <syntax>otr forget context <nick></syntax> + + <description> + + <para> + Forgets the entire OTR context associated with the given user. This includes current message and protocol states, as well as any fingerprints for that user. + </para> + + </description> + + </bitlbee-command> + + <bitlbee-command name="key"> + <syntax>otr forget key <fingerprint></syntax> + + <description> + + <para> + Forgets an OTR private key matching the specified fingerprint. It is allowed to specify only a (unique) prefix of the fingerprint. + </para> + + </description> + + </bitlbee-command> + + </bitlbee-command> + + </bitlbee-command> <bitlbee-command name="set"> <short-description>Miscellaneous settings</short-description> @@ -590,6 +768,16 @@ </bitlbee-setting> + <bitlbee-setting name="color_encrypted" type="boolean" scope="global"> + <default>true</default> + + <description> + <para> + If set to true, BitlBee will color incoming encrypted messages according to their fingerprint trust level: untrusted=red, trusted=green. + </para> + </description> + </bitlbee-setting> + <bitlbee-setting name="control_channel" type="string" scope="global"> <default>&bitlbee</default> @@ -930,6 +1118,20 @@ </description> </bitlbee-setting> + <bitlbee-setting name="otr_policy" type="string" scope="global"> + <default>opportunistic</default> + <possible-values>never, opportunistic, manual, always</possible-values> + + <description> + <para> + This setting controls the policy for establishing Off-the-Record connections. + </para> + <para> + A value of "never" effectively disables the OTR subsystem. In "opportunistic" mode, a magic whitespace pattern will be appended to the first message sent to any user. If the peer is also running opportunistic OTR, an encrypted connection will be set up automatically. On "manual", on the other hand, OTR connections must be established explicitly using <emphasis>otr connect</emphasis>. Finally, the setting "always" enforces encrypted communication by causing BitlBee to refuse to send any cleartext messages at all. + </para> + </description> + </bitlbee-setting> + <bitlbee-setting name="password" type="string" scope="both"> <description> <para> |