« back to all changes in this revision
Viewing changes to doc/ymsg-9.txt
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Kartik Mistry
- Date: 2007-04-23 11:47:36 UTC
- Revision ID: james.westby@ubuntu.com-20070423114736-ksgy8h9gvkbt07uh
Tags: upstream-0.7.5+dfsg
Import upstream version 0.7.5+dfsg
- files added:
- doc
- src
added
removed
doc/ymsg-9.txt
1
Yahoo Messenger Protocol v 9
2
----------------------------
3
4
The Yahoo Messenger Protocol is an application layer protocol running most
5
of the time over TCP, but in some cases over HTTP as well. Throughout
6
this document, we will speak about the YMSG packets, after stripping out
7
any other protocol data, but will mention this other data if it is of
8
relevance.
9
10
This document is incomplete. For anything not mentioned here, refer to the
11
source of libyahoo2.
12
13
14
1. The YMSG packet structure
15
16
The YMSG packet structure is as follows:
17
18
(each byte is represented by 5 spaces in the following diagram,
19
including the | at the end)
20
21
<------- 4B -------><------- 4B -------><---2B--->
22
+-------------------+-------------------+---------+
23
| Y M S G | version | pkt_len |
24
+---------+---------+---------+---------+---------+
25
| service | status | session_id |
26
+---------+-------------------+-------------------+
27
| |
28
: D A T A :
29
| 0 - 65535* |
30
+-------------------------------------------------+
31
32
33
* 65535 is the theoretical limit, since the length field is two bytes
34
long. Practically though, the data section does not exceed about 1000
35
bytes.
36
37
All numeric fields are stored in network byte order. i.e. Most
38
significant byte first.
39
40
YMSG - The first four bytes of all packets are always YMSG - the
41
protocol name.
42
43
version - The next four bytes are for the protocol version number.
44
For version 9, these are 0x09 0x00 0x00 0x00
45
NOTE: The last three bytes of this may just be padding bytes.
46
47
pkt_len - A two byte value, in network byte order, stating how many bytes
48
are in the _data_ section of the packet. In practice, this
49
value does not exceed about 1000.
50
51
service - This is an opcode that tells the client/server what kind of
52
service is requested/being responded to. There are 45 known
53
services. See the services section of this document for a
54
full listing.
55
56
status - In case of a response from the server, indicates the status
57
of the request (success/failure/etc.). For a request, it is 0
58
in most cases, except for packets that set the user's status
59
(set status, typing notify, etc.)
60
61
session - The session id is used primarily when connecting through a HTTP
62
id proxy. It is set in all cases, but has no effect in a direct
63
connection. When the client sends the first packet, it is 0,
64
the server responds with a session id that is used by the client
65
and the server in all further packets. The server may change
66
the session id, in which case the client must use the new
67
session id henceforth.
68
69
DATA - The data section is pkt_len bytes long and consists of a series
70
of key/value pairs. All keys are numeric strings. The packet
71
contains their numeric values in the ASCII character set. e.g.
72
1 == 0x31, 21 == 0x32 0x31
73
74
The maximum number of digits in a key is unknown, although keys
75
of up to three digits have been seen.
76
77
Every key and value is terminated by a two byte sequence of
78
0xc0 0x80. Some keys may have empty values.
79
80
The actual keys sent, and their meanings depend on the service
81
in use.
82
83
e.g. The packet data to send an instant message looks like this:
84
85
0x30 0xc080 yahoo_id 0xc080 0x31 0xc080 active_id 0xc080 0x35
86
0xc080 recipient_id 0xc080 0x3134 0xc080 message_text 0xc080
87
88
The 0xc080 byte sequence is a separator. The values 0x30, 0x31,
89
0x35 and 0x3134 are the keys. Convert them to their ASCII
90
equivalents and you get 0, 1, 5, 14 (0x3134 == 0x31 0x34)
91
92
93
2. Services
94
95
There are 45 known services at the moment, although more may exist. All
96
known services are listed below along with the hex values that they
97
correspond to. Any service without a hex value is one more than the
98
previous value. i.e. YAHOO_SERVICE_LOGOFF=0x02 and
99
YAHOO_SERVICE_ISBACK=0x04.
100
101
YAHOO_SERVICE_LOGON = 0x01
102
YAHOO_SERVICE_LOGOFF
103
YAHOO_SERVICE_ISAWAY
104
YAHOO_SERVICE_ISBACK
105
YAHOO_SERVICE_IDLE = 0x05
106
YAHOO_SERVICE_MESSAGE
107
YAHOO_SERVICE_IDACT
108
YAHOO_SERVICE_IDDEACT
109
YAHOO_SERVICE_MAILSTAT
110
YAHOO_SERVICE_USERSTAT = 0x0a
111
YAHOO_SERVICE_NEWMAIL
112
YAHOO_SERVICE_CHATINVITE
113
YAHOO_SERVICE_CALENDAR
114
YAHOO_SERVICE_NEWPERSONALMAIL
115
YAHOO_SERVICE_NEWCONTACT = 0x0f
116
YAHOO_SERVICE_ADDIDENT = 0x10
117
YAHOO_SERVICE_ADDIGNORE
118
YAHOO_SERVICE_PING
119
YAHOO_SERVICE_GROUPRENAME
120
YAHOO_SERVICE_SYSMESSAGE = 0x14
121
YAHOO_SERVICE_PASSTHROUGH2 = 0x16
122
YAHOO_SERVICE_CONFINVITE = 0x18
123
YAHOO_SERVICE_CONFLOGON
124
YAHOO_SERVICE_CONFDECLINE = 0x1a
125
YAHOO_SERVICE_CONFLOGOFF
126
YAHOO_SERVICE_CONFADDINVITE
127
YAHOO_SERVICE_CONFMSG
128
YAHOO_SERVICE_CHATLOGON
129
YAHOO_SERVICE_CHATLOGOFF = 0x1f
130
YAHOO_SERVICE_CHATMSG = 0x20
131
YAHOO_SERVICE_GAMELOGON = 0x28
132
YAHOO_SERVICE_GAMELOGOFF
133
YAHOO_SERVICE_GAMEMSG = 0x2a
134
YAHOO_SERVICE_FILETRANSFER = 0x46
135
YAHOO_SERVICE_VOICECHAT = 0x4a
136
YAHOO_SERVICE_NOTIFY = 0x4b
137
YAHOO_SERVICE_P2PFILEXFER = 0x4d
138
YAHOO_SERVICE_PEERTOPEER = 0x4f
139
YAHOO_SERVICE_AUTHRESP = 0x54
140
YAHOO_SERVICE_LIST = 0x55
141
YAHOO_SERVICE_AUTH = 0x57
142
YAHOO_SERVICE_ADDBUDDY = 0x83
143
YAHOO_SERVICE_REMBUDDY = 0x84
144
YAHOO_SERVICE_IGNORECONTACT = 0x85
145
YAHOO_SERVICE_REJECTCONTACT = 0x86
146
147
Most of the service codes should be self explanatory. Those that aren't
148
are listed here:
149
150
IDACT/IDDEACT - activate/deactivate an identity
151
NOTIFY - typing/game notification
152
FILETRASNFER - transfer a file using the yahoo filetransfer server as an
153
intermediate
154
P2PFILEXFER - transfer a file between two peers, yahoo server not used
155
PEERTOPEER - check if peer to peer connections are possible
156
AUTH - Send initial login packet (username), response contains
157
challenge string
158
AUTHRESP - Send response to challenge string, or, if received from
159
server, contains reason for login failure
160
LOGON/LOGOFF - a buddy logged in/out
161
162
163
3. Status codes
164
165
The status code is a four byte value. Most status codes are two bytes
166
long. The status codes (in decimal except for offline and typing) are:
167
168
YAHOO_STATUS_AVAILABLE = 0
169
YAHOO_STATUS_BRB
170
YAHOO_STATUS_BUSY
171
YAHOO_STATUS_NOTATHOME
172
YAHOO_STATUS_NOTATDESK
173
YAHOO_STATUS_NOTINOFFICE = 5
174
YAHOO_STATUS_ONPHONE
175
YAHOO_STATUS_ONVACATION
176
YAHOO_STATUS_OUTTOLUNCH
177
YAHOO_STATUS_STEPPEDOUT = 9
178
YAHOO_STATUS_INVISIBLE = 12
179
YAHOO_STATUS_CUSTOM = 99
180
YAHOO_STATUS_IDLE = 999
181
YAHOO_STATUS_OFFLINE = 0x5a55aa56
182
YAHOO_STATUS_TYPING = 0x16
183
184
You may choose either AVAILABLE or INVISIBLE as your initial login status.
185
TYPING is used only when sending a TYPING notification packet.
186
187
188
4. Session states
189
190
A Yahoo session has two states, Authentication and Messaging.
191
192
4.1. Authentication
193
194
The session starts in the authentication state. The client sends the username
195
to the server. The server responds with a challenge string. The client
196
responds to this challenge with two response strings. If authentication is
197
successful, the connection goes into the messaging state, else, an error
198
response is sent back.
199
200
4.2. Messaging state
201
202
After successful authentication, the session goes into the messaging state.
203
The server sends the buddy list, ignore list, identity list and a list of
204
cookies to the client. These might all be sent in a single packet. It then
205
sends the list of online buddies along with their status codes. All this is
206
sent without the client requesting anything.
207
208
At this time, any offline messages are also delivered to the client.
209
210
In the messaging state, a client may send/receive messages, join conferences,
211
send/receive files, change state, etc.
212
213
Messaging state is terminated when the user goes offline by sending a LOGOFF
214
packet.
215
216
217
5. Requests
218
219
5.1. Authentication
220
221
The first packet sent from the client is the authentication request
222
packet. This consists of the user's yahoo id, or any identity
223
corresponding to that yahoo id. The AUTH packet has one key/value pair.
224
225
service: YAHOO_SERVICE_AUTH
226
status: YAHOO_STATUS_AVAILABLE
227
228
1: yahoo_id
229
230
The server responds with a Challenge string. The client then hashes the
231
username and password with this challenge string, and sends it back as an
232
AUTH_RESP packet.
233
234
service: YAHOO_SERVICE_AUTHRESP
235
status: initial login status
236
237
0: yahoo_id
238
6: response_string_1
239
96: response_string_2
240
1: active_id
241
242
243
5.2. Sending a message
244
245
service: YAHOO_SERVICE_MESSAGE
246
status: 0
247
248
0: yahoo_id
249
1: active_id
250
5: recipient_id
251
14: message to send
252
253
5.3. Send typing start/stop notification
254
255
service: YAHOO_SERVICE_NOTIFY
256
status: YAHOO_STATUS_TYPING
257
258
4: active_id
259
5: recipient_id
260
13: 1 or 0 depending on whether this is a typing start or stop
261
packet
262
14: <space>
263
49: TYPING /* The literal string */
264
265
5.4. Set status
266
267
service: YAHOO_SERVICE_ISBACK or YAHOO_SERVICE_ISAWAY
268
status: the status to set to
269
270
10: status_code
271
if custom_status:
272
19: custom away message
273
47: 0 or 1 depending on whether it is away or not
274
275
276
5.5. Logoff
277
278
service: YAHOO_SERVICE_LOGOFF
279
status: YAHOO_STATUS_AVAILABLE
280
281
no key value pairs
282
283
5.6. Keep alive - sent every 20 minutes
284
285
service: YAHOO_SERVICE_PING
286
status: YAHOO_STATUS_AVAILABLE
287
288
no key value pairs
289
290
5.7. Add buddy
291
292
service: YAHOO_SERVICE_ADDBUDDY
293
status: YAHOO_STATUS_AVAILABLE
294
295
1: yahoo_id
296
7: buddy_to_add
297
65: group to add to
298
299
5.8. Remove buddy
300
301
service: YAHOO_SERVICE_REMBUDDY
302
status: YAHOO_STATUS_AVAILABLE
303
304
1: yahoo_id
305
7: buddy_to_remove
306
65: group to remove from
307
308
309
5.9. Reject buddy add
310
311
service: YAHOO_SERVICE_REJECTCONTACT
312
status: YAHOO_STATUS_AVAILABLE
313
314
1: yahoo_id
315
7: buddy_to_reject
316
14: reject message
317
318
319
-----------------------------------------------------------------------
320
321
What? Is that all?
322
323
Use the source Luke!
324
325
-----------------------------------------------------------------------
326
Loggerhead is a web-based interface for Breezy
Version: 2.0.1