From 78b10b997c1db3b2e95f4c43ce17f18542bf5344 Mon Sep 17 00:00:00 2001 From: Tim Henkes Date: Sun, 15 Mar 2020 15:13:09 +0100 Subject: [PATCH] editorial changes; use XML entities; neutral phrasing --- xep-0384.xml | 44 ++++++++++++++++++++++---------------------- xep.ent | 5 +++++ 2 files changed, 27 insertions(+), 22 deletions(-) diff --git a/xep-0384.xml b/xep-0384.xml index 93856e6b..c62b3c5b 100644 --- a/xep-0384.xml +++ b/xep-0384.xml @@ -208,7 +208,7 @@
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,15 +216,15 @@

- 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 a modified version of 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/Ed25519
 +
curve
Curve25519/Ed25519
hash function
SHA-256
info string
"OMEMO X3DH"
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.
 @@ -232,37 +232,37 @@
number of PreKeys to provide in the bundle
The bundle SHOULD always contain around 100 PreKeys.
minimum number of PreKeys to provide in the bundle
The bundle MUST always contain at least 25 PreKeys.
associated data
The associated data is created by concatenating the IdentityKeys of Alice and Bob: AD = Encode(IK_A) || Encode(IK_B)
 -
XEdDSA
The usage of XEdDSA has historically been a pain-point of the X3DH key exchange, as the number of available XEdDSA-implementations is low (at the time of writing) and the license of these implementations might not be optimal for all clients that intend to use OMEMO. For this reason, OMEMO does not mandate the usage of XEdDSA with X3DH. Instead, there are three simple rules that implementations MUST follow: +
XEdDSA
OMEMO does not mandate the usage of &xeddsa; with &x3dh; for the IdentityKey. Instead, there are three simple rules that implementations MUST follow:
    -
  1. Implementations must use the birational map between the curves X25519 and Ed25519 to convert the public part of the IdentityKey whenever required, as defined in RFC 7748.
    2. -
  2. Implementations must be able to perform Diffie-Hellman using the IdentityKey.
    3. -
  3. Implementations must be able to create EdDSA-compatible signatures using the IdentityKey.
    4. +
  4. Implementations must use the birational map between the curves Curve25519 and Ed25519 to convert the public part of the IdentityKey whenever required, as defined in &rfc7748; (on page 5).
    5. +
  5. Implementations must be able to perform X25519 (ECDH on Curve25519) using the IdentityKey.
    6. +
  6. Implementations must be able to create EdDSA-compatible signatures on the curve Ed25519 using the IdentityKey.
There are essentially two ways in which libraries can fulfill these requirements:
    -
  1. Libraries can use an X25519 key pair as their internal IdentityKey. In this case, the IdentityKey can be used for Diffie-Hellman directly, and XEdDSA has to be used to produce EdDSA-compatible signatures.
    2. -
  2. 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 Diffie-Hellman.
    3. +
  3. 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.
    4. +
  4. 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 X25519 and Ed25519 affects the definition of the Sig(PK, M) and DH(PK1, PK2) functions as defined below.
 -
Sig(PK, M)
If the IdentityKey pair is chosen to be an X25519 key pair, the definition of Sig(PK, M) found in the X3DH specification applies. If the IdentityKey pair is chosen to be an Ed25519 key pair, the following definition applies: Sig(PK, M) represents the byte sequence that is an Ed25519 signature on the byte sequence M and verifies with public key PK, and which was created by signing M with PK's corresponding private key.
 -
DH(PK1, PK2)
The original definition of DH(PK1, PK2) found in the X3DH specification applies with one exception: if the IdentityKey pair is chosen to be an Ed25519 key pair and either PK1 or PK2 corresponds to the IdentityKey, the respective key first has to be converted into its X25519 equivalent (see RFC 7748). This conversion is implemented by several crypto-libraries, for example libsodium, which exports the conversion as crypto_sign_ed25519_sk_to_curve25519 and crypto_sign_ed25519_pk_to_curve25519 for the private and public key, respectively (documented here).
 -
byte-encoding of the public keys
[TODO: Find out how Ed25519 public keys are usually encoded]. Note that this is always the Ed25519 public key. When using an X25519 key pair internally, the public key has to be converted to Ed25519 first.
 + 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. +
Sig(PK, M)
If the IdentityKey pair is chosen to be a Curve25519 key pair, the definition of Sig(PK, M) found in the X3DH specification applies. If the IdentityKey pair is chosen to be an Ed25519 key pair, the following definition applies: Sig(PK, M) represents the byte sequence that is an Ed25519 signature on the byte sequence M and verifies with public key PK, and which was created by signing M with PK's corresponding private key. The byte-format of the signature is defined in &rfc8032;.
 +
DH(PK1, PK2)
The original definition of DH(PK1, PK2) found in the X3DH specification applies with one exception: if the IdentityKey pair is chosen to be an Ed25519 key pair and either PK1 or PK2 corresponds to the IdentityKey, the respective key first has to be converted into its Curve25519 equivalent (see above). This conversion is implemented for example by libsodium, which exports the conversion as crypto_sign_ed25519_sk_to_curve25519 and crypto_sign_ed25519_pk_to_curve25519 for the private and public key, respectively (documented on libsodium.org).
 +
Encode(PK)
The public part of the IdentityKey pair is encoded as defined in &rfc8032;. Note that the IdentityKey is always transferred in its Ed25519 form. When using a Curve25519 key pair internally, the public key has to be converted to Ed25519 first. Curve25519 public keys are encoded using the little-endian encoding of the u-coordinate as specified in &rfc7748;.

The key exchange is done just-in-time when sending the first message to a device. Thus, each key exchange message always also contains encrypted content as produced by the Double Ratchet encryption scheme below.

-

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)
@@ -270,7 +270,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. @@ -280,10 +280,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. @@ -638,7 +638,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. 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 X25519 form (see the notes on XEdDSA in the X3DH protocol section for details). If interoperability and backward compatibility are not of concern, the fingerprint MUST still be chosen as a different combination of 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 Curve25519 form (see the notes on XEdDSA in the X3DH protocol section for details). If interoperability and backward compatibility are not of concern, the fingerprint MUST still be chosen as a different combination of 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.

    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 fd3846af..332aff0a 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>." >