- 1 Introduction
- 2 Features
- 3 Network
- 4 Packet Structure
- 5 Login Process
- 6 Client Versions
- 7 Useful Links
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.
The Yahoo protocol has the following features:
- File transfer
- Instant messaging
- Offline messaging
- Voice chat
- Webcam support
- Cross-network interoperability with the Windows Live Messenger (MSN) network. This is explained below.
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
Add information about the packet structure here.
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:
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.
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=<username>&passwd=<password>&chal=<challengestring>" to the server login.yahoo.com (or login.yahoo.co.jp for Yahoo JAPAN accounts). The whole URL is https://login.yahoo.com/config/pwtoken_get?src=ymsgr&login=<username>&passwd=<password>&chal=<challengestring> (or https://login.yahoo.co.jp/config/pwtoken_get?src=ymsgr&login=<username>&passwd=<password>&chal=<challengestring> for Yahoo JAPAN).
Substitute the Yahoo ID for <username>, but strip @yahoo.com from any ID sent (other domains, such as sbcglobal.net or rocketmail.com, seem to be OK). Substitute the password for <password> and the challenge string from the previous step for <challengestring>. Note that the challenge string is not strictly required to proceed. If you choose not to use the challenge string for this request, you can wait to perform steps 1 and 2 until you've completed step 4 and are ready to start step 5.
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:
|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=<token>" to the same login server used in the last step. The whole url is https://login.yahoo.com/config/pwtoken_login?src=ymsgr&token=<token> (or https://login.yahoo.co.jp/config/pwtoken_login?src=ymsgr&token=<token> for Yahoo JAPAN). Substitute <token> with the token from the previous step.
Again, the server's response contains necessary information.
The HTTP headers contain a B Cookie in the format "Set-Cookie: B=<cookie>". This is not strictly needed to log in, but some clients (including the official client) use it. If you choose to use it, ignore the characters "B=", but take the remainder of the text up to (but not including) the first semicolon.
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:
|307||"response" calculated in previous step|
|244||Client build ID. More on this below.|
|135||Client version. More on this below.|
- 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.
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||Build ID||Network||Supported|