moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-24 10:12:19 -05:00
Code Issues Releases Wiki Activity

Handled a lot of TODOs in the XEP

Browse Source
This commit is contained in:
Tim Henkes 2020-03-08 17:25:11 +01:00
parent 030329ecf4
commit 2e28c9cc58
1 changed files with 14 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
xep-0384.xml
View File

@ -194,31 +194,22 @@
<li>Any kind of denial-of-service attack.</li> <li>Any kind of denial-of-service attack.</li>
<li>tbc</li> <li>tbc</li>
</ul> </ul>
<p>
Trust management is a difficult topic, which is out of scope of this document.
</p>
<section2 topic='Threat Model' anchor='reqs-threat-model'> <section2 topic='Threat Model' anchor='reqs-threat-model'>
<p>The OMEMO protocol protects against passive and active attackers which are able to read, modify, replay, delay and delete messages.</p> <p>The OMEMO protocol protects against passive and active attackers which are able to read, modify, replay, delay and delete messages.</p>
<p>tbc</p> <p>tbc</p>
</section2> </section2>
</section1> </section1>
<section1 topic='Glossary' anchor='glossary'> <section1 topic='Glossary' anchor='glossary'>
<section2 topic='General Terms' anchor='glossary-general'> <dl>
<dl> <di><dt>Device</dt><dd>A communication end point, i.e. a specific client instance</dd></di>
<di><dt>Device</dt><dd>A communication end point, i.e. a specific client instance</dd></di> <di><dt>OMEMO element</dt><dd>An &lt;encrypted&gt; element in the urn:xmpp:omemo:1 namespace</dd></di>
<di><dt>OMEMO element</dt><dd>An &lt;encrypted&gt; element in the urn:xmpp:omemo:1 namespace.</dd></di> <di><dt>Bundle</dt><dd>A collection of publicly accessible data used by the X3DH key exchange that can be used to build a session with a device, namely its public IdentityKey, a signed PreKey with corresponding signature, and a list of (single use) PreKeys.</dd></di>
<di><dt>MessageElement</dt><dd>An OMEMO element that contains a chat message. Its &lt;payload&gt;, when decrypted, corresponds to a &lt;message&gt;'s &lt;body&gt;.</dd></di> <di><dt>rid</dt><dd>The device id of the intended recipient of the containing &lt;key&gt;</dd></di>
<di><dt>Bundle</dt><dd>A collection of publicly accessible data that can be used to build a session with a device, namely its public IdentityKey, a signed PreKey with corresponding signature, and a list of (single use) PreKeys.</dd></di> <di><dt>sid</dt><dd>The device id of the sender of the containing OMEMO element</dd></di>
<di><dt>rid</dt><dd>The device id of the intended recipient of the containing &lt;key&gt;</dd></di> </dl>
<di><dt>sid</dt><dd>The device id of the sender of the containing OMEMO element</dd></di>
</dl>
</section2>
<section2 topic='SignalProtocol-specific' anchor='glossary-signalprotocol'>
<dl>
<di><dt>IdentityKey</dt><dd>Per-device public/private key pair used to authenticate communications</dd></di>
<di><dt>PreKey</dt><dd>A Diffie-Hellman public key, published in bulk and ahead of time</dd></di>
<di><dt>OMEMOKeyExchange</dt><dd>An encrypted message that includes the initial key exchange. This is used to transparently build sessions with the first exchanged message.</dd></di>
<di><dt>OMEMOAuthenticatedMessage</dt><dd>An encrypted and authenticated message</dd></di>
</dl>
</section2>
</section1> </section1>
<section1 topic='Protocol Definition' anchor='protocol'> <section1 topic='Protocol Definition' anchor='protocol'>
<section2 topic='Overview' anchor='protocol-overview'> <section2 topic='Overview' anchor='protocol-overview'>
@ -234,7 +225,7 @@
<di><dt>curve</dt><dd>X25519</dd></di> <di><dt>curve</dt><dd>X25519</dd></di>
<di><dt>hash function</dt><dd>SHA-256</dd></di> <di><dt>hash function</dt><dd>SHA-256</dd></di>
<di><dt>info string</dt><dd>&quot;OMEMO X3DH&quot;</dd></di> <di><dt>info string</dt><dd>&quot;OMEMO X3DH&quot;</dd></di>
<di><dt>byte-encoding of the public keys</dt><dd>the default as used by most crypto libraries TODO</dd></di> <di><dt>byte-encoding of the public keys</dt><dd>The little-endian encoding of the u-coordinate as specified <link url="http://www.ietf.org/rfc/rfc7748.txt">here</link> (this is the default way most crypto-libraries encode the public key).</dd></di>
<di><dt>signed pre-key rotation period</dt><dd>Signed pre-keys SHOULD be rotated periodically once a week to once a month. A faster or slower rotation period should not be required.</dd></di> <di><dt>signed pre-key rotation period</dt><dd>Signed pre-keys SHOULD be rotated periodically once a week to once a month. A faster or slower rotation period should not be required.</dd></di>
<di><dt>time to keep the private key of the old signed pre-key after rotating it</dt><dd>The private key of the old signed pre-key SHOULD be kept for another rotation period as defined above, to account for delayed messages using the old signed pre-key.</dd></di> <di><dt>time to keep the private key of the old signed pre-key after rotating it</dt><dd>The private key of the old signed pre-key SHOULD be kept for another rotation period as defined above, to account for delayed messages using the old signed pre-key.</dd></di>
<di><dt>number of pre-keys to provide in the bundle</dt><dd>The bundle SHOULD always contain around 100 pre-keys.</dd></di> <di><dt>number of pre-keys to provide in the bundle</dt><dd>The bundle SHOULD always contain around 100 pre-keys.</dd></di>
@ -448,7 +439,7 @@
<p>A random pk entry is selected, and used to build an OMEMO session.</p> <p>A random pk entry is selected, and used to build an OMEMO session.</p>
</section2> </section2>
<section2 topic='Ending a session' anchor='usecases-ending'> <section2 topic='Ending a session' anchor='usecases-ending'>
<p>In order to signal (TODO: english?) a contact that you like to terminate a session, your <p>In order to signal a contact that you like to terminate a session, your
device MUST send a &lt;terminate&gt; element to all intended recipient devices device MUST send a &lt;terminate&gt; element to all intended recipient devices
inside an encrypted stanza. A user or client MAY tag the element with a inside an encrypted stanza. A user or client MAY tag the element with a
reason. If a device is receiving a stanza containing a &lt;terminate&gt; element, reason. If a device is receiving a stanza containing a &lt;terminate&gt; element,
@ -489,11 +480,8 @@
<section3 topic='Encryption' anchor='encrypt'> <section3 topic='Encryption' anchor='encrypt'>
<p> <p>
The &content; element is encrypted as described in the section about <link url="#protocol-message_encryption">Message Encryption</link>. The &content; element is encrypted as described in the section about <link url="#protocol-message_encryption">Message Encryption</link>.
The client MUST use fresh, randomly generated key AES-256 with.
The SCE &content; element is encrypted using this key (TODO)
</p> </p>
<p> <p>
The 32-byte AES key and the 32-byte HMAC are concatenated and the result of this concatenation is encrypted using the corresponding long-standing OMEMO session for each intended recipient device.
Clients SHOULD only consider the devices on the 'urn:xmpp:omemo:1:devices' node of each recipient (i.e. including his own devices node, but excluding itself). Clients SHOULD only consider the devices on the 'urn:xmpp:omemo:1:devices' node of each recipient (i.e. including his own devices node, but excluding itself).
</p> </p>
</section3> </section3>
@ -528,7 +516,7 @@
<section2 topic='Receiving a message' anchor='usecases-receiving'> <section2 topic='Receiving a message' anchor='usecases-receiving'>
<p>When an OMEMO element is received, the client MUST check whether there is a &lt;keys&gt; element with a jid attribute matching its own bare jid and an inner &lt;key&gt; element with an rid attribute matching its own device id. If this is not the case the message was not encrypted for this particular device and a warning message SHOULD be displayed instead. If such an element exists, the client checks whether the element's contents are an OMEMOKeyExchange.</p> <p>When an OMEMO element is received, the client MUST check whether there is a &lt;keys&gt; element with a jid attribute matching its own bare jid and an inner &lt;key&gt; element with an rid attribute matching its own device id. If this is not the case the message was not encrypted for this particular device and a warning message SHOULD be displayed instead. If such an element exists, the client checks whether the element's contents are an OMEMOKeyExchange.</p>
<p>If this is the case, a new session is built from this received element. The client MUST then republish their bundle information, replacing the used PreKey, such that it won't be used again by a different client. If the client already has a session with the sender's device, it MUST replace this session with the newly built session. The client MUST eventually delete the private key belonging to the PreKey after use (this is subject to the <link url="#business-rules">business rules</link>).</p> <p>If this is the case, a new session is built from this received element. The client MUST then republish their bundle information, replacing the used PreKey, such that it won't be used again by a different client. If the client already has a session with the sender's device, it MUST replace this session with the newly built session. The client MUST eventually delete the private key belonging to the PreKey after use (this is subject to the <link url="#business-rules">business rules</link>).</p>
<p>If the element's contents are a OMEMOAuthenticatedMessage, and the client has a session with the sender's device, it tries to decrypt the OMEMOAuthenticatedMessage using this session. If the decryption fails or there is no session with the sending device, a warning message SHOULD be displayed instead. This is subject to TODO: recovering from broken sessions.</p> <p>If the element's contents are a OMEMOAuthenticatedMessage, and the client has a session with the sender's device, it tries to decrypt the OMEMOAuthenticatedMessage using this session. If the decryption fails or there is no session with the sending device, a warning message SHOULD be displayed instead. Also refer to the section about revocering from broken sessions in the <link url="#business-rules">Business Rules</link>.</p>
<p> <p>
After either the OMEMOKeyExchange or the OMEMOAuthenticatedMessage is decrypted, the content is decrypted as described in the section about <link url="#protocol-message_decryption">Message Decryption</link>. After either the OMEMOKeyExchange or the OMEMOAuthenticatedMessage is decrypted, the content is decrypted as described in the section about <link url="#protocol-message_decryption">Message Decryption</link>.
</p> </p>
@ -608,12 +596,10 @@
<p>When a client receives the message from a device id that is not on the device list, it SHOULD try to retrieve that user's devices node directly to ensure their local cached version of the devices list is up-to-date.</p> <p>When a client receives the message from a device id that is not on the device list, it SHOULD try to retrieve that user's devices node directly to ensure their local cached version of the devices list is up-to-date.</p>
</section1> </section1>
<section1 topic='Implementation Notes' anchor='impl'> <section1 topic='Implementation Notes' anchor='impl'>
<!-- TODO: I think this is still true? -->
<!-- TODO: Write something about trust here -->
</section1> </section1>
<section1 topic='Security Considerations' anchor='security'> <section1 topic='Security Considerations' anchor='security'>
<p>Clients MUST NOT use a newly built session to transmit data without user intervention. If a client were to opportunistically start using sessions for sending without asking the user whether to trust a device first, an attacker could publish a fake device for this user, which would then receive copies of all messages sent by/to this user. A client MAY use such "not (yet) trusted" sessions for decryption of received messages, but in that case it SHOULD indicate the untrusted nature of such messages to the user.</p> <p>Clients MUST NOT use a newly built session to transmit data without user intervention. If a client were to opportunistically start using sessions for sending without asking the user whether to trust a device first, an attacker could publish a fake device for this user, which would then receive copies of all messages sent by/to this user. A client MAY use such "not (yet) trusted" sessions for decryption of received messages, but in that case it SHOULD indicate the untrusted nature of such messages to the user.</p>
<p>When prompting the user for a trust decision regarding a key, the client SHOULD present the user with a fingerprint in the form of a hex string, QR code, or other unique representation, such that it can be compared by the user. TODO: consistent color foo</p> <p>When prompting the user for a trust decision regarding a key, the client SHOULD present the user with a fingerprint in the form of a hex string, QR code, or other unique representation, such that it can be compared by the user. When displaying the fingerprint as a hex string, one way to make it easier to compare the fingerprint is to split the hex string into 8 substrings of 8 chars each, then coloring each 8-char group using &xep0392;. Lowercase letters are recommended when displaying the fingerprint as a hex string.</p>
<p>While it is RECOMMENDED that clients postpone private key deletion until after message catch-up, the standards mandates that clients MUST NOT use duplicate-PreKey sessions for sending, so clients MAY delete such keys immediately for security reasons. For additional information on potential security impacts of this decision, refer to <note>Menezes, Alfred, and Berkant Ustaoglu. "On reusing ephemeral keys in Diffie-Hellman key agreement protocols." International Journal of Applied Cryptography 2, no. 2 (2010): 154-158.</note>.</p> <p>While it is RECOMMENDED that clients postpone private key deletion until after message catch-up, the standards mandates that clients MUST NOT use duplicate-PreKey sessions for sending, so clients MAY delete such keys immediately for security reasons. For additional information on potential security impacts of this decision, refer to <note>Menezes, Alfred, and Berkant Ustaoglu. "On reusing ephemeral keys in Diffie-Hellman key agreement protocols." International Journal of Applied Cryptography 2, no. 2 (2010): 154-158.</note>.</p>
</section1> </section1>
<section1 topic='IANA Considerations' anchor='iana'> <section1 topic='IANA Considerations' anchor='iana'>