Protocols/MSNP/MSNP12/Logging In

MSNP12 Reference - Starting off

Connecting to the server

To connect to the MSN Messenger network, connect to messenger.hotmail.com on port 1863. If you wish to initiate a SOCKS based connection, then you connect to gateway.messenger.hotmail.com on port 80.

An important message

Once you are connected, you send the server the VER command, which goes like this:

>>> VER Your supported protocols (e.g MSNP12)\r\n

You have to support MSNP12 and CVR0.

The next important message

Now you need to send the CVR command, which has the following parameters in this order:

• The locale id in hexadecimal format Find them out here
• The short operating system name (Windows -> win)
• The OS version (4.10 for windows 98)
• The architecture of the computer (like i386)
• A short name for the cillent thats online
• The client version
• Just MSMSGS (no reason why)
• The passport

Now the server will reply, but you don't need to know this, as you should know all the infomation.

Initial USR

After receiving the response to CVR, you must send the USR command. It has a TrID.

• The first parameter is the authentication system (always TWN).
• The second parameter is always the letter I (standing for initiating authentication).
• The third parameter is the account name that you want to log on with.

If the server does not like your USR, it will close the connection with no reply, or possibly send an error first. Error 911 is sent if you replace the I with an S or when sending invalid account names such as hotmail.com. Error 928 is sent if you send a bad ticket.

Sometimes, when the server is having problems or is down for maintenance, it will reply with an error instead of logging you in. Some possible errors include error 500, error 601, error 910, and error 921.

Otherwise, the server will either respond with a XFR (transferring you to another notification server) or a subsequent USR.

XFR

messenger.hotmail.com always sends XFR, but gateway.messenger.hotmail.com never does. Microsoft's other notification servers very rarely send XFR - presumably, they send it when they are overloaded or going down for maintenance.

The XFR command will have the same TrID as the previous USR and four parameters.

• The first parameter is NS, telling you that it is transferring you to a notification server.
• The second parameter is the IP and port of the notification server, separated by a colon. The port seems to always be 1863, but it's best not to rely on that always being the case.
• The third parameter is always 0 (zero).
• The fourth parameter is the IP address and port (separated by a colon) of the server that you are currently connected to.

Below is an example USR command and XFR reply.

>>> USR 2 TWN I example@passport.com\r\n
<<< XFR 2 NS 207.46.106.145:1863 0 207.46.104.20:1863\r\n

After you receive the XFR, the server will close the connection. You must connect to the specified notification server and start the login process again. There is no communication between notification servers, so you could specify a different protocol version, name and so on when logging into the new notification server.

TWN Authentication

TWN ("Tweener") authentication is the way MSN Messenger plugs into Microsoft's Passport Authentication framework. Passport authentication is Microsoft's attempt to provide a "single sign-on" system for all Internet services, from Messenger to on-line banking. Some background information about it is available on MSDN. Understanding Tweener doesn't require any background knowledge of Passport, but you will need a basic understanding of the HyperText Transfer Protocol version 1.0 or 1.1.

Tweener authentication involves the following steps:

1. The client stores the string sent in the USR response.
2. The client (optionally) connects to the Passport 'Nexus', and retrieves the URL of a login server. This result doesn't change very often, so it can be cached.
3. Using the stored string, passport, and password, the client authenticates itself with this login server. The server will do one of:
   • Redirect the client to another login server for the client to authenticate with (note: this server must not be cached).
   • Report a failure in the login process, with an appropriate error message.
   • Return a 'ticket'. This ticket is sent back to the notification server in the USR reply.

Authentication with MS Passport involves sending HTTPS requests to Microsoft's Passport servers in order to retrieve a passport 'ticket', which is then sent to the server you really want to connect to. HTTPS is HyperText Transfer Protocol encrypted using "Secure Sockets Layer". It is recommended that you find a library for your chosen programming language that supports HTTPS - even if you choose to write your own HTTP parser, you should not try to implement SSL (it's far too complex and security-sensitive to implement as part of a larger project). Some HTTPS libraries are listed on the projects page. Passport servers allow you to either send your login details as an HTML file in the body of the request or as headers of the HTTPS request itself. The "HTML" method is only intended for use by web browsers, but will work fine for MSN Messenger clients. The "header" method is recommended for Messenger clients, and is the only method explained on this site.

Connecting to the Nexus involves sending an HTTPS GET request for the URL "https://nexus.passport.com/rdr/pprdr.asp". The server should always reply with a 200 OK message with an empty body. The important information is contained in the "PassportURLs" header, which contains a comma-separated list. The "DALogin" field of this header contains the address of the login server. This value isn't technically a valid URL, so your HTTPS library might require you to prepend "https://".

The client should then send an HTTPS GET request for the URL given to it by the Nexus. The request should include an "Authorization" header. The value of this header is one long string with no spaces, made up of the string "Passport1.4 OrgVerb=GET,OrgURL=http%3A%2F%2Fmessenger%2Emsn%2Ecom,sign-in="), your URL-encoded passport, ",pwd=", your URL-encoded password, ",", and the challenge string given to you by the Notification Server.

The server's response should be either a 200 OK message (for success), 302 Found (for redirection) or 401 Unauthorized (for failure). The message will contain either an "Authentication-Info" or a "WWW-Authenticate" header. It's not known why two different header names are used, although at present "WWW-Authenticate" is only used with failed logins. It's safest to assume that the two header names are interchangeable. The header's value will begin with " Passport1.4 ", then a comma-separated list of fields of the form "key=value". The first field will have a key "da-status" and a value of "success", "failed" or "redir" (redirect).

If the response is a failure, the header will include a "cbtxt" field with a URL-encoded error message, and a "cburl" field that contains the URL of a picture you might want to display along with it.

If the response is a redirection, there will be a separate "Location" header, which includes the URL of the login server which the client is being redirected to. At the time of writing, the client will only be redirected if it has a passport that ends in "@hotmail.com" or "@msn.com". The client must begin the login step again.

If the response is a success, the header will include a "from-PP" field, which contains the ticket to return to the Notification Server. This field has a slightly unusual format, in that the value is inside apostrophes and includes several equals signs (but no commas).

Final USR command

After getting your ticket, you must send the final USR command. It has a TrID, the first parameter is TWN, the second parameter is S, and the third parameter is your ticket.

If the ticket is correct, the server will respond with a USR with OK as the first parameter, your account name as the second parameter, your URL-encoded display name as the third parameter, 0 or 1 as the fourth parameter, and 0 as the fifth. The fourth parameter represents whether or not your Passport has been verified (1 is true, 0 is false). We don't yet know what the fifth parameter means.

If your your ticket is incorrect, the server will respond with error 911 and close the connection. If anything else is wrong (including an invalid digest size), the server will close the connection with no error.

Sometimes, when the server is having problems or is down for maintenance, it will reply with an error instead of logging you in. Some possible errors include error 500, error 601, error 910, and error 921.