imported>B42 |
imported>B42 |
| (4 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| This module allows you to encrypt private conversations using the
| | [http://wiki.znc.in/Otr This page has been moved to ZNC wiki.] |
| [https://otr.cypherpunks.ca/ OTR protocol]. Several popular
| |
| [https://otr.cypherpunks.ca/software.php IRC clients] support OTR (usually requiring a plugin).
| |
| | |
| For more information about OTR, see https://otr.cypherpunks.ca/ and https://otr.im/.
| |
| | |
| == Installing ==
| |
| | |
| The module source is available at https://github.com/mmilata/znc-otr. You can
| |
| download a
| |
| [https://github.com/mmilata/znc-otr/archive/master/znc-otr-master.tar.gz tarball]
| |
| directly if you don't want to use git. Once you have the source code,
| |
| follow the instructions for [http://wiki.znc.in/Compiling_modules compiling]
| |
| and [http://wiki.znc.in/Modules#.28Un.29Loading_Modules loading ZNC modules].
| |
| | |
| If your ZNC is running on a virtual server (see
| |
| [[#Security considerations|security considerations]]) it is recommended
| |
| to install an entropy-gathering daemon such as
| |
| [http://www.issihosts.com/haveged/ haveged]. Otherwise the bouncer may get
| |
| stuck waiting for the system to gather entropy.
| |
| | |
| == Usage ==
| |
| | |
| To request OTR-encrypted conversation with someone, send them the message
| |
| ''?OTR?'' in a private conversation. If the request succeeds the module informs
| |
| you about it and requests that you authenticate the other side if you haven't
| |
| previously done so.
| |
| | |
| The module is controlled by sending commands to the ''*otr'' nick. The commands
| |
| are listed below.
| |
| | |
| Please note that otr is a network module meaning that if your account has
| |
| multiple IRC networks then each has its own instance of the module and its own
| |
| ''*otr'' nick.
| |
| | |
| === Commands ===
| |
| | |
| ==== help ====
| |
| Prints the table of available commands together with their short description.
| |
| | |
| ==== info ====
| |
| Shows the table of known fingerprints. The table has five columns:
| |
| | |
| * '''Peer''' - nick on this network the following fingerprints belong to
| |
| * '''State''' - the peer can be in three states:
| |
| ** ''plaintext'' - OTR not active, messages are not encrypted
| |
| ** ''encrypted'' - OTR active, private messages are encrypted
| |
| ** ''finished'' - peer finished the OTR session but we did not (using the finish command) - messages are blocked
| |
| * '''Fingerprint''' - fingerprint of the private key used by the peer
| |
| * '''Act''' - if OTR is active for this nick, asterisk denotes the fingerprint corresponding to the private key used
| |
| * '''Trust''' - whether the fingerprint is trusted:
| |
| ** ''not trusted'' - default state for new unknown fingerprint
| |
| ** ''manual'' - fingerprint set as trusted using the ''trust'' command
| |
| ** ''shared secret'' - fingerprint set as trusted using the ''auth'' or ''authq'' command
| |
| | |
| Example:
| |
| <pre>
| |
| <alice> info
| |
| <*otr> +-------+-----------+----------------------------------------------+-----+---------------+
| |
| <*otr> | Peer | State | Fingerprint | Act | Trust |
| |
| <*otr> +-------+-----------+----------------------------------------------+-----+---------------+
| |
| <*otr> | bob | plaintext | 94A1353B 60A58E73 82CE8999 CBBD7B92 5E9EBB87 | | manual |
| |
| <*otr> | carol | encrypted | 378A8445 3FC3933C 73C917C8 BFE4C18B 5CE65CFC | * | shared secret |
| |
| <*otr> | | | AEB4DEDE 5D025A1C 6A735BD5 7D82385A 7E03E21D | | not trusted |
| |
| <*otr> +-------+-----------+----------------------------------------------+-----+---------------+
| |
| <*otr> Your fingerprint: A305FE90 2B4A8038 03BF89F7 5BBD5595 4B9D209A.
| |
| </pre>
| |
| In this example, we know one fingerprint from bob which we manually verified.
| |
| We currently don't have OTR-encrypted conversation with bob. We have active
| |
| OTR session with carol for whom we have two known fingerprints - the first one
| |
| corresponds to the carol's private key used in our current conversation and has
| |
| been verified using the OTR shared secret authentication mechanism. The other | |
| fingerprint is not currently used (only one is used at a time) and we did not
| |
| verify it really belongs to carol.
| |
| | |
| ==== trust <nick|fingerprint> ====
| |
| If the argument is nick and we have OTR conversation with nick, their current
| |
| fingerprint is marked as trusted. You can pass the hexadecimal value directly
| |
| instead of the nick it belongs to.
| |
| | |
| You should only use this command after verifying over another channel (e.g.
| |
| phone, in person) that it is indeed the fingerprint used by your peer.
| |
| | |
| Example:
| |
| <pre>
| |
| <alice> trust bob
| |
| <*otr> [bob] Fingerprint 94A1353B 60A58E73 82CE8999 CBBD7B92 5E9EBB87 trusted!
| |
| <alice> trust 378A8445 3FC3933C 73C917C8 BFE4C18B 5CE65CFC
| |
| <*otr> [carol] Fingerprint 378A8445 3FC3933C 73C917C8 BFE4C18B 5CE65CFC trusted!
| |
| </pre>
| |
| | |
| ==== distrust <nick|fingerprint> ====
| |
| This works the same way as the ''trust'' command, except that it marks the
| |
| fingerprint as not trusted.
| |
| | |
| ==== finish <nick> ====
| |
| Terminates the OTR conversation with ''nick''. They are notified that the conversation ended.
| |
| | |
| Note that when ''nick'' terminates the conversation first, you have to use this command as well
| |
| (or start new OTR session). This is to prevent the situation when the other side ends the OTR
| |
| session just before you hit Enter and send in plaintext something you assumed will be encrypted.
| |
| | |
| ==== auth <nick> <secret> ====
| |
| Starts authentication with ''nick'' using a shared secret. So called
| |
| [http://en.wikipedia.org/wiki/Socialist_millionaire socialist millionaire protocol]
| |
| is used to determine whether both of you know the same secret without
| |
| disclosing it to each other.
| |
| | |
| This command is also used to reply to authentication requests started by the other side.
| |
| | |
| Example:
| |
| <pre>
| |
| <alice> Let's authenticate with the answer to following question: what is my favorite book?
| |
| <alice> No capitals or punctuation.
| |
| <bob> OK.
| |
| </pre>
| |
| <pre>
| |
| <alice> auth bob the old man and the sea
| |
| <*otr> [bob] Initiated authentication.
| |
| (bob now does something similar in his client)
| |
| <*otr> [bob] Peer replied to authentication request.
| |
| <*otr> [bob] Successfully authenticated.
| |
| </pre>
| |
| | |
| ==== authq <nick> <[question]> <secret> ====
| |
| This is similar as ''auth'' except that the question is sent as part of the
| |
| authentication request. This allows graphical clients to e.g. display the
| |
| question in a dialog box asking for the answer.
| |
| | |
| You have to enclose the question in a literal square brackets.
| |
| | |
| Please note that this form of shared secret authentication only works in
| |
| clients that support OTRv3.
| |
| | |
| Example:
| |
| <pre>
| |
| <alice> authq bob [What is my favorite book (no caps)?] the old man and the sea
| |
| <*otr> [bob] Initiated authentication.
| |
| (bob's client displays the question and he types the answer)
| |
| <*otr> [bob] Peer replied to authentication request.
| |
| <*otr> [bob] Successfully authenticated.
| |
| </pre>
| |
| | |
| ==== authabort <nick> ====
| |
| Abort ongoing shared secret authentication with ''nick''.
| |
| | |
| ==== genkey [--overwrite] ====
| |
| Generate new private key. You don't have to use this command directly as the
| |
| key is automatically generated the first time it is needed.
| |
| | |
| Use with the '''--overwrite''' parameter to throw away the old key and generate
| |
| a new one.
| |
| | |
| ==== ignore [--remove] [nick] ====
| |
| This command is used to maintain list of nicks for which all OTR functionality is disabled.
| |
| Wildcards can be used to match multiple nicks.
| |
| | |
| Useful when the other side does not like the whitespace OTR advertisements (e.g. NickServ on
| |
| freenode) or when their OTR plugin is broken and causes crashes.
| |
| | |
| Example:
| |
| <pre>
| |
| <alice> ignore
| |
| <*otr> OTR is disabled for following nicks:
| |
| <*otr> carol
| |
| <*otr> elvis
| |
| <alice> ignore foo*
| |
| <*otr> Added foo* to OTR ignore list.
| |
| <alice> ignore --remove carol
| |
| <*otr> Removed carol from OTR ignore list
| |
| <alice> ignore
| |
| <*otr> elvis
| |
| <*otr> foo*
| |
| </pre>
| |
| | |
| == Security considerations ==
| |
| * In most cases it is best not to use this ZNC module and use OTR directly on the client you use to connect to the bouncer instead. This way you don't have to rely on the security of the server, which might be difficult to achieve.
| |
| * Use SSL to connect to the bouncer, otherwise the messages can be intercepted between ZNC and the client.
| |
| * Make sure to turn off logging BOTH on the bouncer (disable the [http://wiki.znc.in/Log log] module) AND at the client you use to connect to the bouncer!
| |
| * It is recommended to only use this module if you are in full control of the ZNC server and are its only user. The bouncer admin, root user of the machine it runs on, and the admin of the virtual host (in case you are running on a VPS) all have access to your conversations and your private keys, which they can give to other people, either intentionally or by making mistakes with regard to security.
| |
| * By disregarding these security measures, you compromise your conversation partner's security as well as yours.
| |
| | |
| == Bugs ==
| |
| The quality of OTR implementation in IRC clients varies greatly. Sometimes the OTR conversation can get to a state where OTR needs to be restarted by using the ''finish'' command and then sending ''?OTR?'' to your peer again.
| |
| | |
| You can report bugs on https://github.com/mmilata/znc-otr/issues or by contacting ''b42'' on freenode.
| |
