View source for Protocols/MSNP/MSNP8/SBAuthentication

{{Protocols/MSNP/MSNP8 Messaging Nav}}


= Overview =
On MSNP user messaging occurs mainly on an external server known as switchboard.
There are two ways to connect to a switchboard: you can either request a new switchboard session or be invited to an existing one. Both of these events take place on the notification server. When connecting to the switchboard, a client will need to handle the creation of a session {'''XFR''') and being invited ('''RNG''') somewhat differently.

= Requesting a Switchboard Session =
== Notification Server ==
To request a switchboard session, the client must send the '''XFR''' command to the NS with a TrID and a parameter of '''SB''' (for switchboard). The server will reply with another '''XFR''' with instructions on authenticating with the switchboard. Below is an example:

 >>> XFR 15 SB\r\n

 <<< XFR 15 SB 207.46.108.37:1863 CKI 17262740.1050826919.32308\r\n

* The first parameter tells you that you are being transferred to a switchboard (this should always remain the same). Note that in the [[Protocols/MSNP/MSNP8/Authentication#XFR|dispatch server]], this parameter reads '''NS'''.
* The second parameter is the colon-delimited string for the address and port (has always been 1863) of the switchboard server.
* The third parameter specifies the type of authentication, which should always be '''CKI'''.
* The fourth parameter is an authentication string that the client will need to send when connecting to the switchboard to prove its identity.

However, if you have not set your initial status, or you are set to '''HDN''', you may not transfer to a switchboard. Instead of receiving an '''XFR''' in response to your '''XFR''', you will receive [[Protocols/MSNP/Reference/Error_List#913|error 913]].

== Switchboard Server ==
The client must now initiate a TCP connection to the given switchboard IP on the given port (without closing the NS connection).  The client can wait at least two minutes and still connect to the switchboard safely.

Once connected to the switchboard, the client must send the '''USR''' command. It must have a TrID, your account name as the first parameter, and the authentication string as the second parameter. This command must be sent within approximately one minute or else the switchboard will close the connection.

If successful, the server will respond with a '''USR''' with the same TrID, '''OK''' as the first parameter, your account name as the second parameter, and your display name as the third parameter.

*  If of either (or both) the account name or the authentication string were incorrect, the server will send [[Protocols/MSNP/Reference/Error_List#911|error 911]] and close the connection.
* If the format was wrong, the server will immediately close the connection with no error.
* If you try to authenticate with the correct information with the wrong switchboard server (different IP), you will be disconnected with no error.
* If you have already logged into the switchboard server with the authentication information, and try to log in again with the same information, you will receive [[Protocols/MSNP/Reference/Error_List#911|error 911]] and be disconnected. Note that you can still connect to multiple switchboards simultaneously, but you must send multiple '''XFR'''s and use each one separately.

Below is an example of logging in correctly:

 <o> Client Connects to 207.46.108.37 1863 (Switchboard)

 >>> USR 1 example@passport.com 17262740.1050826919.32308\r\n
 <<< USR 1 OK example@passport.com Example%20Name\r\n

 <o> Continue SB Session . . .

Below is an example of logging with the wrong authentication string:

 <o> Client Connects to 207.46.108.37 1863 (Switchboard)

 >>> USR 1 example@passport.com 17262740.1050826919.32307\r\n
 <<< 911 1\r\n

 <o> Switchboard Closes Connection

Now that you are properly authenticated with a switchboard server, you may invite principals as described in the [[Protocols/MSNP/MSNP8/SBMiscellaneous#invite|Participants page]].

= Getting Invited to a Switchboard Session =
== Notification Server ==
When a principal invites you to a switchboard session, you will receive an '''RNG''' command over the notification server. The official client will automatically connect to a switchboard session and won't open a chat window until a plaintext message is sent, but third party clients may choose to behave differently.

The '''RNG''' command has no TrID and five parameters:
*  The first parameter is the session ID of the new switchboard session. Every switchboard session has a unique ID, and each principal invited will use the same session ID. You will need this for authenticating with the switchboard.
* The second parameter is the colon-delimited string for the address and port (has always been 1863) of the switchboard.
* The third parameter specifies the type of authentication, which should always be '''CKI'''.
* The fourth parameter is an authentication string that you will need when authenticating with the switchboard.
* The fifth and sixth parameters are respectively the account name and the URL-encoded display name of the principal that invited you to the switchboard session.

Note: If client version is [[Protocols/MSNP/MSN_Protocol_Version_13|MSNP13]] or later, RNG will have [[Protocols/MSNP/MSNP13/Changes#RNG|two additional parameters]].

Here is an example '''RNG''' command:
 <<< RNG 11752013 207.46.108.38:1863 CKI 849102291.520491113 example@passport.com Example%20Name\r\n

The client does not respond to this command. Instead, it opens a new connection to the IP and port given in the second parameter.

== Switchboard Server ==
As with '''XFR''', you should open a TCP connection to the server within two minutes of receiving the '''RNG''' command. The first thing you must send is the '''ANS''' command. The '''ANS''' command has a TrID and three parameters. The first parameter is your account name, the second parameter is the authentication string, and the third parameter is the switchboard session ID.

If successful, the server will respond with one or more '''IRO'''s followed by an '''ANS'''. However, several things can go wrong.
*  If you connect but do not send '''ANS''', the switchboard will close the connection with no error in about one minute.
* If you don't connect within about one minute of receiving the '''RNG''', the switchboard will close the connection with no error upon receiving the '''ANS'''.
* No matter what, if your session ID is wrong, you will be disconnected with no error.
* If you send a nonexistent or invalid account name and/or an incorrect authentication string, you will receive [[Protocols/MSNP/Reference/Error_List#911|error 911]] and the server will close the connection.
* If the general syntax of the '''ANS''' is wrong, you will be disconnected with no error.
* If you connect to the wrong switchboard address and try to authenticate, you will be disconnected with no error.
* If you (or an attacker) has already connected and authenticated, and you authenticate with the correct information again, you will receive [[Protocols/MSNP/Reference/Error_List#911|error 911]] and the switchboard will close the connection.
* If all of the participants in the switchboard session leave before you connect and send '''ANS''', the switchboard session will be destroyed before you enter, and you will therefore be disconnected with no error after sending '''ANS'''.

The list of participants already in the switchboard session is sent with the '''IRO''' command, which probably stands for "initial roster". A separate '''IRO''' will be sent for each participant. Note that you, having just entered, are not included in this list. '''IRO''' has the same TrID as the '''ANS''' and four parameters.

* The first parameter is the number of the current '''IRO''' command in the list. In the first '''IRO''' command, this will be '''1''', the second will be '''2''', and so on until the total number of commands.
* The second parameter is the total number of '''IRO''' commands that will be sent.
* The third parameter is the participant's account name.
* The fourth parameter is a display name for the participant. If the participant has changed their display name since joining the switchboard session, this parameter will be out-of-date.

Because display names reported by the switchboard server can be out-of-date, you should use the display name given to you by the notification server if possible.

After receiving the last '''IRO''' (where the incrementing number is the same as the total number), you will receive '''ANS''' with the same TrID as the '''ANS''' that you sent initially, with the parameter '''OK'''. After receiving this, you are officially part of the switchboard session and can send and receive messages.

Below is an example of authenticating with the switchboard and finding out that there are two other principals (making a total of three):

 <o> Client Connects to 207.46.108.38 1863 (Switchboard)

 >>> ANS 1 name_123@hotmail.com 849102291.520491113 11752013\r\n
 <<< IRO 1 1 2 example@passport.com Mike\r\n
 <<< IRO 1 2 2 myname@msn.com My%20Name\r\n
 <<< ANS 1 OK\r\n

 <o> Continue SB Session . . .

[[Category:MSN]]
[[Category:Protocols/MSNP]]
[[Category:Work_In_Progress]]