From de92a8c11f67650e0e0e254e672fb9af2f41cb34 Mon Sep 17 00:00:00 2001 From: Daniel Gultsch Date: Fri, 2 Jun 2017 15:30:11 +0200 Subject: [PATCH] XEP-0384: switch to 'siacs' namespace and use SignalProtocol --- xep-0384.xml | 83 +++++++++++++++++++++++++++++----------------------- 1 file changed, 46 insertions(+), 37 deletions(-) diff --git a/xep-0384.xml b/xep-0384.xml index 29d76c94..7d388d91 100644 --- a/xep-0384.xml +++ b/xep-0384.xml @@ -27,6 +27,15 @@ andy@strb.org andy@strb.org + + 0.2 + 2017-06-02 + dg + +

Depend on SignalProtocol instead of Olm.

+

Changed to eu.siacs.conversations.axolotl Namespace which is currently used in the wild

+ + 0.1 2016-12-07 @@ -63,17 +72,19 @@ external complexity.

- This XEP defines a protocol that leverages &olm; encryption to provide + This XEP defines a protocol that leverages the SignalProtocol encryption to provide multi-end to multi-end encryption, allowing messages to be synchronized - securely across multiple clients, even if some of them are offline. Olm + securely across multiple clients, even if some of them are offline. The SignalProtocol is a cryptographic double ratched protocol based on work by Trevor Perrin - and Moxie Marlinspike first published as the Axolotl protocol. + and Moxie Marlinspike first published as the Axolotl protocol. The protocol is not fully + documented in public domain and only exists in GPLv3-licensed implementations maintained + by OpenWhisperSystems.

The general idea behind this protocol is to maintain separate, - long-standing Olm-encrypted sessions with each device of each contact + long-standing SignalProtocol-encrypted sessions with each device of each contact (as well as with each of our other devices), which are used as secure key transport channels. In this scheme, each message is encrypted with a fresh, randomly generated encryption key. An encrypted header is added to @@ -87,14 +98,14 @@

As the encrypted payload is common to all recipients, it only has to be - included once, reducing overhead. Furthermore, Olm's transparent handling + included once, reducing overhead. Furthermore, SignalProtocols’s transparent handling of messages that were lost or received out of order, as well as those sent while the recipient was offline, is maintained by this protocol. As a result, in combination with &xep0280; and &xep0313;, the desired property of inter-client history synchronization is achieved.

- OMEMO currently uses version 1 Olm protocol. Instead of an Axolotl key + OMEMO currently uses version 3 SignalProtocol. Instead of an Signal key server, &xep0163; (PEP) is used to publish key data.

@@ -111,7 +122,7 @@
Device
A communication end point, i.e. a specific client instance
 -
OMEMO element
An <encrypted> element in the urn:xmpp:omemo:0 namespace. Can be either MessageElement or a KeyTransportElement
 +
OMEMO element
An <encrypted> element in the eu.siacs.conversations.axolotl namespace. Can be either MessageElement or a KeyTransportElement
MessageElement
An OMEMO element that contains a chat message. Its <payload>, when decrypted, corresponds to a <message>'s <body>.
KeyTransportElement
An OMEMO element that does not have a <payload>. It contains a fresh encryption key, which can be used for purposes external to this XEP.
Bundle
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.
 @@ -120,12 +131,12 @@
- +
IdentityKey
Per-device public/private key pair used to authenticate communications
PreKey
A Diffie-Hellman public key, published in bulk and ahead of time
 -
PreKeyOlmMessage
An encrypted message that includes the initial key exchange. This is used to transparently build sessions with the first exchanged message.
 -
OlmMessage
An encrypted message
 +
PreKeySignalMessage
An encrypted message that includes the initial key exchange. This is used to transparently build sessions with the first exchanged message.
 +
SignalMessage
An encrypted message
@@ -139,16 +150,16 @@

-

In order to determine whether a given contact has devices that support OMEMO, the devicelist node in PEP is consulted. Devices MUST subscribe to 'urn:xmpp:omemo:0:devicelist' via PEP, so that they are informed whenever their contacts add a new device. They MUST cache the most up-to-date version of the devicelist.

+

In order to determine whether a given contact has devices that support OMEMO, the devicelist node in PEP is consulted. Devices MUST subscribe to 'eu.siacs.conversations.axolotl.devicelist' via PEP, so that they are informed whenever their contacts add a new device. They MUST cache the most up-to-date version of the devicelist.

- + - + @@ -162,9 +173,9 @@ - + - + @@ -178,9 +189,9 @@ - + - + BASE64ENCODED... @@ -216,10 +227,10 @@ to='juliet@capulet.lit' id='fetch1'> - + ]]> -

A random preKeyPublic entry is selected, and used to build an Olm session.

+

A random preKeyPublic entry is selected, and used to build an SignalProtocol session.

@@ -230,15 +241,15 @@ 128 bit) are concatenated and for each intended recipient device, i.e. both own devices as well as devices associated with the contact, the result of this concatenation is encrypted using the corresponding - long-standing Olm session. Each encrypted payload key/authentication tag + long-standing SignalProtocol session. Each encrypted payload key/authentication tag tuple is tagged with the recipient device's ID. The key element MUST be - tagged with a prekey attribute set to true if a PreKeyOlmMessage is being + tagged with a prekey attribute set to true if a PreKeySignalMessage is being used. This is all serialized into a MessageElement, which is transmitted in a <message> as follows:

- +
BASE64ENCODED... BASE64ENCODED... @@ -258,14 +269,14 @@ SHOULD have at least 128 bit) are concatenated and for each intended recipient device, i.e. both own devices as well as devices associated with the contact, this key is encrypted using the corresponding - long-standing Olm session. Each encrypted payload key/authentication tag + long-standing SignalProtocol session. Each encrypted payload key/authentication tag tuple is tagged with the recipient device's ID. The key element MUST be - tagged with a prekey attribute set to true if a PreKeyOlmMessage is being + tagged with a prekey attribute set to true if a PreKeySignalMessage is being used This is all serialized into a KeyTransportElement, omitting the <payload> as follows:

+
BASE64ENCODED... BASE64ENCODED... @@ -276,25 +287,24 @@

This KeyTransportElement can then be sent over any applicable transport mechanism.

-

When an OMEMO element is received, the client MUST check whether there is a <key> element with an rid attribute matching its own device ID. If this is not the case, the element MUST be silently discarded. If such an element exists, the client checks whether the element's contents are a PreKeyOlmMessage.

+

When an OMEMO element is received, the client MUST check whether there is a <key> element with an rid attribute matching its own device ID. If this is not the case, the element MUST be silently discarded. If such an element exists, the client checks whether the element's contents are a PreKeySignalMessage.

If this is the case, a new session is built from this received element. The client SHOULD 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 delete the private key belonging to the PreKey after use.

-

If the element's contents are a OlmMessage, and the client has a session with the sender's device, it tries to decrypt the OlmMessage using this session. If the decryption fails or if the element's contents are not a OlmMessage either, the OMEMO element MUST be silently discarded.

+

If the element's contents are a SignalMessage, and the client has a session with the sender's device, it tries to decrypt the SignalMessage using this session. If the decryption fails or if the element's contents are not a SignalMessage either, the OMEMO element MUST be silently discarded.

If the OMEMO element contains a <payload>, it is an OMEMO message element. The client tries to decrypt the base64 encoded contents using the key and the authentication tag extracted from the <key> element. If the decryption fails, the client MUST silently discard the OMEMO message. If it succeeds, the decrypted contents are treated as the <body> of the received message.

If the OMEMO element does not contain a <payload>, the client has received a KeyTransportElement. The key extracted from the <key> element can then be used for other purposes (e.g. encrypted file transfer).

Before publishing a freshly generated Device ID for the first time, a device MUST check whether that Device ID already exists, and if so, generate a new one.

-

Clients SHOULD NOT immediately fetch the bundle and build a session as soon as a new device is announced. Before the first message is exchanged, the contact does not know which PreKey has been used (or, in fact, that any PreKey was used at all). As they have not had a chance to remove the used PreKey from their bundle announcement, this could lead to collisions where both Alice and Bob pick the same PreKey to build a session with a specific device. As each PreKey SHOULD only be used once, the party that sends their initial PreKeyOlmMessage later loses this race condition. This means that they think they have a valid session with the contact, when in reality their messages MAY be ignored by the other end. By postponing building sessions, the chance of such issues occurring can be drastically reduced. It is RECOMMENDED to construct sessions only immediately before sending a message.

-

As there are no explicit error messages in this protocol, if a client does receive a PreKeyOlmMessage using an invalid PreKey, they SHOULD respond with a KeyTransportElement, sent in a <message> using a PreKeyOlmMessage. By building a new session with the original sender this way, the invalid session of the original sender will get overwritten with this newly created, valid session.

-

If a PreKeyOlmMessage is received as part of a &xep0313; catch-up and used to establish a new session with the sender, the client SHOULD postpone deletion of the private key corresponding to the used PreKey until after MAM catch-up is completed. If this is done, the client MUST then also send a KeyTransportMessage using a PreKeyOlmMessage before sending any payloads using this session, to trigger re-keying. (as above) This practice can mitigate the previously mentioned race condition by preventing message loss.

+

Clients SHOULD NOT immediately fetch the bundle and build a session as soon as a new device is announced. Before the first message is exchanged, the contact does not know which PreKey has been used (or, in fact, that any PreKey was used at all). As they have not had a chance to remove the used PreKey from their bundle announcement, this could lead to collisions where both Alice and Bob pick the same PreKey to build a session with a specific device. As each PreKey SHOULD only be used once, the party that sends their initial PreKeySignalMessage later loses this race condition. This means that they think they have a valid session with the contact, when in reality their messages MAY be ignored by the other end. By postponing building sessions, the chance of such issues occurring can be drastically reduced. It is RECOMMENDED to construct sessions only immediately before sending a message.

+

As there are no explicit error messages in this protocol, if a client does receive a PreKeySignalMessage using an invalid PreKey, they SHOULD respond with a KeyTransportElement, sent in a <message> using a PreKeySignalMessage. By building a new session with the original sender this way, the invalid session of the original sender will get overwritten with this newly created, valid session.

+

If a PreKeySignalMessage is received as part of a &xep0313; catch-up and used to establish a new session with the sender, the client SHOULD postpone deletion of the private key corresponding to the used PreKey until after MAM catch-up is completed. If this is done, the client MUST then also send a KeyTransportMessage using a PreKeySignalMessage before sending any payloads using this session, to trigger re-keying. (as above) This practice can mitigate the previously mentioned race condition by preventing message loss.

As the asynchronous nature of OMEMO allows decryption at a later time to currently offline devices client SHOULD include a &xep0334; <store /> hint in their OMEMO messages. Otherwise, server implementations of &xep0313; will generally not retain OMEMO messages, since they do not contain a <body />

- The Olm library's reference implementation (and presumably its ports to - various other platforms) uses a trust model that doesn't work very well with + The SignalProtocol-library uses a trust model that doesn't work very well with OMEMO. For this reason it may be desirable to have the library consider all keys trusted, effectively disabling its trust management. This makes it necessary to implement trust handling oneself. @@ -305,7 +315,7 @@

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.

While it is RECOMMENDED that clients postpone private key deletion until after MAM catch-up and this standards mandates that clients MUST NOT use duplicate-PreKey sessions for sending, clients MAY delete such keys immediately for security reasons. For additional information on potential security impacts of this decision, refer to 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..

- In order to be able to handle out-of-order messages, the Olm stack has to + In order to be able to handle out-of-order messages, the SignalProtocol stack has to cache the keys belonging to "skipped" messages that have not been seen yet. It is up to the implementor to decide how long and how many of such keys to keep around. @@ -318,9 +328,8 @@

This specification defines the following XMPP namespaces:

    -
  • urn:xmpp:omemo:0
    • +
  • eu.siacs.conversations.axolotl
-

The ®ISTRAR; shall include the foregoing namespace in its registry at &NAMESPACES;, as goverened by &xep0053;.

&NSVER; @@ -330,8 +339,8 @@ + targetNamespace="eu.siacs.conversations.axolotl" + xmlns="eu.siacs.conversations.axolotl">