Yahoo
Introduction
The Yahoo! Messenger Protocol is the protocol created by the Yahoo! corporation for use in its instant messaging clients. The protocol is proprietary and centralized in nature with some functionality being peer-to-peer in the newest revisions of the protocol and clients. In general, the protocol is called YMSG. Note that all YMSG packets will contain "YMSG" near the beginning of their payload.
Yahoo JAPAN also runs a second network using the same protocol. The protocol used is identical, however the servers are different and it is not possible for a user on the Yahoo JAPAN network to chat with a user on the "normal" Yahoo network (or vice versa). The Yahoo JAPAN network also appears not to be able to use all the features the other network can, for example Windows Live Messenger (MSN) interoperability.
Features
The Yahoo protocol has the following features:
- Avatars
- Conferencing
- File transfer
- Instant messaging
- Offline messaging
- Voice chat
- Webcam support
- SMS
Cross-network interoperability with the Windows Live Messenger (MSN) network. This is explained below.
Network
The Yahoo protocol connects to its servers over the following ports:
- Chat port (Pager server): 5050 (TCP)
- File transfer port: 80 (TCP)
- Peer-to-peer chat: 5101 (TCP)
- Rooms list: 80 (TCP)
- Voice chat: 5000-5010 (UDP) or 5000-5001 (TCP)
- Webcam: 5100 (TCP)
- Yahoo Phone: 5055
- Pager server request: 80 (TCP: HTTP)
- Login server: 443 (TCP: HTTPS)
Known servers are:
- Login server: login.yahoo.com
- Pager server request server: vcs1.msg.yahoo.com
- Pager server request server for Yahoo JAPAN: cs1.msg.vip.ogk.yahoo.co.jp
- Pager server hostname pool: scsa.msg.yahoo.com
- File transfer server: filetransfer.msg.yahoo.com
- File transfer server Japan: filetransfer.msg.yahoo.co.jp
Packet Structure
Add information about the packet structure here.
Login Process
Starting with Yahoo Messenger 9.0, clients use YMSG protocol version 16. The login procedure for protocol version 16 employs an HTTP request, a YMSG packet, two HTTPS requests, then a return to YMSG. The login process consists of multiple steps as follows:
1. Request a pager server address
Send an HTTP GET request for location "/capacity" to the server vcs1.msg.yahoo.com (or cs1.msg.vip.ogk.yahoo.co.jp for Yahoo JAPAN). The whole URL is http://vcs1.msg.yahoo.com/capacity (or http://cs1.msg.vip.ogk.yahoo.co.jp/capacity for Yahoo JAPAN).
The server responds with a message containing two lines:
COLO_CAPACITY=1
CS_IP_ADDRESS=aaa.bbb.ccc.ddd
The address aaa.bbb.ccc.ddd will be a real IP address usable for standard YMSG connections. It is currently in correct IPv4 format; that is, no leading zeroes are used. This is the Pager server the client should connect to.
The COLO_CAPACITY line's purpose is currently unknown, but it is believed
that if the server returns COLO_CAPACITY=0 that official clients will not
attempt to connect to a pager server.
2. Send YMSG packet to Pager server
Send a packet for service 57 (authentication) to the pager server. This packet must contain a single key-value pair. The key is 1 and the value is the Yahoo ID you are trying to connect with.
The server will reply with a packet for service 57 that contains 3 key-value pairs:
- Key 1, Value Yahoo ID connecting
- Key 13, Value 2. This key indicates the particular authentication mechanism to use. Past values are 0 and 1, but these are no longer supported.
- Key 94, Value is a string. This string is the challenge string used during the first HTTPS request.
3. Send username, password, and challenge string to login server
Send an HTTPS GET request for location
"/config/pwtoken_get?src=ymsgr&login=
Substitute the Yahoo ID for
The server will respond, but the response will vary depending on whether information supplied is correct or not.
The first line of the response's body will be an ASCII representation of an integer. This response code's values and meanings are:
| Code | Definition |
|---|---|
| 0 | Information supplied is correct. |
| 100 | Missing required field (username or password) |
| 1013 | Username contains @yahoo.com or similar but should not; strip this information. |
| 1212 | The username or password is incorrect. |
| 1213 | The account is locked because of too many failed login attempts |
| 1214 | Security lock requiring the use of a CAPTCHA. |
| 1218 | The account has been deactivated by Yahoo |
| 1235 | The username does not exist. |
| 1236 | The account is locked due to too many login attempts (this error code means only the number of attempted logins, including both failed and successful login attempts). |
If the response was 0, there will be additional lines in the response:
- The second line of the response will start with "ymsgr=". This value is the token.
- The third line of the response will start with "partnerid=". The purpose of this value is unknown, but seems to be somehow tied to a given username and password pair.
4. Send token to login server
Send an HTTPS GET request for location
"/config/pwtoken_login?src=ymsgr&token=
Again, the server's response contains necessary information.
The HTTP headers contain a B Cookie in the format "Set-Cookie: B=
The first line of the response's body will again be an ASCII representation of an integer. 0 means the information supplied to the server was correct, and 100 means there's a problem. If the first line is 0, additional lines will be present:
- Line 2 will start with "crumb=". This is the crumb needed to calculate a hash later.
- Line 3 will start with "Y=". This is the Y cookie and is needed later.
- Line 4 will start with "T=". This is the T cookie and is needed later.
- Line 5 will start with "cookievalidfor=". This is the life of the cookies in seconds. Usually this value is 86400 (1 day).
5. Calculate a hash to send to the Pager server
You now need to send a string to the Pager server. This string is calculated using the crumb and challenge string, hashed with MD5, and encoded with Yahoo's variant of Base64.
- Concatenate the crumb and the challenge string. This is "crypt"
- perform and MD5 hash of crypt. This is "hash"
- Encode hash with Yahoo's Base64 variant. Some clients, like libpurple,
implement their own y64 encoding function, but you can do this instead:
- Base64-encode hash. This is "response"
- Replace all instances of
+in response with. - Replace all instances of
/in response with_ - Replace all instances of
=in response with-
6. Send the response to the Pager server
Send a YMSG packet for service Authentication Response (0x54) with the following key-value pairs:
| Key | Value |
|---|---|
| 1 | Yahoo ID |
| 0 | Yahoo ID |
| 277 | Y cookie |
| 278 | T cookie |
| 307 | "response" calculated in previous step |
| 244 | Client build ID. More on this below. |
| 2 | Yahoo ID |
| 2 | 1 |
| 59 | B cookie |
| 98 | Chat locale |
| 135 | Client version. More on this below. |
Notes:
- All three places using the Yahoo ID must use the same ID string that was used to obtain the token and crumb. If a domain had to be stripped to obtain the token and crumb, that stripped version of the username must be used here as well.
- The B cookie isn't strictly needed for login, but will make clients less distinguishable from the official client.
- The key 244 and final key 2 values are numbers, but are treated as ASCII characters instead of as integers.
- The meaning of key 98's value is an assumption. The US official client puts "us" in this value; the JAPAN official client puts "jp". This value is not strictly needed for login, but will make clients less distinguishable from the official client.
Client Versions
The official clients have two different version numbers. One is the version number a user sees in the "About Yahoo! Messenger" box. The other is completely hidden from the user and used only during the login process. We'll call these versions the version and build ID, respectively. Each version has precisely one build ID associated with it. Known pairs are listed:
Client version and build ID pairs
| Client Version | Build ID | Network | Supported |
|---|---|---|---|
| 9.0.0.2162 | 4194239 | Normal | Yes |
| 9.0.0.1727 | 4186047 | Japan | Yes |