moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-12-21 23:28:51 -05:00
Code Issues Releases Wiki Activity

Don't forbid XEdDSA, but make it optional by defining rules that make actual sense

Browse Source
This commit is contained in:
Tim Henkes 2020-03-14 15:42:27 +01:00
parent c00b41bbd4
commit 4372ac8951
1 changed files with 16 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
xep-0384.xml
View File

@ -227,15 +227,26 @@
<di><dt>curve</dt><dd>X25519/Ed25519</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>byte-encoding of the public keys</dt><dd>TBD: How are Ed25519 public keys commonly encoded?</dd></di>
<di><dt>signed PreKey rotation period</dt><dd>Signed PreKeys 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 PreKey after rotating it</dt><dd>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.</dd></di>
<di><dt>number of PreKeys to provide in the bundle</dt><dd>The bundle SHOULD always contain around 100 PreKeys.</dd></di>
<di><dt>minimum number of PreKeys to provide in the bundle</dt><dd>The bundle MUST always contain at least 25 PreKeys.</dd></di>
<di><dt>associated data</dt><dd>The associated data is created by concatenating the IdentityKeys of Alice and Bob: <tt>AD = Encode(IK_A) || Encode(IK_B)</tt></dd></di>
<di><dt>XEdDSA</dt><dd>OMEMO does not use XEdDSA as specified in the X3DH specification. Instead, OMEMO uses an Ed25519 key pair as the IdentityKey and converts this key pair into an X25519 key pair when required. This is mainly due to the fact that XEdDSA is not widely available (at the time of writing) and it is not trivial to write custom implementations of it. The impact of this change is minimal: the <tt>Sig(PK, M)</tt> and the <tt>DH(PK1, PK2)</tt> functions work slightly different as defined below.</dd></di>
<di><dt>Sig(PK, M)</dt><dd><tt>Sig(PK, M)</tt> represents the byte sequence that is an Ed25519 signature on the byte sequence <tt>M</tt> and verifies with public key <tt>PK</tt>, and which was created by signing <tt>M</tt> with <tt>PK</tt>'s corresponding private key.</dd></di>
<di><dt>DH(PK1, PK2)</dt><dd>The original definition of <tt>DH(PK1, PK2)</tt> applies with one exception: if either <tt>PK1</tt> or <tt>PK2</tt> corresponds to the IdentityKey, the respective key first has to be converted into its X25519 equivalent as per [TODO: find and link specification of the conversion algorithm]. This conversion is implemented by several crypto-libraries, for example <tt>libsodium</tt>, which exports the conversion as <tt>crypto_sign_ed25519_sk_to_curve25519</tt> and <tt>crypto_sign_ed25519_pk_to_curve25519</tt> for the private and public key, respectively (documented <link url="https://download.libsodium.org/doc/advanced/ed25519-curve25519">here</link>).</dd></di>
<di><dt>XEdDSA</dt><dd>The usage of <link url="https://www.signal.org/docs/specifications/xeddsa/">XEdDSA</link> 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:
<ol>
<li>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 <link url="https://tools.ietf.org/html/rfc7748#page-5">RFC 7748</link>.</li>
<li>Implementations must be able to perform Diffie-Hellman using the IdentityKey.</li>
<li>Implementations must be able to create EdDSA-compatible signatures using the IdentityKey.</li>
</ol>
There are essentially two ways in which libraries can fulfill these requirements:
<ol>
<li>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.</li>
<li>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.</li>
</ol>
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 <tt>Sig(PK, M)</tt> and <tt>DH(PK1, PK2)</tt> functions as defined below.</dd></di>
<di><dt>Sig(PK, M)</dt><dd>If the IdentityKey pair is chosen to be an X25519 key pair, the definition of <tt>Sig(PK, M)</tt> found in the X3DH specification applies. If the IdentityKey pair is chosen to be an Ed25519 key pair, the following definition applies: <tt>Sig(PK, M)</tt> represents the byte sequence that is an Ed25519 signature on the byte sequence <tt>M</tt> and verifies with public key <tt>PK</tt>, and which was created by signing <tt>M</tt> with <tt>PK</tt>'s corresponding private key.</dd></di>
<di><dt>DH(PK1, PK2)</dt><dd>The original definition of <tt>DH(PK1, PK2)</tt> found in the X3DH specification applies with one exception: if the IdentityKey pair is chosen to be an Ed25519 key pair and either <tt>PK1</tt> or <tt>PK2</tt> corresponds to the IdentityKey, the respective key first has to be converted into its X25519 equivalent (see <link url="https://tools.ietf.org/html/rfc7748#page-5">RFC 7748</link>). This conversion is implemented by several crypto-libraries, for example <tt>libsodium</tt>, which exports the conversion as <tt>crypto_sign_ed25519_sk_to_curve25519</tt> and <tt>crypto_sign_ed25519_pk_to_curve25519</tt> for the private and public key, respectively (documented <link url="https://download.libsodium.org/doc/advanced/ed25519-curve25519">here</link>).</dd></di>
<di><dt>byte-encoding of the public keys</dt><dd>[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.</dd></di>
</dl>
<p>
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.
@ -627,7 +638,7 @@
</section1>
<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>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 after converting it to X25519 (see the <link url="#protocol-key_exchange">notes on `DH(PK1, PK2)` in the X3DH protocol section</link> for info on that conversion). 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.</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. 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 <link url="#protocol-key_exchange">notes on XEdDSA in the X3DH protocol section</link> 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.</p>
<p>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 <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 topic='IANA Considerations' anchor='iana'>