<p>As of version 4.6, major Telegram clients are using <strong>MTProto 2.0</strong>.
MTProto v.1.0 is deprecated and is currently being phased out.</p>
</blockquote>
<p>This article describes the basic layer of the MTProto protocol version 2.0 (Cloud chats, server-client encryption). The principal differences from version 1.0 (<ahref="/mtproto/description_v1">described here</a> for reference) are as follows:</p>
<ul>
<li>SHA-256 is used instead of SHA-1;</li>
<li>Padding bytes are involved in the computation of <strong>msg_key</strong>;</li>
<li><strong>msg_key</strong> depends not only on the message to be encrypted, but on a portion of <strong>auth_key</strong> as well;</li>
<li>12..1024 padding bytes are used instead of 0..15 padding bytes in v.1.0.</li>
<p>Before a message (or a multipart message) is transmitted over a network using a transport protocol, it is encrypted in a certain way, and an external header is added at the top of the message that consists of a 64-bit key identifier <strong>auth_key_id</strong> (that uniquely identifies an authorization key for the server as well as the user) and a 128-bit message key <strong>msg_key</strong>. </p>
<p>The authorization key <strong>auth_key</strong> combined with the message key <strong>msg_key</strong> define an actual 256-bit key <strong>aes_key</strong> and a 256-bit initialization vector <strong>aes_iv</strong>, which are used to encrypt the message using AES-256 encryption in infinite garble extension (IGE) mode. Note that the initial part of the message to be encrypted contains variable data (session, message ID, sequence number, server salt) that obviously influences the message key (and thus the AES key and iv). In <strong>MTProto 2.0</strong>, the message key is defined as the 128 middle bits of the SHA-256 of the message body (including session, message ID, padding, etc.) prepended by 32 bytes taken from the authorization key. In the older <strong>MTProto 1.0</strong>, the message key was computed as the lower 128 bits of SHA-1 of the message body, excluding the padding bytes.</p>
<p>Multipart messages are encrypted as a single message. </p>
<p>Got questions about this setup? — Check out the <ahref="http://core.telegram.org/techfaq">Advanced FAQ</a>!</p>
</blockquote>
<h6><strong>Note 1</strong></h6>
<p>Each plaintext message to be encrypted in MTProto always contains the following data to be checked upon decryption in order to make the system robust against known problems with the components:</p>
<ul>
<li>server salt (64-Bit)</li>
<li>session id</li>
<li>message sequence number</li>
<li>message length</li>
<li>time</li>
</ul>
<h6><strong>Note 2</strong></h6>
<p>Telegram's <strong>End-to-end</strong> encrypted Secret Chats are using an additional layer of encryption on top of the described above. See <ahref="https://core.telegram.org/api/end-to-end">Secret Chats, End-to-End encryption</a> for details.</p>
<p>A 2048-bit key shared by the client device and the server, created upon user registration directly on the client device by exchanging Diffie-Hellman keys, and never transmitted over a network. Each authorization key is user-specific. There is nothing that prevents a user from having several keys (that correspond to “permanent sessions” on different devices), and some of these may be locked forever in the event the device is lost. See also <ahref="/mtproto/auth_key">Creating an Authorization Key</a>.</p>
<p>A 2048-bit RSA key used by the server digitally to sign its own messages while registration is underway and the authorization key is being generated. The application has a built-in public server key which can be used to verify a signature but cannot be used to sign messages. A private server key is stored on the server and changed very infrequently.</p>
<p>The 64 lower-order bits of the SHA1 hash of the authorization key are used to indicate which particular key was used to encrypt a message. Keys must be uniquely defined by the 64 lower-order bits of their SHA1, and in the event of a collision, an authorization key is regenerated. A zero key identifier means that encryption is not used which is permissible for a limited set of message types used during registration to generate an authorization key in a Diffie-Hellman exchange. <strong>For MTProto 2.0, SHA1 is still used here, because auth_key_id should identify the authorization key used independently of the protocol version.</strong></p>
<p>A (random) 64-bit number generated by the client to distinguish between individual sessions (for example, between different instances of the application, created with the same authorization key). The session in conjunction with the key identifier corresponds to an application instance. The server can maintain session state. <em>Under no circumstances can a message meant for one session be sent into a different session</em>. The server may unilaterally forget any client sessions; clients should be able to handle this. </p>
<p>A (random) 64-bit number changed every 30 minutes (separately for each session) at the request of the server. All subsequent messages must contain the new salt (although, messages with the old salt are still accepted for a further 1800 seconds). Required to protect against replay attacks and certain tricks associated with adjusting the client clock to a moment in the distant future.</p>
<p>A (time-dependent) 64-bit number used uniquely to identify a message within a session. Client message identifiers are divisible by 4, server message identifiers modulo 4 yield 1 if the message is a response to a client message, and 3 otherwise. Client message identifiers must increase monotonically (within a single session), the same as server message identifiers, and must approximately equal unixtime*2^32. This way, a message identifier points to the approximate moment in time the message was created. A message is rejected over 300 seconds after it is created or 30 seconds before it is created (this is needed to protect from replay attacks). In this situation, it must be re-sent with a different identifier (or placed in a container with a higher identifier). The identifier of a message container must be strictly greater than those of its nested messages.</p>
<p><strong>Important</strong>: to counter replay-attacks the lower 32 bits of <strong>msg_id</strong> passed by the client must not be empty and must present a fractional part of the time point when the message was created.</p>
<p>A message requiring an explicit acknowledgment. These include all the user and many service messages, virtually all with the exception of containers and acknowledgments. </p>
<h4><aclass="anchor"href="#message-sequence-number-msg-seqno"id="message-sequence-number-msg-seqno"name="message-sequence-number-msg-seqno"><iclass="anchor-icon"></i></a>Message Sequence Number (msg_seqno)</h4>
<p>A 32-bit number equal to twice the number of “content-related” messages (those requiring acknowledgment, and in particular those that are not containers) created by the sender prior to this message and subsequently incremented by one if the current message is a content-related message. A container is always generated after its entire contents; therefore, its sequence number is greater than or equal to the sequence numbers of the messages contained in it.</p>
<p>In <strong>MTProto 2.0</strong>, the middle 128 bits of the SHA-256 hash of the message to be encrypted (including the internal header and the <em>padding bytes</em> for MTProto 2.0), prepended by a 32-byte fragment of the authorization key.</p>
<p>In <strong>MTProto 1.0</strong>, message key was defined differently, as the lower 128 bits of the SHA-1 hash of the message to be encrypted, with padding bytes excluded from the computation of the hash. Authorization key was not involved in this computation.</p>
<p>A header (16 bytes) added before a message or a container before it is all encrypted together. Consists of the server salt (64 bits) and the session (64 bits).</p>
<p>A header (24 bytes) added before an encrypted message or a container. Consists of the key identifier <strong>auth_key_id</strong> (64 bits) and the message key <strong>msg_key</strong> (128 bits).</p>
<p>External header + encrypted message or container.</p>
<h3><aclass="anchor"href="#defining-aes-key-and-initialization-vector"id="defining-aes-key-and-initialization-vector"name="defining-aes-key-and-initialization-vector"><iclass="anchor-icon"></i></a>Defining AES Key and Initialization Vector</h3>
<p>The 2048-bit authorization key (auth_key) and the 128-bit message key (msg_key) are used to compute a 256-bit AES key (aes_key) and a 256-bit initialization vector (aes_iv) which are subsequently used to encrypt the part of the message to be encrypted (i. e. everything with the exception of the external header that is added later) with AES-256 in infinite garble extension (IGE) mode.</p>
<p>For MTProto 2.0, the algorithm for computing aes_key and aes_iv from auth_key and msg_key is as follows.</p>
<p>where x = 0 for messages from client to server and x = 8 for those from server to client.</p>
<p><em>For the obsolete MTProto 1.0, msg_key, aes_key, and aes_iv were computed differently (see <ahref="/mtproto/description_v1#defining-aes-key-and-initialization-vector">this document</a> for reference).</em></p>
<p>The lower-order 1024 bits of auth_key are not involved in the computation. They may (together with the remaining bits or separately) be used on the client device to encrypt the local copy of the data received from the server. The 512 lower-order bits of auth_key are not stored on the server; therefore, if the client device uses them to encrypt local data and the user loses the key or the password, data decryption of local data is impossible (even if data from the server could be obtained).</p>
<p>In MTProto 1.0, when AES was used to encrypt a block of data of a length not divisible by 16 bytes, the data was padded with 0 to 15 random padding bytes <strong>random_padding</strong> to a length divisible by 16 bytes prior to encryption. <strong>In MTProto 2.0, this padding is taken into account when computing <code>msg_key</code>. Note that MTProto 2.0 requires from 12 to 1024 bytes of padding, still subject to the condition that the resulting message length be divisible by 16 bytes.</strong></p>
<h3><aclass="anchor"href="#using-mtproto-20-instead-of-mtproto-10"id="using-mtproto-20-instead-of-mtproto-10"name="using-mtproto-20-instead-of-mtproto-10"><iclass="anchor-icon"></i></a>Using MTProto 2.0 instead of MTProto 1.0</h3>
<p>A client may either use only MTProto 2.0 or only MTProto 1.0 in the same TCP connection. The server detects the protocol used by the first message received from the client, and then uses the same encryption for its messages, and expects the client to use the same encryption henceforth. We recommend using MTProto 2.0; MTProto 1.0 is deprecated and supported for backward compatibility only.</p>
<p>When an encrypted message is received, it <em>must</em> be checked that <strong>msg_key</strong> is <em>in fact</em> equal to the 128 middle bits of the SHA-256 of the decrypted data with a 32-byte fragment of <strong>auth_key</strong> prepended to it, and that msg_id has even parity for messages from client to server, and odd parity for messages from server to client.</p>
<p>In addition, the identifiers (msg_id) of the last N messages received from the other side must be stored, and if a message comes in with msg_id lower than all or equal to any of the stored values, the message is to be ignored. Otherwise, the new message msg_id is added to the set, and, if the number of stored msg_id values is greater than N, the oldest (i. e. the lowest) is forgotten.</p>
<p>On top of this, msg_id values that belong over 30 seconds in the future or over 300 seconds in the past are to be ignored. This is especially important for the server. The client would also find this useful (to protect from a replay attack), but only if it is certain of its time (for example, if its time has been synchronized with that of the server).</p>
<p>Certain client-to-server service messages containing data sent by the client to the server (for example, msg_id of a recent client query) may, nonetheless, be processed on the client even if the time appears to be “incorrect”. This is especially true of messages to change server_salt and notifications of invalid client time. See <ahref="/mtproto/service_messages">Mobile Protocol: Service Messages</a>.</p>
<h3><aclass="anchor"href="#storing-an-authorization-key-on-a-client-device"id="storing-an-authorization-key-on-a-client-device"name="storing-an-authorization-key-on-a-client-device"><iclass="anchor-icon"></i></a>Storing an Authorization Key on a Client Device</h3>
<p>It may be suggested to users concerned with security that they password protect the authorization key in approximately the same way as in ssh. This can be accomplished by prepending the value of cryptographic hash function, such as SHA-256, of the key to the front of the key, following which the entire string is encrypted using AES in CBC mode and a key equal to the user's (text) password. When the user inputs the password, the stored protected password is decrypted and verified by checking the SHA-256 value. From the user's standpoint, this is practically the same as using an application or a website password.</p>
<p>Special plain-text messages may be used to create an authorization key as well as to perform a time synchronization. They begin with auth_key_id = 0 (64 bits) which means that there is no auth_key. This is followed directly by the message body in serialized format without internal or external headers. A message identifier (64 bits) and body length in bytes (32 bytes) are added before the message body.</p>
<p>Only a very limited number of messages of special types can be transmitted as plain text. </p>
<h3><aclass="anchor"href="#schematic-presentation-of-messages"id="schematic-presentation-of-messages"name="schematic-presentation-of-messages"><iclass="anchor-icon"></i></a>Schematic Presentation of Messages</h3>
<p><strong>MTProto 2.0 uses 12..1024 padding bytes, instead of the 0..15 used in MTProto 1.0</strong></p>
<h3><aclass="anchor"href="#creating-an-authorization-key"id="creating-an-authorization-key"name="creating-an-authorization-key"><iclass="anchor-icon"></i></a>Creating an Authorization Key</h3>
<p>An authorization key is normally created once for every user during the application installation process immediately prior to registration. Registration itself, in actuality, occurs after the authorization key is created. However, a user may be prompted to complete the registration form while the authorization key is being generated in the background. Intervals between user key strokes may be used as a source of entropy in the generation of high-quality random numbers required for the creation of an authorization key.</p>
<p>See <ahref="/mtproto/auth_key">Creating an Authorization Key</a>.</p>
<p>During the creation of the authorization key, the client obtains its server salt (to be used with the new key for all communication in the near future). The client then creates an encrypted session using the newly generated key, and subsequent communication occurs within that session (including the transmission of the user's registration information and phone number validation) unless the client creates a new session. The client is free to create new or additional sessions at any time by choosing a new random session_id.</p></div>
</div>
</div>
</div>
<divclass="footer_wrap">
<divclass="footer_columns_wrap footer_desktop">
<divclass="footer_column footer_column_telegram">
<h5>Telegram</h5>
<divclass="footer_telegram_description"></div>
Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed.
