Update content of files

This commit is contained in:
GitHub Action 2023-03-15 19:48:25 +00:00
parent 0a6ba1b668
commit 872e276570
3 changed files with 180 additions and 127 deletions

View file

@ -60,9 +60,6 @@ Client developers are required to comply with the <a href="/mtproto/security_gui
<p><a href="/mtproto/auth_key">Creating an Authorization Key</a></p>
</li>
<li>
<p><a href="/mtproto/samples-auth_key">Creating an Authorization Key: Example</a></p>
</li>
<li>
<p><a href="/mtproto/service_messages">Mobile Protocol: Service Messages</a></p>
</li>
<li>

View file

@ -44,100 +44,150 @@
<div id="dev_page_content"><p>The query format is described using <a href="/mtproto/serialize">Binary Data Serialization</a> and the <a href="/mtproto/TL">TL Language</a>. All large numbers are transmitted as strings containing the required sequence of bytes in big endian order. Hash functions, such as SHA1, return strings (of 20 bytes) which can also be interpreted as big endian numbers. Small numbers (<code>int</code>, <code>long</code>, <code>int128</code>, <code>int256</code>) are normally little endian; however, if they are part of SHA1, the bytes are not rearranged. This way, if <code>long</code> <code>x</code> is the 64 lower-order bits of SHA1 of string <code>s</code>, then the <em>final</em> 8 bytes of 20-byte string <code>SHA1(s)</code> are taken and interpreted as a 64-bit integer.</p>
<p>Prior to sending off unencrypted messages (required in this instance to generate an authorization key), the client must undergo (p,q) authorization as follows.</p>
<h4><a class="anchor" name="dh-exchange-initiation" href="#dh-exchange-initiation"><i class="anchor-icon"></i></a>DH exchange initiation</h4>
<p>1) Client sends query to server</p>
<pre><code>req_pq_multi#be7e8ef1 nonce:int128 = ResPQ;</code></pre>
<h4><a class="anchor" href="#dh-exchange-initiation" id="dh-exchange-initiation" name="dh-exchange-initiation"><i class="anchor-icon"></i></a>DH exchange initiation</h4>
<ol>
<li>
<p>Client sends query to server</p>
<p>req_pq_multi#be7e8ef1 nonce:int128 = ResPQ;</p>
</li>
</ol>
<p>The value of <em>nonce</em> is selected randomly by the client (random number) and identifies the client within this communication. Following this step, it is known to all.</p>
<p>2) Server sends response of the form</p>
<pre><code>resPQ#05162463 nonce:int128 server_nonce:int128 pq:string server_public_key_fingerprints:Vector long = ResPQ;</code></pre>
<ol start="2">
<li>
<p>Server sends response of the form</p>
<p>resPQ#05162463 nonce:int128 server_nonce:int128 pq:string server_public_key_fingerprints:Vector long = ResPQ;</p>
</li>
</ol>
<p>Here, string pq is a representation of a natural number (in binary big endian format). This number is the product of two different odd prime numbers. Normally, pq is less than or equal to 2^63-1. The value of <em>server_nonce</em> is selected randomly by the server; following this step, it is known to all.</p>
<p><code>server_public_key_fingerprints</code> is a list of public RSA key fingerprints (64 lower-order bits of SHA1 (server_public_key); the public key is represented as a bare type <code>rsa_public_key n:string e:string = RSAPublicKey</code>, where, as usual, n and e are numbers in big endian format serialized as strings of bytes, following which SHA1 is computed) received by the server.</p>
<p>All subsequent messages contain the pair (nonce, server_nonce) both in the plain-text, and the encrypted portions which makes it possible to identify a “temporary session” — one run of the key generation protocol described on this page that uses the same (nonce, server_nonce) pair. An intruder could not create a parallel session with the server with the same parameters and reuse parts of server- or client-encrypted messages for its own purposes in such a parallel session, because a different server_nonce would be selected by the server for any new “temporary session”.</p>
<h4><a class="anchor" name="proof-of-work" href="#proof-of-work"><i class="anchor-icon"></i></a>Proof of work</h4>
<p>3) Client decomposes pq into prime factors such that p &lt; q.</p>
<h4><a class="anchor" href="#proof-of-work" id="proof-of-work" name="proof-of-work"><i class="anchor-icon"></i></a>Proof of work</h4>
<ol start="3">
<li>Client decomposes pq into prime factors such that p &lt; q.</li>
</ol>
<p>This starts a round of Diffie-Hellman key exchanges.</p>
<h4><a class="anchor" name="presenting-proof-of-work-server-authentication" href="#presenting-proof-of-work-server-authentication"><i class="anchor-icon"></i></a>Presenting proof of work; Server authentication</h4>
<p>4) Client sends query to server</p>
<pre><code>req_DH_params#d712e4be nonce:int128 server_nonce:int128 p:string q:string public_key_fingerprint:long encrypted_data:string = Server_DH_Params</code></pre>
<h4><a class="anchor" href="#presenting-proof-of-work-server-authentication" id="presenting-proof-of-work-server-authentication" name="presenting-proof-of-work-server-authentication"><i class="anchor-icon"></i></a>Presenting proof of work; Server authentication</h4>
<ol start="4">
<li>
<p>Client sends query to server</p>
<p>req_DH_params#d712e4be nonce:int128 server_nonce:int128 p:string q:string public_key_fingerprint:long encrypted_data:string = Server_DH_Params</p>
</li>
</ol>
<p>Here, encrypted_data is obtained as follows:</p>
<ul>
<li>new_nonce := another (good) random number generated by the client; after this query, it is known to both client and server;</li>
<li><p>data := a serialization of </p>
<li>
<p>new_nonce := another (good) random number generated by the client; after this query, it is known to both client and server;</p>
</li>
<li>
<p>data := a serialization of </p>
<pre><code>p_q_inner_data_dc#a9f55f95 pq:string p:string q:string nonce:int128 server_nonce:int128 new_nonce:int256 dc:int = P_Q_inner_data;</code></pre>
<p>or of</p>
<pre><code>p_q_inner_data_temp_dc#56fddf88 pq:string p:string q:string nonce:int128 server_nonce:int128 new_nonce:int256 dc:int expires_in:int = P_Q_inner_data;</code></pre>
</li>
<li><p>encrypted_data := RSA_PAD (data, server_public_key), where RSA_PAD is a version of RSA with a variant of OAEP+ padding explained below in 4.1).</p>
<li>
<p>encrypted_data := RSA_PAD (data, server_public_key), where RSA_PAD is a version of RSA with a variant of OAEP+ padding explained below in 4.1).</p>
</li>
</ul>
<p>Someone might intercept the query and replace it with their own, independently decomposing pq into factors instead of the client. The only field that it makes sense to modify is new_nonce which would be the one an intruder would have to re-generate (because an intruder cannot decrypt the encrypted data sent by the client). Since all subsequent messages are encrypted using new_nonce or contain new_nonce_hash, they will not be processed by the client (an intruder would not be able to make it look as though they had been generated by the server because they would not contain new_nonce). Therefore, this intercept will only result in the intruder&#39;s completing the authorization key generation protocol in place of the client and creating a new key (that has nothing to do with the client); however, the same effect could be achieved simply by creating a new key in one&#39;s own name.</p>
<p>Someone might intercept the query and replace it with their own, independently decomposing pq into factors instead of the client. The only field that it makes sense to modify is new_nonce which would be the one an intruder would have to re-generate (because an intruder cannot decrypt the encrypted data sent by the client). Since all subsequent messages are encrypted using new_nonce or contain new_nonce_hash, they will not be processed by the client (an intruder would not be able to make it look as though they had been generated by the server because they would not contain new_nonce). Therefore, this intercept will only result in the intruder's completing the authorization key generation protocol in place of the client and creating a new key (that has nothing to do with the client); however, the same effect could be achieved simply by creating a new key in one's own name.</p>
<p>An alternative form of inner data (<code>p_q_inner_data_temp_dc</code>) is used to create temporary keys, that are only stored in the server RAM and are discarded after at most <code>expires_in</code> seconds. The server is free to discard its copy earlier. In all other respects the temporary key generation protocol is the same. After a temporary key is created, the client usually binds it to its principal authorisation key by means of the <a href="/method/auth.bindTempAuthKey">auth.bindTempAuthKey</a> method, and uses it for all client-server communication until it expires; then a new temporary key is generated. Thus Perfect Forward Secrecy (PFS) in client-server communication is achieved. <a href="/api/pfs">Read more about PFS »</a></p>
<p>4.1) RSA_PAD(data, server_public_key) mentioned above is implemented as follows:</p>
<ul>
<li>data_with_padding := data + random_padding_bytes; where random_padding_bytes are chosen so that the resulting length of data_with_padding is precisely 192 bytes, and data is the TL-serialized data to be encrypted as before. One has to check that data is not longer than 144 bytes.</li>
<li>data_pad_reversed := BYTE_REVERSE(data_with_padding); is obtained from data_with_padding by reversing the byte order.</li>
<li>data_with_padding := data + random_padding_bytes; -- where random_padding_bytes are chosen so that the resulting length of data_with_padding is precisely 192 bytes, and data is the TL-serialized data to be encrypted as before. One has to check that data is not longer than 144 bytes.</li>
<li>data_pad_reversed := BYTE_REVERSE(data_with_padding); -- is obtained from data_with_padding by reversing the byte order.</li>
<li>a random 32-byte temp_key is generated.</li>
<li>data_with_hash := data_pad_reversed + SHA256(temp_key + data_with_padding); after this assignment, data_with_hash is exactly 224 bytes long.</li>
<li>aes_encrypted := AES256_IGE(data_with_hash, temp_key, 0); AES256-IGE encryption with zero IV.</li>
<li>temp_key_xor := temp_key XOR SHA256(aes_encrypted); adjusted key, 32 bytes</li>
<li>key_aes_encrypted := temp_key_xor + aes_encrypted; exactly 256 bytes (2048 bits) long</li>
<li>data_with_hash := data_pad_reversed + SHA256(temp_key + data_with_padding); -- after this assignment, data_with_hash is exactly 224 bytes long.</li>
<li>aes_encrypted := AES256_IGE(data_with_hash, temp_key, 0); -- AES256-IGE encryption with zero IV.</li>
<li>temp_key_xor := temp_key XOR SHA256(aes_encrypted); -- adjusted key, 32 bytes</li>
<li>key_aes_encrypted := temp_key_xor + aes_encrypted; -- exactly 256 bytes (2048 bits) long</li>
<li>The value of key_aes_encrypted is compared with the RSA-modulus of server_pubkey as a big-endian 2048-bit (256-byte) unsigned integer. If key_aes_encrypted turns out to be greater than or equal to the RSA modulus, the previous steps starting from the generation of new random temp_key are repeated. Otherwise the final step is performed:</li>
<li>encrypted_data := RSA(key_aes_encrypted, server_pubkey); 256-byte big-endian integer is elevated to the requisite power from the RSA public key modulo the RSA modulus, and the result is stored as a big-endian integer consisting of exactly 256 bytes (with leading zero bytes if required).</li>
<li>encrypted_data := RSA(key_aes_encrypted, server_pubkey); -- 256-byte big-endian integer is elevated to the requisite power from the RSA public key modulo the RSA modulus, and the result is stored as a big-endian integer consisting of exactly 256 bytes (with leading zero bytes if required).</li>
</ul>
<p>5) Server responds with:</p>
<pre><code>server_DH_params_ok#d0e8075c nonce:int128 server_nonce:int128 encrypted_answer:string = Server_DH_Params;</code></pre>
<ol start="5">
<li>
<p>Server responds with:</p>
<p>server_DH_params_ok#d0e8075c nonce:int128 server_nonce:int128 encrypted_answer:string = Server_DH_Params;</p>
</li>
</ol>
<blockquote>
<p>If the query is incorrect, the server returns a <code>-404</code> error and the handshake must be restarted (any subsequent request also returns <code>-404</code>, even if it is correct).</p>
</blockquote>
<p>Here, encrypted_answer is obtained as follows:</p>
<ul>
<li>new_nonce_hash := 128 lower-order bits of SHA1 (new_nonce);</li>
<li><p>answer := serialization </p>
<li>
<p>new_nonce_hash := 128 lower-order bits of SHA1 (new_nonce);</p>
</li>
<li>
<p>answer := serialization </p>
<pre><code> server_DH_inner_data#b5890dba nonce:int128 server_nonce:int128 g:int dh_prime:string g_a:string server_time:int = Server_DH_inner_data;</code></pre>
</li>
<li><p>answer_with_hash := SHA1(answer) + answer + (0-15 random bytes); such that the length be divisible by 16;</p>
<li>
<p>answer_with_hash := SHA1(answer) + answer + (0-15 random bytes); such that the length be divisible by 16;</p>
</li>
<li>
<p>tmp_aes_key := SHA1(new_nonce + server_nonce) + substr (SHA1(server_nonce + new_nonce), 0, 12);</p>
</li>
<li>
<p>tmp_aes_iv := substr (SHA1(server_nonce + new_nonce), 12, 8) + SHA1(new_nonce + new_nonce) + substr (new_nonce, 0, 4);</p>
</li>
<li>
<p>encrypted_answer := AES256_ige_encrypt (answer_with_hash, tmp_aes_key, tmp_aes_iv); here, tmp_aes_key is a 256-bit key, and tmp_aes_iv is a 256-bit initialization vector. The same as in all the other instances that use AES encryption, the encrypted data is padded with random bytes to a length divisible by 16 immediately prior to encryption.</p>
</li>
<li>tmp_aes_key := SHA1(new_nonce + server_nonce) + substr (SHA1(server_nonce + new_nonce), 0, 12);</li>
<li>tmp_aes_iv := substr (SHA1(server_nonce + new_nonce), 12, 8) + SHA1(new_nonce + new_nonce) + substr (new_nonce, 0, 4);</li>
<li>encrypted_answer := AES256_ige_encrypt (answer_with_hash, tmp_aes_key, tmp_aes_iv); here, tmp_aes_key is a 256-bit key, and tmp_aes_iv is a 256-bit initialization vector. The same as in all the other instances that use AES encryption, the encrypted data is padded with random bytes to a length divisible by 16 immediately prior to encryption.</li>
</ul>
<p>Following this step, new_nonce is still known to client and server only. The client is certain that it is the server that responded and that the response was generated specifically in response to client query req_DH_params, since the response data are encrypted using new_nonce.</p>
<p>Client is expected to check whether <strong>p = dh_prime</strong> is a safe 2048-bit prime (meaning that both <strong>p</strong> and <strong>(p-1)/2</strong> are prime, and that 2<sup>2047 &lt; p &lt; 2</sup>2048), and that <strong>g</strong> generates a cyclic subgroup of prime order <strong>(p-1)/2</strong>, i.e. is a quadratic residue <strong>mod p</strong>. Since <strong>g</strong> is always equal to 2, 3, 4, 5, 6 or 7, this is easily done using quadratic reciprocity law, yielding a simple condition on <strong>p mod 4g</strong> — namely, <strong>p mod 8 = 7</strong> for <strong>g = 2</strong>; <strong>p mod 3 = 2</strong> for <strong>g = 3</strong>; no extra condition for <strong>g = 4</strong>; <strong>p mod 5 = 1 or 4</strong> for <strong>g = 5</strong>; <strong>p mod 24 = 19 or 23</strong> for <strong>g = 6</strong>; and <strong>p mod 7 = 3, 5 or 6</strong> for <strong>g = 7</strong>. After <strong>g</strong> and <strong>p</strong> have been checked by the client, it makes sense to cache the result, so as not to repeat lengthy computations in future.</p>
<p>If the verification takes too long time (which is the case for older mobile devices), one might initially run only 15 Miller—Rabin iterations for verifying primeness of <strong>p</strong> and <strong>(p - 1)/2</strong> with error probability not exceeding one billionth, and do more iterations later in the background.</p>
<p>Another optimization is to embed into the client application code a small table with some known “good” couples <strong>(g,p)</strong> (or just known safe primes <strong>p</strong>, since the condition on <strong>g</strong> is easily verified during execution), checked during code generation phase, so as to avoid doing such verification during runtime altogether. Server changes these values rarely, thus one usually has to put the current value of server&#39;s <strong>dh_prime</strong> into such a table. For example, current value of <strong>dh_prime</strong> equals (in big-endian byte order)</p>
<p>Client is expected to check whether <strong>p = dh_prime</strong> is a safe 2048-bit prime (meaning that both <strong>p</strong> and <strong>(p-1)/2</strong> are prime, and that 2^2047 &lt; p &lt; 2^2048), and that <strong>g</strong> generates a cyclic subgroup of prime order <strong>(p-1)/2</strong>, i.e. is a quadratic residue <strong>mod p</strong>. Since <strong>g</strong> is always equal to 2, 3, 4, 5, 6 or 7, this is easily done using quadratic reciprocity law, yielding a simple condition on <strong>p mod 4g</strong> -- namely, <strong>p mod 8 = 7</strong> for <strong>g = 2</strong>; <strong>p mod 3 = 2</strong> for <strong>g = 3</strong>; no extra condition for <strong>g = 4</strong>; <strong>p mod 5 = 1 or 4</strong> for <strong>g = 5</strong>; <strong>p mod 24 = 19 or 23</strong> for <strong>g = 6</strong>; and <strong>p mod 7 = 3, 5 or 6</strong> for <strong>g = 7</strong>. After <strong>g</strong> and <strong>p</strong> have been checked by the client, it makes sense to cache the result, so as not to repeat lengthy computations in future.</p>
<p>If the verification takes too long time (which is the case for older mobile devices), one might initially run only 15 Miller--Rabin iterations for verifying primeness of <strong>p</strong> and <strong>(p - 1)/2</strong> with error probability not exceeding one billionth, and do more iterations later in the background.</p>
<p>Another optimization is to embed into the client application code a small table with some known "good" couples <strong>(g,p)</strong> (or just known safe primes <strong>p</strong>, since the condition on <strong>g</strong> is easily verified during execution), checked during code generation phase, so as to avoid doing such verification during runtime altogether. Server changes these values rarely, thus one usually has to put the current value of server's <strong>dh_prime</strong> into such a table. For example, current value of <strong>dh_prime</strong> equals (in big-endian byte order)</p>
<pre><code>C7 1C AE B9 C6 B1 C9 04 8E 6C 52 2F 70 F1 3F 73 98 0D 40 23 8E 3E 21 C1 49 34 D0 37 56 3D 93 0F 48 19 8A 0A A7 C1 40 58 22 94 93 D2 25 30 F4 DB FA 33 6F 6E 0A C9 25 13 95 43 AE D4 4C CE 7C 37 20 FD 51 F6 94 58 70 5A C6 8C D4 FE 6B 6B 13 AB DC 97 46 51 29 69 32 84 54 F1 8F AF 8C 59 5F 64 24 77 FE 96 BB 2A 94 1D 5B CD 1D 4A C8 CC 49 88 07 08 FA 9B 37 8E 3C 4F 3A 90 60 BE E6 7C F9 A4 A4 A6 95 81 10 51 90 7E 16 27 53 B5 6B 0F 6B 41 0D BA 74 D8 A8 4B 2A 14 B3 14 4E 0E F1 28 47 54 FD 17 ED 95 0D 59 65 B4 B9 DD 46 58 2D B1 17 8D 16 9C 6B C4 65 B0 D6 FF 9C A3 92 8F EF 5B 9A E4 E4 18 FC 15 E8 3E BE A0 F8 7F A9 FF 5E ED 70 05 0D ED 28 49 F4 7B F9 59 D9 56 85 0C E9 29 85 1F 0D 81 15 F6 35 B1 05 EE 2E 4E 15 D0 4B 24 54 BF 6F 4F AD F0 34 B1 04 03 11 9C D8 E3 B9 2F CC 5B</code></pre>
<p>6) Client computes random 2048-bit number <em>b</em> (using a sufficient amount of entropy) and sends the server a message</p>
<pre><code>set_client_DH_params#f5045f1f nonce:int128 server_nonce:int128 encrypted_data:string = Set_client_DH_params_answer;</code></pre>
<ol start="6">
<li>
<p>Client computes random 2048-bit number <em>b</em> (using a sufficient amount of entropy) and sends the server a message</p>
<p>set_client_DH_params#f5045f1f nonce:int128 server_nonce:int128 encrypted_data:string = Set_client_DH_params_answer;</p>
</li>
</ol>
<p>Here, encrypted_data is obtained thus:</p>
<ul>
<li>g_b := pow(g, b) mod dh_prime;</li>
<li><p>data := serialization </p>
<li>
<p>g_b := pow(g, b) mod dh_prime;</p>
</li>
<li>
<p>data := serialization </p>
<pre><code> client_DH_inner_data#6643b654 nonce:int128 server_nonce:int128 retry_id:long g_b:string = Client_DH_Inner_Data</code></pre>
</li>
<li><p>data_with_hash := SHA1(data) + data + (0-15 random bytes); such that length be divisible by 16;</p>
<li>
<p>data_with_hash := SHA1(data) + data + (0-15 random bytes); such that length be divisible by 16;</p>
</li>
<li>
<p>encrypted_data := AES256_ige_encrypt (data_with_hash, tmp_aes_key, tmp_aes_iv);</p>
</li>
<li>encrypted_data := AES256_ige_encrypt (data_with_hash, tmp_aes_key, tmp_aes_iv);</li>
</ul>
<p>The retry_id field is equal to zero at the time of the first attempt; otherwise, it is equal to auth_key_aux_hash from the previous failed attempt (see Item 9).</p>
<p>7) Thereafter, auth_key equals <code>pow(g, {ab}) mod dh_prime</code>; on the server, it is computed as <code>pow(g_b, a) mod dh_prime</code>, and on the client as <code>(g_a)^b mod dh_prime</code>.</p>
<p>8) auth_key_hash is computed := 64 lower-order bits of SHA1 (auth_key). The server checks whether there already is another key with the same auth_key_hash and responds in one of the following ways.</p>
<h4><a class="anchor" name="dh-key-exchange-complete" href="#dh-key-exchange-complete"><i class="anchor-icon"></i></a>DH key exchange complete</h4>
<p>9) Server responds in one of three ways:</p>
<pre><code>dh_gen_ok#3bcbf734 nonce:int128 server_nonce:int128 new_nonce_hash1:int128 = Set_client_DH_params_answer;
<ol start="7">
<li>
<p>Thereafter, auth_key equals <code>pow(g, {ab}) mod dh_prime</code>; on the server, it is computed as <code>pow(g_b, a) mod dh_prime</code>, and on the client as <code>(g_a)^b mod dh_prime</code>.</p>
</li>
<li>
<p>auth_key_hash is computed := 64 lower-order bits of SHA1 (auth_key). The server checks whether there already is another key with the same auth_key_hash and responds in one of the following ways.</p>
</li>
</ol>
<h4><a class="anchor" href="#dh-key-exchange-complete" id="dh-key-exchange-complete" name="dh-key-exchange-complete"><i class="anchor-icon"></i></a>DH key exchange complete</h4>
<ol start="9">
<li>
<p>Server responds in one of three ways:</p>
<p>dh_gen_ok#3bcbf734 nonce:int128 server_nonce:int128 new_nonce_hash1:int128 = Set_client_DH_params_answer;
dh_gen_retry#46dc1fb9 nonce:int128 server_nonce:int128 new_nonce_hash2:int128 = Set_client_DH_params_answer;
dh_gen_fail#a69dae02 nonce:int128 server_nonce:int128 new_nonce_hash3:int128 = Set_client_DH_params_answer;</code></pre>
dh_gen_fail#a69dae02 nonce:int128 server_nonce:int128 new_nonce_hash3:int128 = Set_client_DH_params_answer;</p>
</li>
</ol>
<ul>
<li>new_nonce_hash1, new_nonce_hash2, and new_nonce_hash3 are obtained as the 128 lower-order bits of SHA1 of the byte string derived from the new_nonce string by adding a single byte with the value of 1, 2, or 3, and followed by another 8 bytes with auth_key_aux_hash. Different values are required to prevent an intruder from changing server response dh_gen_ok into dh_gen_retry.</li>
<li>auth_key_aux_hash is the 64 <em>higher-order</em> bits of SHA1(auth_key). It must not be confused with auth_key_hash.</li>
</ul>
<p>In the other case, the client goes to Item 6) generating a new <em>b</em>.<br>In the first case, the client and the server have negotiated auth_key, following which they forget all other temporary data, and the client creates another encrypted session using auth_key. At the same time, server_salt is initially set to <code>substr(new_nonce, 0, 8) XOR substr(server_nonce, 0, 8)</code>. If required, the client stores the difference between server_time received in 5) and its local time, to be able always to have a good approximation of server time which is required to generate correct message identifiers.</p>
<p>In the other case, the client goes to Item 6) generating a new <em>b</em>.
In the first case, the client and the server have negotiated auth_key, following which they forget all other temporary data, and the client creates another encrypted session using auth_key. At the same time, server_salt is initially set to <code>substr(new_nonce, 0, 8) XOR substr(server_nonce, 0, 8)</code>. If required, the client stores the difference between server_time received in 5) and its local time, to be able always to have a good approximation of server time which is required to generate correct message identifiers.</p>
<p><strong>IMPORTANT</strong>: Apart from the conditions on the Diffie-Hellman prime <strong>dh_prime</strong> and generator <strong>g</strong>, both sides are to check that <strong>g</strong>, <strong>g_a</strong> and <strong>g_b</strong> are greater than <strong>1</strong> and less than <strong>dh_prime - 1</strong>. We recommend checking that <strong>g_a</strong> and <strong>g_b</strong> are between <strong>2^{2048-64}</strong> and <strong>dh_prime - 2^{2048-64}</strong> as well.</p>
<h4><a class="anchor" name="error-handling-lost-queries-and-responses" href="#error-handling-lost-queries-and-responses"><i class="anchor-icon"></i></a>Error Handling (Lost Queries and Responses)</h4>
<h4><a class="anchor" href="#error-handling-lost-queries-and-responses" id="error-handling-lost-queries-and-responses" name="error-handling-lost-queries-and-responses"><i class="anchor-icon"></i></a>Error Handling (Lost Queries and Responses)</h4>
<p>If the client fails to receive any response to its query from the server within a certain time interval, it may simply re-send the query. If the server has already sent a response to this query (<em>exactly</em> the same request and not just similar: all the parameters during the repeat request must take on the same values) but it did not get to the client, the server will simply re-send the same response. The server remembers the response for up to 10 minutes after having received the query in 1). If the server has already forgotten the response or the requisite temporary data, the client will have to start from the beginning.</p>
<p>The server may consider that if the client has already sent in the next query using the data from the previous server response to the specific client, the response is known to have been received by the client and may be forgotten by the server.</p>
<h4><a class="anchor" name="usage-example" href="#usage-example"><i class="anchor-icon"></i></a>Usage Example</h4>
<p>An example of a complete list of queries required to generate an authorization key is shown on <a href="/mtproto/samples-auth_key">a separate page</a>.</p>
</div>
<p>The server may consider that if the client has already sent in the next query using the data from the previous server response to the specific client, the response is known to have been received by the client and may be forgotten by the server.</p></div>
</div>

View file

@ -47,7 +47,7 @@
</blockquote>
<p>In the examples below, the <a href="/mtproto#transport">transport</a> headers are omitted:</p>
<blockquote>
<p>For example, for an abridged version of the transport the client sends <code>0xef</code> as the first byte (<strong>important:</strong> only prior to the very first data packet), then packet length is encoded by a single byte (<code>0x01-0x7e</code> = data length divided by 4; or <code>0x7f</code> followed by 3 bytes (little endian) divided by 4) followed by the data themselves. In this case, server responses have the same form (although the server does not send <code>0xef</code>as the first byte).</p>
<p>For example, for the <a href="/mtproto/mtproto-transports#abridged">abridged version of the transport »</a>, the client sends <code>0xef</code> as the first byte (<strong>important:</strong> only prior to the very first data packet), then the packet length is encoded with a single byte (<code>0x01-0x7e</code> = data length divided by 4; or <code>0x7f</code> followed by 3 bytes (little endian) divided by 4) followed by the data itself. In this case, server responses have the same structure (although the server does not send <code>0xef</code>as the first byte).</p>
</blockquote>
<p>Detailed documentation on creating authorization keys is available <a href="/mtproto/auth_key">here »</a>.</p>
<h4><a class="anchor" href="#1-request-for-pq-authorization" id="1-request-for-pq-authorization" name="1-request-for-pq-authorization"><i class="anchor-icon"></i></a>1. Request for (p,q) Authorization</h4>
@ -57,7 +57,7 @@
<tr>
<th>Parameter</th>
<th>Offset, Length in bytes</th>
<th>Value</th>
<th>Value (hex)</th>
<th>Description</th>
</tr>
</thead>
@ -65,54 +65,55 @@
<tr>
<td>auth_key_id</td>
<td>0, 8</td>
<td><code>0</code></td>
<td>Since message is in plain text</td>
<td><code>0000000000000000</code></td>
<td>Since the message is in plain text</td>
</tr>
<tr>
<td>message_id</td>
<td>8, 8</td>
<td><code>51e57ac42770964a</code></td>
<td><code>af12fb209c111264</code></td>
<td>Exact unixtime * 2^32</td>
</tr>
<tr>
<td>message_length</td>
<td>16, 4</td>
<td><code>20</code></td>
<td><code>14000000</code> (20 in decimal)</td>
<td>Message body length</td>
</tr>
<tr>
<td>%(req_pq_multi)</td>
<td>20, 4</td>
<td><code>be7e8ef1</code></td>
<td><code>f18e7ebe</code></td>
<td>req_pq_multi constructor number from TL schema</td>
</tr>
<tr>
<td>nonce</td>
<td>24, 16</td>
<td><code>3E0549828CCA27E966B301A48FECE2FC</code></td>
<td><code>C10F3EA71170B031C2EC7365EAFA6D0E</code></td>
<td>Random number</td>
</tr>
</tbody>
</table>
<p>The header is 20 bytes long, the message body is 20 bytes long, and the entire message is 40 bytes in length.</p>
<pre><code>0000 | 00 00 00 00 00 00 00 00 4A 96 70 27 C4 7A E5 51
0010 | 14 00 00 00 f1 8e 7e be 3E 05 49 82 8C CA 27 E9
0020 | 66 B3 01 A4 8F EC E2 FC</code></pre>
<pre><code>0000 | 00 00 00 00 00 00 00 00 00 00 00 00 9c 11 12 64
0010 | 14 00 00 00 f1 8e 7e be C1 0F 3E A7 11 70 B0 31
0020 | C2 EC 73 65 EA FA 6D 0E</code></pre>
<h4><a class="anchor" href="#2-a-response-from-the-server-has-been-received-with-the-following-content" id="2-a-response-from-the-server-has-been-received-with-the-following-content" name="2-a-response-from-the-server-has-been-received-with-the-following-content"><i class="anchor-icon"></i></a>2. A response from the server has been received with the following content:</h4>
<pre><code>0000 | 00 00 00 00 00 00 00 00 01 C8 83 1E C9 7A E5 51
0010 | 40 00 00 00 63 24 16 05 3E 05 49 82 8C CA 27 E9
0020 | 66 B3 01 A4 8F EC E2 FC A5 CF 4D 33 F4 A1 1E A8
0030 | 77 BA 4A A5 73 90 73 30 08 17 ED 48 94 1A 08 F9
0040 | 81 00 00 00 15 C4 B5 1C 01 00 00 00 21 6B E8 6C
0050 | 02 2B B4 C3</code></pre>
<h5><a class="anchor" href="#response-decomposition-using-the-following-formula" id="response-decomposition-using-the-following-formula" name="response-decomposition-using-the-following-formula"><i class="anchor-icon"></i></a>Response decomposition using the following formula:</h5>
<pre><code>0000 | 00 00 00 00 00 00 00 00 01 ac 7d 9a 76 13 12 64
0010 | 50 00 00 00 63 24 16 05 C1 0F 3E A7 11 70 B0 31
0020 | C2 EC 73 65 EA FA 6D 0E bc 9a 0b 35 61 1c a3 78
0030 | 0c 78 c0 17 d2 9d e0 04 08 2a d4 7f de 84 c2 34
0040 | 9b 00 00 00 15 c4 b5 1c 03 00 00 00 a5 b7 f7 09
0050 | 35 5f c3 0b 21 6b e8 6c 02 2b b4 c3 85 fd 64 de
0060 | 85 1d 9d d0</code></pre>
<h5><a class="anchor" href="#response-decomposition-using-the-following-steps" id="response-decomposition-using-the-following-steps" name="response-decomposition-using-the-following-steps"><i class="anchor-icon"></i></a>Response decomposition using the following steps:</h5>
<pre><code>resPQ#05162463 nonce:int128 server_nonce:int128 pq:string server_public_key_fingerprints:Vector long = ResPQ </code></pre>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Offset, Length in bytes</th>
<th>Value</th>
<th>Value (hex)</th>
<th>Description</th>
</tr>
</thead>
@ -120,71 +121,88 @@
<tr>
<td>auth_key_id</td>
<td>0, 8</td>
<td><code>0</code></td>
<td><code>0000000000000000</code></td>
<td>Since message is in plain text</td>
</tr>
<tr>
<td>message_id</td>
<td>8, 8</td>
<td><code>51E57AC91E83C801</code></td>
<td><code>01ac7d9a76131264</code></td>
<td>Server message ID</td>
</tr>
<tr>
<td>message_length</td>
<td>16, 4</td>
<td><code>64</code></td>
<td><code>50000000</code> (80 in decimal)</td>
<td>Message body length</td>
</tr>
<tr>
<td>%(resPQ)</td>
<td>20, 4</td>
<td><code>05162463</code></td>
<td><code>63241605</code></td>
<td>resPQ constructor number from TL schema</td>
</tr>
<tr>
<td>nonce</td>
<td>24, 16</td>
<td><code>3E0549828CCA27E966B301A48FECE2FC</code></td>
<td><code>C10F3EA71170B031C2EC7365EAFA6D0E</code></td>
<td>Value generated by client in Step 1</td>
</tr>
<tr>
<td>server_nonce</td>
<td>40, 16</td>
<td><code>A5CF4D33F4A11EA877BA4AA573907330</code></td>
<td><code>bc9a0b35611ca3780c78c017d29de004</code></td>
<td>Server-generated random number</td>
</tr>
<tr>
<td>pq</td>
<td>56, 12</td>
<td><code>17ED48941A08F981</code></td>
<td><code>082ad47fde84c2340b000000</code></td>
<td>Single-byte prefix denoting length, an 8-byte string, and three bytes of padding</td>
</tr>
<tr>
<td>%(Vector long)</td>
<td>68, 4</td>
<td><code>1cb5c415</code></td>
<td><code>15c4b51c</code></td>
<td><em>Vector long</em> constructor number from TL schema</td>
</tr>
<tr>
<td>count</td>
<td>72, 4</td>
<td><code>1</code></td>
<td><code>03000000</code></td>
<td>Number of elements in key fingerprint list</td>
</tr>
<tr>
<td>fingerprints[]</td>
<td>fingerprints[0]</td>
<td>76, 8</td>
<td><code>c3b42b026ce86b21</code></td>
<td><code>a5b7f709355fc30b</code></td>
<td>64 lower-order bits of SHA1 (server_public_key)</td>
</tr>
<tr>
<td>fingerprints[1]</td>
<td>76, 8</td>
<td><code>216be86c022bb4c3</code></td>
<td>64 lower-order bits of SHA1 (server_public_key)</td>
</tr>
<tr>
<td>fingerprints[2]</td>
<td>76, 8</td>
<td><code>85fd64de851d9dd0</code></td>
<td>64 lower-order bits of SHA1 (server_public_key)</td>
</tr>
</tbody>
</table>
<p>The <strong>server_public_key</strong> public key has been selected whose fingerprint corresponds to the only one received from the server: <code>c3b42b026ce86b21</code>.</p>
<h4><a class="anchor" href="#3-pq--17ed48941a08f981-decomposed-into-2-prime-cofactors" id="3-pq--17ed48941a08f981-decomposed-into-2-prime-cofactors" name="3-pq--17ed48941a08f981-decomposed-into-2-prime-cofactors"><i class="anchor-icon"></i></a>3. Pq = 17ED48941A08F981 decomposed into 2 prime cofactors:</h4>
<pre><code>p = 494C553B
q = 53911073</code></pre>
<p>In our case, the client only has the following public keys, with the following fingerprints:</p>
<ul>
<li><code>03268d20df9858b2</code></li>
<li><code>85fd64de851d9dd0</code></li>
</ul>
<p>Let's choose the only matching key, the one with fingerprint equal to <code>85fd64de851d9dd0</code>.</p>
<h4><a class="anchor" href="#3-pq--2ad47fde84c2340b-bigendian--decimal-3086232238342419611-decomposed-into-2-prime-cofactors" id="3-pq--2ad47fde84c2340b-bigendian--decimal-3086232238342419611-decomposed-into-2-prime-cofactors" name="3-pq--2ad47fde84c2340b-bigendian--decimal-3086232238342419611-decomposed-into-2-prime-cofactors"><i class="anchor-icon"></i></a>3. Pq = 2ad47fde84c2340b (bigendian =&gt; decimal 3086232238342419611) decomposed into 2 prime cofactors:</h4>
<pre><code>p = 1743948187 (bigendian hex 67f2899b)
q = 1769681153 (bigendian hex 697b3101)</code></pre>
<h4><a class="anchor" href="#4-encrypted-data-generation" id="4-encrypted-data-generation" name="4-encrypted-data-generation"><i class="anchor-icon"></i></a>4. encrypted_data Generation</h4>
<pre><code>p_q_inner_data#83c95aec pq:string p:string q:string nonce:int128 server_nonce:int128 new_nonce:int256 = P_Q_inner_data</code></pre>
<pre><code>p_q_inner_data_dc#a9f55f95 pq:bytes p:bytes q:bytes nonce:int128 server_nonce:int128 new_nonce:int256 dc:int = P_Q_inner_data;</code></pre>
<table class="table">
<thead>
<tr>
@ -198,51 +216,57 @@ q = 53911073</code></pre>
<tr>
<td>%(p_q_inner_data)</td>
<td>0, 4</td>
<td><code>83c95aec</code></td>
<td>p_q_inner_data constructor number from TL schema</td>
<td><code>955ff5a9</code></td>
<td>p_q_inner_data_dc constructor number from TL schema</td>
</tr>
<tr>
<td>pq</td>
<td>4, 12</td>
<td><code>17ED48941A08F981</code></td>
<td><code>082ad47fde84c2340b000000</code></td>
<td>Single-byte prefix denoting length, 8-byte string, and three bytes of padding</td>
</tr>
<tr>
<td>p</td>
<td>16, 8</td>
<td><code>494C553B</code></td>
<td><code>0467f2899b000000</code></td>
<td>First prime cofactor: single-byte prefix denoting length, 4-byte string, and three bytes of padding</td>
</tr>
<tr>
<td>q</td>
<td>24, 8</td>
<td><code>53911073</code></td>
<td><code>04697b3101000000</code></td>
<td>Second prime cofactor: single-byte prefix denoting length, 4-byte string, and three bytes of padding</td>
</tr>
<tr>
<td>nonce</td>
<td>32, 16</td>
<td><code>3E0549828CCA27E966B301A48FECE2FC</code></td>
<td><code>C10F3EA71170B031C2EC7365EAFA6D0E</code></td>
<td>Value generated by client in Step 1</td>
</tr>
<tr>
<td>server_nonce</td>
<td>48, 16</td>
<td><code>A5CF4D33F4A11EA877BA4AA573907330</code></td>
<td><code>bc9a0b35611ca3780c78c017d29de004</code></td>
<td>Value received from server in Step 2</td>
</tr>
<tr>
<td>new_nonce</td>
<td>64, 32</td>
<td><code>311C85DB234AA2640AFC4A76A735CF5B</code> <code>1F0FD68BD17FA181E1229AD867CC024D</code></td>
<td><code>311C85DB234AA2640AFC4A76A735CF5B1F0FD68BD17FA181E1229AD867CC024D</code></td>
<td>Client-generated random number</td>
</tr>
<tr>
<td>dc</td>
<td>96, 4</td>
<td><code>02000000</code></td>
<td>DC ID: <code>10000</code> (decimal) has to be added to the DC ID to connect to the test servers; it has to be made negative if the DC we're connecting to is a media (not CDN) DC.</td>
</tr>
</tbody>
</table>
<p>The serialization of <em>P_Q_inner_data</em> produces some string <strong>data</strong>. This is followed by <strong>encrypted_data</strong>:</p>
<pre><code>SHA1 (data) = DB761C27718A2305044F71F2AD951629D78B2449
RSA (data_with_hash, server_public_key) = 7BB0100A523161904D9C69FA04BC60DECFC5DD74B99995C768EB60D8716E2109BAF2D4601DAB6B09610DC11067BB89021E09471FCFA52DBD0F23204AD8CA8B012BF40A112F44695AB6C266955386114EF5211E6372227ADBD34995D3E0E5FF02EC63A43F9926878962F7C570E6A6E78BF8366AF917A5272675C46064BE62E3E202EFA8B1ADFB1C32A898C2987BE27B5F31D57C9BB963ABCB734B16F652CEDB4293CBB7C878A3A3FFAC9DBEA9DF7C67BC9E9508E111C78FC46E057F5C65ADE381D91FEE430A6B576A99BDF8551FDB1BE2B57069B1A45730618F27427E8A04720B4971EF4A9215983D68F2830C3EAA6E40385562F970D38A05C9F1246DC33438E6</code></pre>
<p>The length of the final string was 256 bytes.</p>
<p>The length of the final string is 256 bytes.</p>
<h5><a class="anchor" href="#request-to-start-diffie-hellman-key-exchange" id="request-to-start-diffie-hellman-key-exchange" name="request-to-start-diffie-hellman-key-exchange"><i class="anchor-icon"></i></a>Request to Start Diffie-Hellman Key Exchange</h5>
<pre><code>req_DH_params#d712e4be nonce:int128 server_nonce:int128 p:string q:string public_key_fingerprint:long encrypted_data:string = Server_DH_Params</code></pre>
<table class="table">
@ -264,49 +288,49 @@ RSA (data_with_hash, server_public_key) = 7BB0100A523161904D9C69FA04BC60DECFC5DD
<tr>
<td>message_id</td>
<td>8, 8</td>
<td><code>51e57ac917717a27</code></td>
<td><code>fa1bc56176131264</code></td>
<td>Exact unixtime * 2^32</td>
</tr>
<tr>
<td>message_length</td>
<td>16, 4</td>
<td><code>320</code></td>
<td><code>40010000</code> (decimal 320)</td>
<td>Message body length</td>
</tr>
<tr>
<td>%(req_DH_params)</td>
<td>20, 4</td>
<td><code>d712e4be</code></td>
<td><code>bee412d7</code></td>
<td>req_DH_params constructor number from TL schema</td>
</tr>
<tr>
<td>nonce</td>
<td>24, 16</td>
<td><code>3E0549828CCA27E966B301A48FECE2FC</code></td>
<td><code>C10F3EA71170B031C2EC7365EAFA6D0E</code></td>
<td>Value generated by client in Step 1</td>
</tr>
<tr>
<td>server_nonce</td>
<td>40, 16</td>
<td><code>A5CF4D33F4A11EA877BA4AA573907330</code></td>
<td><code>bc9a0b35611ca3780c78c017d29de004</code></td>
<td>Value received from server in Step 2</td>
</tr>
<tr>
<td>p</td>
<td>56, 8</td>
<td><code>494C553B</code></td>
<td><code>0467f2899b000000</code></td>
<td>First prime cofactor: single-byte prefix denoting length, 4-byte string, and three bytes of padding</td>
</tr>
<tr>
<td>q</td>
<td>64, 8</td>
<td><code>53911073</code></td>
<td><code>04697b3101000000</code></td>
<td>Second prime cofactor: single-byte prefix denoting length, 4-byte string, and three bytes of padding</td>
</tr>
<tr>
<td>public_key_fingerprint</td>
<td>72, 8</td>
<td><code>c3b42b026ce86b21</code></td>
<td><code>85fd64de851d9dd0</code></td>
<td>Fingerprint of public key used</td>
</tr>
<tr>
@ -317,28 +341,10 @@ RSA (data_with_hash, server_public_key) = 7BB0100A523161904D9C69FA04BC60DECFC5DD
</tr>
</tbody>
</table>
<pre><code>0000 | 00 00 00 00 00 00 00 00 27 7A 71 17 C9 7A E5 51
0010 | 40 01 00 00 BE E4 12 D7 3E 05 49 82 8C CA 27 E9
0020 | 66 B3 01 A4 8F EC E2 FC A5 CF 4D 33 F4 A1 1E A8
0030 | 77 BA 4A A5 73 90 73 30 04 49 4C 55 3B 00 00 00
0040 | 04 53 91 10 73 00 00 00 21 6B E8 6C 02 2B B4 C3
0050 | FE 00 01 00 7B B0 10 0A 52 31 61 90 4D 9C 69 FA
0060 | 04 BC 60 DE CF C5 DD 74 B9 99 95 C7 68 EB 60 D8
0070 | 71 6E 21 09 BA F2 D4 60 1D AB 6B 09 61 0D C1 10
0080 | 67 BB 89 02 1E 09 47 1F CF A5 2D BD 0F 23 20 4A
0090 | D8 CA 8B 01 2B F4 0A 11 2F 44 69 5A B6 C2 66 95
00A0 | 53 86 11 4E F5 21 1E 63 72 22 7A DB D3 49 95 D3
00B0 | E0 E5 FF 02 EC 63 A4 3F 99 26 87 89 62 F7 C5 70
00C0 | E6 A6 E7 8B F8 36 6A F9 17 A5 27 26 75 C4 60 64
00D0 | BE 62 E3 E2 02 EF A8 B1 AD FB 1C 32 A8 98 C2 98
00E0 | 7B E2 7B 5F 31 D5 7C 9B B9 63 AB CB 73 4B 16 F6
00F0 | 52 CE DB 42 93 CB B7 C8 78 A3 A3 FF AC 9D BE A9
0100 | DF 7C 67 BC 9E 95 08 E1 11 C7 8F C4 6E 05 7F 5C
0110 | 65 AD E3 81 D9 1F EE 43 0A 6B 57 6A 99 BD F8 55
0120 | 1F DB 1B E2 B5 70 69 B1 A4 57 30 61 8F 27 42 7E
0130 | 8A 04 72 0B 49 71 EF 4A 92 15 98 3D 68 F2 83 0C
0140 | 3E AA 6E 40 38 55 62 F9 70 D3 8A 05 C9 F1 24 6D
0150 | C3 34 38 E6</code></pre>
<pre><code>0000 | 00 00 00 00 00 00 00 00 fa 1b c5 61 76 13 12 64
0010 | 40 01 00 00 BE E4 12 D7 C1 0F 3E A7 11 70 B0 31
0020 | C2 EC 73 65 EA FA 6D 0E bc 9a 0b 35 61 1c a3 78
0030 | 0c 78 c0 17 d2 9d e0 04</code></pre>
<h4><a class="anchor" href="#5-a-response-from-the-server-has-been-received-with-the-following-content" id="5-a-response-from-the-server-has-been-received-with-the-following-content" name="5-a-response-from-the-server-has-been-received-with-the-following-content"><i class="anchor-icon"></i></a>5. A response from the server has been received with the following content:</h4>
<pre><code>0000 | 00 00 00 00 00 00 00 00 01 54 43 36 CB 7A E5 51
0010 | 78 02 00 00 5C 07 E8 D0 3E 05 49 82 8C CA 27 E9