payload

README

Notes about implementation

Technical problems you might get stuck

• -404 error on invalid padding size

  [!TIP]

  For some reason, instead of making additional error (to explain developers what's wrong and force them to use 12-1024 random padding). Instead, Telegram server (canonical implementation of mtproto) returns -404 to EVERY error that it might get while parsing message.

  How to handle that: write few tests and include additional check that padding size is strictly between 12 and 1024 bytes, including for decrytion functions.

Documentation

Index

• func BuildEnvelope(salt, sessionID uint64, seqNo uint32, msgID MsgID, msg []byte, ...) (res []byte)
• type Cipher
  • func NewClientCipher(rand io.Reader, key Key) Cipher
  • func NewServerCipher(rand io.Reader, key Key) Cipher
• type Encrypted
  • func (msg *Encrypted) NeedToAck() bool
• type Envelope
  • func DeserializeEnvelope(b []byte) (*Envelope, error)
  • func (e *Envelope) Serialize(padder io.Reader) (res []byte)
• type Initiator
• type Int128
  • func MessageKey(authKey *Key, plaintextPadded []byte, mode Side) Int128
• type Int256
  • func Keys(authKey *Key, msgKey Int128, mode Side) (key, iv Int256)
• type Key
  • func (k *Key) ID() [8]byte
• type MsgID
  • func GenerateMessageID(now time.Time, initiator Initiator, msgSide Side) MsgID
  • func (m MsgID) Initiator() Initiator
  • func (m MsgID) Side() Side
  • func (m MsgID) Time() time.Time
  • func (m MsgID) UniqueID() uint32
• type Side
  • func (s Side) Invert() Side
  • func (s Side) String() string
  • func (s Side) X() int
• type Unencrypted
  • func DeserializeUnencrypted(data []byte) (*Unencrypted, error)
  • func (msg *Unencrypted) Serialize() (res []byte)

Functions

func BuildEnvelope

func BuildEnvelope(salt, sessionID uint64, seqNo uint32, msgID MsgID, msg []byte, padder io.Reader) (res []byte)

Types

type Cipher

type Cipher interface {
	Encrypt(keyID [8]byte, content []byte) ([]byte, error)
	Decrypt(data []byte) ([]byte, error)
}

func NewClientCipher

func NewClientCipher(rand io.Reader, key Key) Cipher

NewClientCipher creates new client-side Cipher.

func NewServerCipher

func NewServerCipher(rand io.Reader, key Key) Cipher

NewServerCipher creates new server-side Cipher.

type Encrypted

type Encrypted struct {
	Salt      uint64
	SessionID uint64
	ID        MsgID
	SeqNo     uint32
	Msg       []byte
}

func (*Encrypted) NeedToAck

func (msg *Encrypted) NeedToAck() bool

type Envelope

type Envelope struct {
	Salt      uint64
	SessionID uint64
	MsgID     MsgID
	SeqNo     uint32
	Msg       []byte
}

Envelope is a data inside encrypted part of encrypted message.

compatible with MTProto 1.0 and 2.0

https://core.telegram.org/mtproto/description#encrypted-message-encrypted-data

func DeserializeEnvelope

func DeserializeEnvelope(b []byte) (*Envelope, error)

func (*Envelope) Serialize

func (e *Envelope) Serialize(padder io.Reader) (res []byte)

if padder set to nil, padding won't be created

type Initiator

type Initiator int8

const (
	InitiatorClient Initiator = iota
	InitiatorServer
)

type Int128

type Int128 = [16]byte

func MessageKey

func MessageKey(authKey *Key, plaintextPadded []byte, mode Side) Int128

MessageKey computes message key for provided auth_key and padded payload.

type Int256

type Int256 = [32]byte

func Keys

func Keys(authKey *Key, msgKey Int128, mode Side) (key, iv Int256)

Keys returns (aes_key, aes_iv) pair for AES-IGE.

See https://core.telegram.org/mtproto/description#defining-aes-key-and-initialization-vector

Example:

key, iv := crypto.Keys(authKey, messageKey, crypto.Client)
cipher, err := aes.NewCipher(key[:])
if err != nil {
	return nil, err
}
encryptor := ige.NewIGEEncrypter(cipher, iv[:])

type Key

type Key [256]byte

func (*Key) ID

func (k *Key) ID() [8]byte

type MsgID

type MsgID uint64

MsgID is a unique identifier of a message in MTProto protocol.

Scheme of message_id (showed):

|1-31|32-61|62|63|
|A   |B    |C |D |

Where:

• A: Approximately equal current unix time
• B: Any random unique 30-bit number
• C: Indicates the message initiator: 0 — for client-initiated (request or server response), 1 — for server-initiated (notification or client response to server request).
• D: message side (0 means client sent message, 1 means server did)

More info: https://core.telegram.org/mtproto/description#message-identifier-msg-id

func GenerateMessageID

func GenerateMessageID(now time.Time, initiator Initiator, msgSide Side) MsgID

GenerateMessageId essentially gives unix timestamp, but in a horribly specific way.

See MsgID for more info how it works

func (MsgID) Initiator

func (m MsgID) Initiator() Initiator

func (MsgID) Side

func (m MsgID) Side() Side

func (MsgID) Time

func (m MsgID) Time() time.Time

func (MsgID) UniqueID

func (m MsgID) UniqueID() uint32

type Side

type Side int8

const (
	SideClient Side = iota
	SideServer
)

func (Side) Invert

func (s Side) Invert() Side

Invert returns Side for decryption.

func (Side) String

func (s Side) String() string

func (Side) X

func (s Side) X() int

Initial vector extension for AES key. See more here: https://core.telegram.org/mtproto/description#defining-aes-key-and-initialization-vector

if side is odd (server side) — returns 8

type Unencrypted

type Unencrypted struct {
	ID  MsgID
	Msg []byte
}

func DeserializeUnencrypted

func DeserializeUnencrypted(data []byte) (*Unencrypted, error)

More info: https://core.telegram.org/mtproto/description#unencrypted-message

func (*Unencrypted) Serialize

func (msg *Unencrypted) Serialize() (res []byte)

compatible with MTProto 1.0 and 2.0

More info: https://core.telegram.org/mtproto/description#unencrypted-message