diff --git a/xep-0384.xml b/xep-0384.xml index 55c384e0..73bc3897 100644 --- a/xep-0384.xml +++ b/xep-0384.xml @@ -57,6 +57,17 @@ xmpp@larma.de jabber@larma.de + + 0.5.0 + 2020-03-26 + th + + + + 0.4.0 2020-03-08 @@ -200,15 +211,15 @@ Trust management is a difficult topic, which is out of scope of this document.

-

The OMEMO protocol protects against passive and active attackers which are able to read, modify, replay, delay and delete messages.

-

tbc

+

The use case for OMEMO is a situation where the content of a conversation needs to be protected, but where the servers the message passes by can’t be trusted to keep the content of the message secret. For example when information that is under strict embargo needs to passed within an organization and the server administrator is not one of the persons cleared to see the information or when a couple is exchanging intimate messages and they want to avoid leaking of those messages to the server administrator.

+

The OMEMO protocol protects against passive and active attackers which are able to read, modify, replay, delay and delete messages. The OMEMO protocol does not protect against attackers who rely on metadata and traffic analysis. The quality of the verification of the conversation participants OMEMO identity keys determines the level of protection OMEMO offers.
Device
A communication end point, i.e. a specific client instance
OMEMO element
An <encrypted> element in the &ns; namespace
 -
Bundle
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.
 +
Bundle
A collection of publicly accessible data used by the X3DH key agreement protocol 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.
rid
The device id of the intended recipient of the containing <key>
sid
The device id of the sender of the containing OMEMO element
@@ -216,18 +227,17 @@

- This protocol uses the Double Ratchet encryption scheme in conjunction with the X3DH key exchange. The following section provides detailed technical information about the protocol that should be sufficient to build an implementation of the OMEMO Double Ratchet. Readers who do not intend to build an OMEMO-compatible library can safely skip this section, relevant details are repeated where needed. + This protocol uses the &doubleratchet; encryption scheme in conjunction with the &x3dh; key agreement protocol. The following section provides detailed technical information about the protocol that should be sufficient to build an implementation of the OMEMO Double Ratchet. Readers who do not intend to build an OMEMO-compatible library can safely skip this section, relevant details are repeated where needed.

- The X3DH key exchange is specified here and placed under the public domain. OMEMO uses this key exchange mechanism with the following parameters/settings: + The &x3dh; key agreement protocol was specified by Trevor Perrin and Moxie Marlinspike and placed under the public domain. OMEMO uses a modified version of this key agreement protocol with the following parameters/settings:

-
curve
X25519
 +
curve
Curve25519/Ed25519
hash function
SHA-256
info string
"OMEMO X3DH"
 -
byte-encoding of the public keys
The little-endian encoding of the u-coordinate as specified here (this is the default way most crypto-libraries encode the public key).
signed PreKey rotation period
Signed PreKeys SHOULD be rotated periodically once a week to once a month. A faster or slower rotation period should not be required.
time to keep the private key of the old signed PreKey after rotating it
The private key of the old signed PreKey SHOULD be kept for another rotation period as defined above, to account for delayed messages using the old signed PreKey.
number of PreKeys to provide in the bundle
The bundle SHOULD always contain around 100 PreKeys.
 @@ -241,7 +251,7 @@ There are essentially two ways in which libraries can fulfill these requirements:
    -
  1. Libraries can use a Curve25519 key pair as their internal IdentityKey. In this case, the IdentityKey can be used for X25519 directly, and XEdDSA has to be used to produce EdDSA-compatible signatures. Note that libsignal by default does NOT use XEdDSA. libsignal includes XEdDSA though and has to be modified to use that to be compatible with OMEMO.
    2. +
  2. Libraries can use a Curve25519 key pair as their internal IdentityKey. In this case, the IdentityKey can be used for X25519 directly, and XEdDSA has to be used to produce EdDSA-compatible signatures. Note that libsignal by default does NOT use XEdDSA. libsignal includes XEdDSA though and has to be modified to use that to be compatible with OMEMO.
  3. Libraries can use an Ed25519 key pair as their internal IdentityKey. In this case, the IdentityKey can create EdDSA-compatible signatures directly, and has to be converted first to perform X25519.
Note that this decision is purely local to each client and OMEMO library. The public key is ALWAYS transferred in its Ed25519 form and only valid EdDSA signatures are transferred. The choice between Curve25519 and Ed25519 affects the definition of the Sig(PK, M) and DH(PK1, PK2) functions as defined below. @@ -254,16 +264,16 @@

-

NOTE: OMEMOMessage.proto, OMEMOAuthenticatedMessage.proto and OMEMOKeyExchange.proto refer to the protobuf structures as defined here.

+

NOTE: OMEMOMessage.proto, OMEMOAuthenticatedMessage.proto and OMEMOKeyExchange.proto refer to the protobuf structures as defined in the Protobuf Schemas.

- The Double Ratchet encryption scheme is specified here and placed under the public domain. OMEMO uses this protocol with the following parameters/settings: + The &doubleratchet; encryption scheme was specified by Trevor Perrin and Moxie Marlinspike and placed under the public domain. OMEMO uses this protocol with the following parameters/settings:

-
ratchet initialization
The Double Ratchet is initialized using the shared secret, ad and public keys as yielded by the X3DH key exchange, as explained in the Double Ratchet specification.
 +
ratchet initialization
The Double Ratchet is initialized using the shared secret, ad and public keys as yielded by the X3DH key agreement protocol, as explained in the Double Ratchet specification.
MAX_SKIP
It is RECOMMENDED to keep around 1000 skipped message keys.
deletion policy for skipped message keys
Skipped message keys MUST be stored until MAX_SKIP message keys are stored. At that point, keys are discarded on a FIFO basis to make space for new message keys. Implementations SHOULD not keep skipped message keys around forever, but discard old keys on a different implementation-defined policy. It is RECOMMENDED to base this policy on deterministic events rather than time.
authentication tag truncation
Authentication tags are truncated to 16 bytes/128 bits.
 -
CONCAT(ad, header)
CONCAT(ad, header) = ad || OMEMOMessage.proto(header) NOTE: the OMEMOMessage.proto is initialized without the ciphertext, which is optional. NOTE: Implementations are not strictly required to return a parseable byte array here, as the unpacked/parsed data is required later in the protocol.
 +
CONCAT(ad, header)
CONCAT(ad, header) = ad || OMEMOMessage.proto(header) NOTE: the OMEMOMessage.proto is initialized without the ciphertext, which is optional. NOTE: Implementations are not strictly required to return a parseable byte array, as the unpacked/parsed data is required later in the protocol.
KDF_RK(rk, dh_out)
HKDF-SHA-256 using the rk as HKDF salt, dh_out as HKDF input material and "OMEMO Root Chain" as HKDF info.
KDF_CK(ck)
HMAC-SHA-256 using ck as the HMAC key, a single byte constant 0x01 as HMAC input to produce the next message key and a single byte constant 0x02 as HMAC input to produce the next chain key.
ENCRYPT(mk, plaintext, associated_data)
@@ -271,7 +281,7 @@
  1. Use HKDF-SHA-256 to generate 80 bytes of output from the message key by providing mk as HKDF input, 256 zero-bits as HKDF salt and "OMEMO Message Key Material" as HKDF info.
  2. Divide the HKDF output into a 32-byte encryption key, a 32-byte authentication key and a 16 byte IV.
    3. -
  3. Encrypt the plaintext (which consists of a 32 bytes key and a 32 bytes HMAC as specified here) using AES-256-CBC with PKCS#7 padding, using the encryption key and IV derived in the previous step.
    4. +
  4. Encrypt the plaintext (which consists of a 32 bytes key and a 32 bytes HMAC as specified in the section about Message Encryption) using AES-256-CBC with PKCS#7 padding, using the encryption key and IV derived in the previous step.
  5. Split the associated data as returned by CONCAT into the original ad and the OMEMOMessage.proto structure.
  6. Add the ciphertext to the OMEMOMessage.proto structure.
  7. Serialize the ad and the OMEMOMessage.proto structure into a parseable byte array by concatenating ad and the serialized protobuf structure.
    8. @@ -281,10 +291,10 @@

- If encrypting this message required a key exchange, the X3DH key exchange header data is placed into a new OMEMOKeyExchange.proto structure together with the OMEMOAuthenticatedMessage.proto structure. + If encrypting this message required a key exchange, the X3DH header data is placed into a new OMEMOKeyExchange.proto structure together with the OMEMOAuthenticatedMessage.proto structure.

- To account for lost and out-of-order messages during the key exchange, OMEMOKeyExchange.proto structures are sent until a response by the recipient confirms that the key exchange was successfully completed. To do so, the X3DH key exchange header data is stored and added on each subsequent message until a response is received. This looks roughly as follows: + To account for lost and out-of-order messages during the key exchange, OMEMOKeyExchange.proto structures are sent until a response by the recipient confirms that the key exchange was successfully completed. To do so, the X3DH header data is stored and added on each subsequent message until a response is received. This looks roughly as follows:

  1. The first content is encrypted for a new recipient. This results in an X3DH header and a OMEMOAuthenticatedMessage.proto structure. Both are packed into an OMEMOKeyExchange.proto structure. The X3DH header is stored for following messages.
    2. @@ -639,7 +649,7 @@

    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.

    -

    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. The fingerprint is often chosen to be the public part of the device's IdentityKey, but could also be a different combination data that guarantees absence of a man-in-the-middle when verified. 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.

    +

    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. To ensure interoperability between clients and older versions of OMEMO, the fingerprint SHOULD be chosen to be the public part of the IdentityKey in its byte-encoded Curve25519 form (see the notes on XEdDSA and the byte-encoding of public keys in the X3DH protocol section for details). 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.

    While it is RECOMMENDED that clients postpone private key deletion until after message catch-up, the X3DH standard mandates that clients should 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 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..

     diff --git a/xep.ent b/xep.ent index 3892e305..634086a0 100644 --- a/xep.ent +++ b/xep.ent @@ -361,6 +361,9 @@ THE SOFTWARE. Whirlpool The Whirlpool Hash Function <http://paginas.terra.com.br/informatica/paulobarreto/WhirlpoolPage.html>." > Olm Olm: A Cryptographic Ratchet <https://matrix.org/docs/spec/olm.html>." > Curve25519 Curve25519: new Diffie-Hellman speed records <http://cr.yp.to/ecdh/curve25519-20060209.pdf>." > +DoubleRatchet The Double Ratchet Algorithm <https://signal.org/docs/specifications/doubleratchet/>." > +X3DH The X3DH Key Agreement Protocol <https://www.signal.org/docs/specifications/x3dh/>." > +XEdDSA The XEdDSA and VXEdDSA Signature Schemes <https://www.signal.org/docs/specifications/xeddsa/>." > @@ -688,8 +691,10 @@ THE SOFTWARE. RFC 7693 RFC 7693: The BLAKE2 Cryptographic Hash and Message Authentication Code (MAC) <http://tools.ietf.org/html/rfc7693>." > RFC 7700 RFC 7700: Preparation, Enforcement, and Comparison of Internationalized Strings Representing Nicknames<http://tools.ietf.org/html/rfc7700>." > RFC 7712 RFC 7712: Domain Name Associations (DNA) in the Extensible Messaging and Presence Protocol (XMPP)<http://tools.ietf.org/html/rfc7712>." > +RFC 7748 RFC 7748: Elliptic Curves for Security <http://tools.ietf.org/html/rfc7748>." > RFC 7764 RFC 7764: Guidance on Markdown: Design Philosophies, Stability Strategies, and Select Registrations <http://tools.ietf.org/html/rfc7764>." > RFC 7830 RFC 7830: The EDNS(0) Padding Option <http://tools.ietf.org/html/rfc7830>." > +RFC 8032 RFC 8032: Edwards-Curve Digital Signature Algorithm (EdDSA) <http://tools.ietf.org/html/rfc8032>." > RFC 8174 RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words <http://tools.ietf.org/html/rfc8174>." > RFC 8264 RFC 8264: PRECIS Framework: Preparation, Enforcement, and Comparison of Internationalized Strings in Application Protocols <http://tools.ietf.org/html/rfc8264>." > RFC 8445 RFC 8445: Interactive Connectivity Establishment (ICE) <http://tools.ietf.org/html/rfc8445>." >