idnits 2.17.1 draft-movva-msn-messenger-protocol-00.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-18) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document is more than 15 pages and seems to lack a Table of Contents. == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 1177 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- Couldn't find a document date in the document -- date freshness check skipped. Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 6 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Instant Messaging and Presence Protocol R. Movva 2 Internet Draft Microsoft 3 Category: Informational August, 1999 4 Document: draft-movva-msn-messenger-protocol-00.txt 5 Document Expires: 2/00 W. Lai 6 Microsoft 7 August, 1999 9 MSN Messenger Service 1.0 Protocol 11 Status of this Memo 13 This document is an Internet-Draft and is NOT offered in accordance 14 with Section 10 of RFC2026, and the author does not provide the IETF 15 with any rights other than to publish as an Internet-Draft. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. Internet-Drafts are draft documents valid for a maximum of 21 six months and may be updated, replaced, or obsoleted by other 22 documents at any time. It is inappropriate to use Internet-Drafts as 23 reference material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 This document and related documents are discussed on the impp 32 mailing list. To join the list, send mail to impp- 33 request@iastate.edu. To contribute to the discussion, send mail to 34 impp@iastate.edu. The archives are at http://lists.fsck.com/cgi- 35 bin/wilma/pip. The IMPP working group charter, including the current 36 list of group documents, can be found at 37 http://www.ietf.org/html.charters/impp-charter.html. 39 1. Abstract 41 Microsoft released a commercial Instant Messaging product in July of 42 1999 called MSN Messenger Service. This document describes the 43 protocol used by that product for core instant messaging and 44 presence functionality. While this protocol does not meet many of 45 the requirements of the IMPP working group, it is provided as 46 background information on existing Instant Messaging 47 implementations. This protocol is provided 'as is' without warranty 48 of any kind. 50 Movva and Lai Category - Informational 1 52 MSN Messenger Service 1.0 Protocol Aug - 99 54 2. Conventions used in this document 56 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 57 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in 58 this document are to be interpreted as described in RFC-2119. 60 Protocol messages sent from client to server are preceded by "C:". 62 Protocol messages sent from server to client are preceded by "S:". 64 3. Introduction 66 MSN Messenger Service enables a user to learn about the presence of 67 other people on the Internet, and to communicate with them in real- 68 time. This functionality is commonly referred to as "Instant 69 Messaging" (IM). 71 This document describes the syntax and semantics of the MSN 72 Messenger Protocol, the communication protocol running between MSN 73 Messenger Service 1.0 clients and servers. Among the core services 74 that the MSN Messenger Servers provide to clients are: 76 - Authenticated user logon. 77 - Adding and deleting members of the user's contact list. 78 - Changing the user's on-line state. 79 - Receipt of asynchronous, real-time, on-line state change 80 notifications from members of the user's contact list. 81 - Delivering lightweight, real-time messages to other users. 82 - Receipt of asynchronous, real-time messages from other users. 83 - Configuring the user's access permissions, to restrict the ability 84 of other users to view the user's on-line state or send messages 85 to the user. 87 Additional background: 89 1. Some features extraneous to core instant messaging functionality 90 contained within the MSN Messenger Service 1.0 protocol are beyond 91 the scope of this document. Examples include client version 92 management and directory functionality. 94 2. The purpose of this document is to provide the members of the 95 IMPP working group with a reference implementation of a "monolithic" 96 IM system. That is, a system designed for massive scale, but not yet 97 capable of communication with servers other than those associated 98 with this specific service. Since any standard in this area will of 99 necessity be a "distributed" design that explicitly enables server- 100 to-server and service-to-service communication, this document will 101 serve primarily as a reference and example of one implementer's 102 choices when providing IM functionality at scale. 104 Movva and Lai Category - Informational 2 106 MSN Messenger Service 1.0 Protocol Aug - 99 108 3. This document reflects the protocol used in the 1.0 release of 109 MSN Messenger clients and servers, deployed on the Internet in July 110 of 1999. However, the service is in production and rapidly growing, 111 which almost certainly will necessitate changes to the protocol as 112 Microsoft gains operational experience with the service and expands 113 its feature set. This Internet Draft may not be updated with such 114 changes, and the changes may be made with little or no notice. 116 4. MSN Messenger Server Component Overview 118 MSN Messenger Service clients make connections to several different 119 kinds of servers. They are separate components to facilitate running 120 at scale - each component can be duplicated an arbitrary number of 121 times, independently of each other, to enable large numbers of 122 users. 124 4.1 Dispatch Server (DS) 126 The Dispatch Server is the initial point of connection between 127 client and server. Its primary functions are protocol version 128 negotiation, determination of which Notification Server (NS) is 129 associated with the client making a connection (via an algorithm of 130 the server's choosing), and referring the client to the proper NS. 132 4.2 Notification Server (NS) 134 The Notification Server is the primary server component. The client 135 and the Notification Server authenticate, synchronize user 136 properties, and exchange asynchronous event notifications. The 137 client's connection to the Notification Server occurs after the 138 referral from the Dispatch Server is completed, and persists without 139 interruption during the user's MSN Messenger Service session. 141 Some of the events transmitted between a client and a Notification 142 Server are: State changes (e.g. client is on-line, client is 143 offline, client is idle), Switchboard Server invitation requests 144 (see below), and application-specific notifications that are beyond 145 the scope of this document. (E.g. new e-mail has arrived) 147 4.3 Switchboard Server (SS) 149 The Switchboard Server is the component through which clients can 150 establish lightweight communication sessions without requiring a 151 direct network connection between clients. The common usage of the 152 Switchboard Server is to provide instant messaging sessions. 153 When a client wishes to communicate with another client, it sends a 154 message to its Notification Server, which then refers the client to 155 a Switchboard Server. Once the SS connection is established, the 156 "destination" client receives a notification from its NS to connect 157 to the same SS. 159 Movva and Lai Category - Informational 3 161 MSN Messenger Service 1.0 Protocol Aug - 99 163 5. Protocol Conventions 165 5.1 Connection Type 167 The MSN Messenger Protocol currently works over TCP/IP. The MSN 168 Messenger server components support connections over port numbers 169 1863, which is the registered port number assigned by the IANA 170 (http://www.isi.edu/in-notes/iana/assignments/port-numbers). 172 5.2 Command Syntax 174 MSN Messenger Protocol command syntax is ASCII and single line- 175 based. Commands begin with a case-sensitive, three-letter command 176 type, followed by zero or more parameters, and terminated by CRLF. 177 Parameters are separated by one or more whitespace characters and 178 cannot contain whitespace characters. Parameters that contain spaces 179 or extended (non 7-bit ASCII) characters should be encoded using 180 URL-style encoding (e.g. "%20" for space). Some commands accept un- 181 encoded binary data. In these cases, the length of the data is 182 transmitted as part of the command, and the data is transmitted 183 immediately following a CRLF of the command. 185 5.3 Asynchronous Requests 187 Commands issued from the client to the server that result in a reply 188 are known as requests. Requests are entirely asynchronous. The 189 client can submit several requests in sequence without waiting for 190 the server response after submitting each request. The server is 191 required to deliver a response or an error for each request 192 received, but it is not required to deliver the responses in the 193 same order as the requests were received. The client can determine 194 the request associated with a particular response by examining the 195 Transaction ID parameter (described below). 197 5.4 User Handles 199 MSN Messenger Protocol uses User Handles for identifying users. A 200 user handle (also known as "account name" and "logon name") is a 201 text representation of the user's identity that is both unique and 202 persistent. The user handle is syntactically equivalent to an e-mail 203 address, and as such is subject to the same restrictions for 204 character set, as described in RFC-822. Most notable among these 205 restrictions are the limitation to Latin alphanumeric characters and 206 a few symbols. The maximum acceptable length of the user handle is 207 129 bytes. 209 Implementation note: In the initial release of the client and 210 server, user handles are Hotmail account names. All user handles 211 must contain the "@hotmail.com" domain name, and user handles that 212 do not contain a domain name are not valid. 214 5.5 Custom User Names 216 Movva and Lai Category - Informational 4 218 MSN Messenger Service 1.0 Protocol Aug - 99 220 A custom user name (also known as "custom name" and "friendly name") 221 is a user's representation of the "friendly" textual name associated 222 with a user handle. (E.g. "Auntie Em" instead of em123@hotmail.com). 223 Custom user names are neither unique nor persistent, and can contain 224 any valid Unicode characters. Custom user names are represented in 225 UTF-8 as described in RFC-2044 and URL-encoded as described in RFC- 226 1738 when transmitted between the client and server. The maximum 227 acceptable length of the encoded custom user name is 387 in the 228 current implementation. 230 5.6 Transaction Identifiers 232 The Transaction Identifier (a.k.a. Transaction ID) is a numeric 233 string representing a number between 0 and (2^32 - 1). It is a value 234 that a client includes with any command that it issues to the 235 server. In the current version of the protocol, the transaction 236 identifier is used to associate server responses with client-issued 237 commands. The server treats the transaction ID as an opaque number 238 and does not assume any relationship between successive Transaction 240 IDs or any particular starting Transaction ID. It is the client's 241 responsibility to guarantee the uniqueness of the Transaction IDs 242 for the purpose of disambiguating the commands and/or responses. (A 243 future version of the protocol could enable the client to track the 244 status or cancel a particular transaction using the transaction ID.) 246 When the server sends the response to a command to the client, it 247 must include in the response the transaction ID that the client sent 248 to the server when the client originally issued the command. In 249 cases where a server sends a command to a client that requires a 250 transaction ID but is not in response to a specific client command, 251 it will use 0 as the transaction ID. In cases where a server sends 252 multiple responses to a single client request, the server will use 253 the same transaction ID in each response. 255 5.7 User List Types 257 Some of the protocol commands are used to the manipulate lists of 258 users. The following types of user lists are supported by the 259 protocol: 261 Forward List (FL) - The list of users for whom a given user wants to 262 receive state change notifications. The Forward List is what is most 263 commonly referred to as the user's "contact list." 265 Reverse List (RL) - The list of users who have registered an 266 interest in seeing this user's state change notifications. 268 Allow List (AL) - The list of users who the user has explicitly 269 allowed to see state change notifications and establish client-to- 270 client sessions via a Switchboard Server. 272 Movva and Lai Category - Informational 5 274 MSN Messenger Service 1.0 Protocol Aug - 99 276 Block List (BL) - The list of users who the user has explicitly 277 prevented from seeing state change notifications and establishing 278 client-to-client sessions via a Switchboard Server. 280 6. Command Summary Table 282 Command From To Description 283 ================================================================== 284 ACK Switchboard Client Sends a positive message 285 delivery acknowledgement. 286 ------------------------------------------------------------------- 287 ADD Client Notification Adds to the user's FL, AL, 288 Notification Client and BL. Notifies the client 289 of asynchronous additions 290 to a user's list. 291 ------------------------------------------------------------------- 292 ANS Client Switchboard Accepts a request for a 293 switchboard server session. 294 ------------------------------------------------------------------- 295 BLP Client Notification Changes the user's message 296 Notification Client privacy setting, which 297 determines how to treat 298 messages from users not 299 already in the BL or AL. 300 ------------------------------------------------------------------- 301 BYE Switchboard Client Notifies a client that a 302 user is no longer in the 303 session. 304 ------------------------------------------------------------------- 305 CAL Client Switchboard Initiates a switchboard 306 server session. 307 ------------------------------------------------------------------- 308 CHG Client Notification Sends a client state change 309 Notification Client to the server. 310 Echoes the success of 311 client's state change 312 request. 313 ------------------------------------------------------------------- 314 FLN Notification Client Notifies the client when 315 users in the FL go off- 316 line. 317 ------------------------------------------------------------------- 318 GTC Client Notification Changes the user's prompt 319 Notification Client setting, which determines 320 how the client reacts to 321 certain RL changes. 322 ------------------------------------------------------------------- 323 INF Client Dispatch, Requests set of support 324 Notification authentication protocol 325 Dispatch, Client from the server. 326 Notification Provides the set of 328 Movva and Lai Category - Informational 6 330 MSN Messenger Service 1.0 Protocol Aug - 99 332 supported authentication 333 protocols to the client. 334 ------------------------------------------------------------------- 335 ILN Notification Client Notifies the client of the 336 initial online state of a 337 user in the FL, while 338 either logging on or adding 339 a user to the FL. 340 ------------------------------------------------------------------- 341 IRO Switchboard Client Provides the initial roster 342 information for new users 343 joining the session. 344 ------------------------------------------------------------------- 345 JOI Switchboard Client Notifies a client that a 346 user is now in the session. 347 ------------------------------------------------------------------- 348 LST Client Notification Retrieves the server's 349 Notification Client version of the user's FL, 350 RL, AL, or BL. 351 ------------------------------------------------------------------- 352 MSG Client Switchboard Sends a message to the 353 members of the current 354 session. 355 ------------------------------------------------------------------- 356 MSG Notification, Client Delivers a message from 357 Switchboard another client or from a 358 server-side component. 359 ------------------------------------------------------------------- 360 NAK Switchboard Client Sends a negative message 361 delivery acknowledgement. 362 ------------------------------------------------------------------- 363 NLN Notification Client Notifies the client when 364 users in the FL go on-line 365 or when their on-line state 366 changes. 367 ------------------------------------------------------------------- 368 OUT All All Ends a client-server 369 Session. 370 ------------------------------------------------------------------- 371 REM Client Notification Removes from the user's FL, 372 Notification Client AL, and BL. 373 Notifies the client of 374 asynchronous removals from 375 a user's list. 376 ------------------------------------------------------------------- 377 RNG Notification Client Notifies the client of a 378 request by another client 379 to establish a session via 380 a switchboard server. 381 ------------------------------------------------------------------- 382 SYN Client Notification Initiates client-server 383 Notification Client property synchronization. 384 ------------------------------------------------------------------- 386 Movva and Lai Category - Informational 7 388 MSN Messenger Service 1.0 Protocol Aug - 99 390 USR All All Authenticates client with 391 server, possibly in 392 multiple passes. 393 ------------------------------------------------------------------ 394 VER Client Dispatch Negotiates common protocol 395 Dispatch Client dialect between client and 396 Server. 397 ------------------------------------------------------------------ 398 XFR Client Notification Requests a Switchboard 399 Notification Client server for use in 400 establishing a session. 401 ------------------------------------------------------------------- 402 XFR Dispatch Client Notification of login-NS to 403 Notification Client the client or notification 404 to move to a different NS. 405 ======================================================================= 407 7. Presence and State Protocol Details 409 This is a detailed list of protocol commands associated with 410 presence functionality. They are defined in the order used by 411 clients. Commands associated with instant messages are discussed in 412 section 8 below. 414 7.1 Protocol Versioning 416 After the client connects to a dispatch server by opening a TCP 417 socket to port 1863, the client and server agree on a particular 418 protocol version before they proceed. The Client-Server protocol 419 version handshake involves the following command exchange: 421 C: VER TrID dialect-name{ dialect-name...} 422 S: VER TrID dialect-name 424 The client can provide multiple dialect names in preferred order. 425 The dialect-name parameter returned by the server is the version 426 server is designating for this connection 428 The current protocol dialect-name supported by Messenger servers is 429 "MSNP2". The dialect names are not case-sensitive. 431 The string "0" is a reserved dialect name and is used to indicate a 432 failure response. E.g.: 434 S: VER TrID 0{ dialect-name ... } 436 7.2 Server Policy Information 438 The client next queries the server for variable "policy" 439 information. In this version of the protocol, the only policy 441 Movva and Lai Category - Informational 8 443 MSN Messenger Service 1.0 Protocol Aug - 99 445 information returned by the server is the authentication package in 446 use. 448 C: INF TrID 449 S: INF TrID SP{,SP...} 451 SP identifies a security package - the name of the SASL mechanism to 452 use for authentication. "MD5" is used by the Notification Server, 453 "CKI" by the Switchboard Server. 455 7.3 Authentication 457 The client needs to authenticate itself after protocol version 458 handshake and identifying the security packages supported on the 459 server. The following are the client server interactions involved. 461 C: USR TrID SP I{ AuthInitiateInfo} 462 S: USR TrID SP S{ AuthChallengeInfo} 463 C: USR TrID SP S{ AuthResponseInfo } 464 S: USR TrID OK UserHandle FriendlyName 466 The SP parameter is the name of the security package("MD5"). The 467 next parameter is a sequence value, which must be I to (I)nitiate 468 the authentication process and S for all (S)ubsequent messages. If 469 authentication fails on the server, the client can start the 470 authentication process again. 472 For the MD5 security package: 473 - The AuthInitiateInfo parameter provided by the client must be the 474 User handle. 475 - The AuthChallengeInfo parameter returned by the server contains a 476 challenge string. 477 - The AuthResponseInfo contains the binary response as a hexadecimal 478 string, which the MD5 hash of the challenge and the User password 479 strings concatenated together. 481 The final response from the server contains, in addition to the user 482 handle, the current "Friendly Name" associated with the user handle. 483 This is a "Custom User Name" as described above. 485 7.4 Referral 487 There are three cases in which clients are referred from one server 488 to another: 490 1. The initial "Dispatch Server" refers the client to the 491 Notification Server to which it is assigned. 492 2. Asynchronous referral by the Notification Server to reassign the 493 client to a different Notification Server if that server is 494 overloaded or undergoing maintenance. 495 3. During Switchboard Session establishment, the assigned 496 Notification Server refers the client to a particular 497 switchboard server for use. This is discussed below. 499 Movva and Lai Category - Informational 9 501 MSN Messenger Service 1.0 Protocol Aug - 99 503 In the current implementation the Dispatch Server uses the user 504 handle provided in the initial USR command above to assign the user 505 in question to a Notification Server. Alternate implementations 506 might not require referral at this stage. 508 If received, referral is of the form: 510 S: XFR TrID ReferralType Address[:PortNo] 512 ReferralType is either "NS" or "SB" and defines the type of referral 513 to a Notification Server or Switchboard Server. 514 Address is a valid DNS name or IP address to a referred server, with 515 optional port# suffixed as ":PortNo". 517 If this command is received from the server, the client should 518 attempt to log in to the server provided. 520 In the case of "NS" referrals during logon, the Server automatically 521 closes the client connection after sending this XFR response so that 522 the client can connect to the new IP Address. 524 If sent asynchronously, the client is responsible for closing the 525 connection. 527 After a "NS" referral, the client will not receive any more messages 528 from the "old" NS, and also must not send any commands to the "old" 529 NS after receiving an XFR. 531 7.5 Client User Property Synchronization 533 Several of the user properties used by the Messenger application are 534 stored on the server. This is done for two reasons: 536 1) So that users can "roam", i.e. log in from different locations 537 and still have the appropriate data, such as their contact lists and 538 privacy settings. 539 2) If changes occur to a user's Reverse List while that user was 540 offline (the user was added to another user's list), the client can 541 be updated with this information. 543 For performance reasons it is useful to cache these properties on 544 the client, so that bandwidth usage is minimized in the typical case 545 where the user is not roaming and there were no Reverse List 546 changes. 548 These requirements are met by the SYN command - synchronization. 550 Once a client logs in successfully, it uses the SYN command to 551 ensure it has the latest version of the server-stored properties. 552 These properties include: Forward List, Reverse List, Block List, 553 Allow List, GTC setting (privacy setting when someone adds this user 554 to their Forward List), and BLP setting (the user's privacy mode). 556 Movva and Lai Category - Informational 10 558 MSN Messenger Service 1.0 Protocol Aug - 99 560 The SYN command is: 562 C: SYN TrID Ser# 563 S: SYN TrID Ser# 565 The Ser# parameter sent by the client is the version of the 566 properties currently cached on the client. The server responds with 567 the current server version of the properties. If the server has a 568 newer version, the server will immediately follow the SYN reply by 569 updating the client with the latest version of the user properties. 570 These updates are done as described below, and are done without the 571 client explicitly initiating a LST, GTC or BLP command. Note that 572 the server will update all server-stored properties to the client, 573 regardless of how many entries have been changed. 575 The following "List Retrieval and Property Management" section 576 describes the format of the user properties sent by the server. 577 After the SYN reply from the server, the user property updates will 578 be sent from the server in this sequence: GTC, BLP, LST FL, LST AL, 579 LST BL, LST RL. 581 All the user property updates will share the same TrID as the SYN 582 command and reply. 584 7.6 List Retrieval And Property Management 586 Synchronizing can result in a batch of user properties and lists 587 getting sent by the server to the client. However, the client 588 application can also initiate a request to retrieve the server- 589 stored lists and properties. The following are the privacy property 590 and list retrieval commands. The response formats are the same 591 whether it is a client-initiated request, or whether it is a 592 response to the SYN process as described above. 594 List Command 596 By issuing the LST command, the client can explicitly request that a 597 list be sent. The server will respond with a series of LST 598 responses, one LST response for each item in the requested list. 600 C: LST TrID LIST 601 S: LST TrID LIST Ser# Item# TtlItems UserHandle CustomUserName 603 - LIST is FL/RL/AL/BL for Forward List, Reverse List, Allow List, 604 and Block List, respectively. 605 - The Item# parameter contains the index of the item described in 606 this command message. (E.g. item 1 of N, 2 of N, etc.) 607 - The TtlItems parameter contains the total number of items in this 608 list. 609 - UserHandle is the user handle for this list item. 610 - CustomUserName is the friendly name for this list item. 612 Movva and Lai Category - Informational 11 614 MSN Messenger Service 1.0 Protocol Aug - 99 616 If the list is empty, the response will be: 618 S: LST TrID LIST Ser# 0 0 620 Reverse List Prompting 622 The client can change its persistent setting for when to prompt the 623 user in reaction to an Reverse List change. This is accomplished via 624 the GTC command: 626 C: GTC TrID [A | N] 627 S: GTC TrID Ser# [A | N] 629 The value of the A/N parameter determines how the client should 630 behave when it discovers that a user is in its RL, but is not in its 631 AL or BL. (Note that this occurs when a user has been added to 632 another user's list, but has not been explicitly allowed or 633 blocked): 635 A - Prompt the user as to whether the new user in the RL should be 636 added to the AL or the BL 637 N - Automatically add the new user in the RL to the AL 639 The A/N parameter is not interpreted by the server, merely stored. 641 The server will respond with the current setting if the change was 642 successful. Otherwise, it will return an error with the matching 643 TrID. If the client tries to change the setting to the same value as 644 the current setting, the server will respond with an error message. 646 The default setting is A when a new user connects to the server for 647 the first time. 649 Privacy Mode 651 The client can change how the server handles instant messages from 652 users via the BLP command: 654 C: BLP TrID [AL | BL] 655 S: BLP TrID Ser# [AL | BL] 657 The AL/BL parameter determines how the server should treat messages 658 (MSG and RNG) from users. If the current setting is AL, messages 659 from users who are not in BL will be delivered. If the current 660 setting is BL, only messages from people who are in the AL will be 661 delivered. 663 The server will respond with the current setting if the change was 664 successful. Otherwise, it will return an error with the matching 665 TrID. If the client tries to change the setting to the same value as 666 the current setting, the server will respond with an error message. 668 Movva and Lai Category - Informational 12 670 MSN Messenger Service 1.0 Protocol Aug - 99 672 The default setting is AL when a new user connects to the server for 673 the first time. 675 7.7 Client States 677 After the client is authenticated and synchronized, the client 678 establishes its initial state with the server with the CHG command. 679 The syntax of the command is: 681 C: CHG TrID State 682 S: CHG TrID State 684 When the state is changed, the server will echo the settings back to 685 client. The state shall not be considered changed until the response 686 is received from the server. 688 Note that the server can send a state change message to the client 689 at any time. If the server changes the state without a request from 690 the client, the TrID parameter will be 0. 692 States are denoted by a string of three characters. The predefined 693 states that the server recognizes are: 695 NLN - Make the client Online (after logging in) and send and receive 696 notifications about buddies. 697 FLN - Make the client Offline. If the client is already online, 698 offline notifications will be sent to users on the RL. No message 699 activity is allowed. In this state, the client can only synchronize 700 the lists as described above. 701 HDN - Make the client Hidden/Invisible. If the client is already 702 online, offline notifications will be sent to users on the RL. The 703 client will appear as Offline to others but can receive 704 online/offline notifications from other users, and can also 705 synchronize the lists. Clients cannot receive any instant messages 706 in this state. 708 All other States are treated as sub-states of NLN (online). The 709 other States currently supported are: 710 BSY - Busy. 711 IDL - Idle. 712 BRB - Be Right Back. 713 AWY - Away From Computer. 714 PHN - On The Phone. 715 LUN - Out To Lunch. 717 7.8 List Modifications 719 The protocol supports generic commands to add and remove users from 720 various lists. This is used by clients to enable "Adding" contacts 721 to the list of folks being watched, or for the "Block" and "Allow" 722 features that define how users chooses to interact with one another. 724 Movva and Lai Category - Informational 13 726 MSN Messenger Service 1.0 Protocol Aug - 99 728 However, these generic commands have different semantics based on 729 the list being modified. For example, only the server can add or 730 remove entries from the Reverse List - since it is an indirect 731 consequence of the user having been added to another user's Forward 732 List. 734 The add and remove commands: 736 C: ADD TrID LIST UserHandle CustomUserName 737 S: ADD TrID LIST ser# UserHandle CustomUserName 739 C: REM TrID LIST UserHandle 740 S: REM TrID LIST ser# UserHandle 742 Valid values for LIST in Client initiated adds and removes are 743 FL/AL/BL. 745 All client initiated adds and removes will be echoed by the server 746 with a new serial number that should be persisted by the client 747 along with the list modification. If not successful, an error will 748 result. 750 The protocol also supports the concept of an ADD or REM that the 751 client did not initiate. Server generated ADDs and REMs can have 752 LIST values of FL/AL/BL/RL. This is common with RL changes, which 753 are never initiated by the client, but is an indirect consequence of 754 this user having been added to someone's Forward List. If the RL 755 change happens while the user is online, it will trigger an 756 asynchronous ADD or REM command from the server. 758 Asynchronous ADDs and REMs to the FL, AL, and BL can happen when the 759 server allows an authenticated user to make list changes from 760 another environment, such as a web site. In all of these cases, the 761 server will send the ADD or REM command with the TrID parameter 762 equal to 0. 764 7.9 Notification Messages 766 The client receives asynchronous notifications whenever a contact on 767 the user's Forward List changes its state. The notifications are of 768 the form: 770 S: NLN Substate UserHandle FriendlyName 771 S: ILN TrID Substate UserHandle FriendlyName 772 S: FLN UserHandle 774 NLN indicates that a user has come online. 775 - Substate can be any three-letter code (see "Client States" above). 776 - UserHandle and FriendlyName are the handle and names associated 777 with the user coming online. 779 ILN is similar to the NLN message, and is received from the server 780 in response to an CHG or ADD command from the client: 782 Movva and Lai Category - Informational 14 784 MSN Messenger Service 1.0 Protocol Aug - 99 786 1. Immediately after the client logon and sends its first CHG 787 command to the NS. In this case several ILNs may be received - 788 one for each Forward List contact that is currently online. 789 2. After the client sends an "ADD TrID FL UserHandle 790 CustomUserName" to the NS. (e.g. ILN for the new contact if that 791 contact is currently online) 793 In both cases, TrID in the ILN is the same as the one sent by the 794 client in the CHG or ADD command. 796 FLN means that the specified user is now offline. 798 7.10 Connection Close 800 The client issues the following command to logoff from the NS: 802 C: OUT 803 S: OUT {StatusCode} 805 The server will reply with an OUT to the client before it initiates 806 a disconnect, with an optional StatusCode. 808 The StatusCode can be "OTH", which indicates that a client with the 809 same user handle and password has logged on to the server from 810 another location, or "SSD" meaning the server is being shut down for 811 maintenance. 813 The server will drop the connection after sending the OUT. 815 7.11 Error Information 817 Error messages from the server are of the format: 819 S: eee {TrID} {(error-info) {param...}} 821 eee is a 3 digit decimal number indicating the error code. Error- 822 info contains the description of the error in a text string 823 localized to the server's locale. The optional parameters provide 824 indication of the client command causing the error. TrID is the 825 Transaction ID of the client command that caused this error. Any 826 server generated errors will not have Transaction IDs. 828 ERR_SYNTAX_ERROR 200 829 ERR_INVALID_PARAMETER 201 830 ERR_INVALID_USER 205 831 ERR_FQDN_MISSING 206 832 ERR_ALREADY_LOGIN 207 833 ERR_INVALID_USERNAME 208 834 ERR_INVALID_FRIENDLY_NAME 209 835 ERR_LIST_FULL 210 836 ERR_ALREADY_THERE 215 838 Movva and Lai Category - Informational 15 840 MSN Messenger Service 1.0 Protocol Aug - 99 842 ERR_NOT_ON_LIST 216 843 ERR_ALREADY_IN_THE_MODE 218 844 ERR_ALREADY_IN_OPPOSITE_LIST 219 845 ERR_SWITCHBOARD_FAILED 280 846 ERR_NOTIFY_XFR_FAILED 281 848 ERR_REQUIRED_FIELDS_MISSING 300 849 ERR_NOT_LOGGED_IN 302 850 ERR_INTERNAL_SERVER 500 851 ERR_DB_SERVER 501 852 ERR_FILE_OPERATION 510 853 ERR_MEMORY_ALLOC 520 854 ERR_SERVER_BUSY 600 855 ERR_SERVER_UNAVAILABLE 601 856 ERR_PEER_NS_DOWN 602 857 ERR_DB_CONNECT 603 858 ERR_SERVER_GOING_DOWN 604 859 ERR_CREATE_CONNECTION 707 860 ERR_BLOCKING_WRITE 711 861 ERR_SESSION_OVERLOAD 712 862 ERR_USER_TOO_ACTIVE 713 863 ERR_TOO_MANY_SESSIONS 714 864 ERR_NOT_EXPECTED 715 865 ERR_BAD_FRIEND_FILE 717 866 ERR_AUTHENTICATION_FAILED 911 867 ERR_NOT_ALLOWED_WHEN_OFFLINE 913 868 ERR_NOT_ACCEPTING_NEW_USERS 920 870 8. Session based Instant Messaging Protocol Details 872 MSN Messenger Service utilizes a lightweight, session-based 873 messaging scheme. In order for two clients to exchange instant 874 messages, they must first establish a common session via a 875 Switchboard Server. They can invite additional clients to join the 876 established session. 878 8.1 Referral to Switchboard 880 This process begins with a "calling" client requesting a referral 881 from its Notification Server to a Switchboard Server: 883 C: XFR TrID SB 884 S: XFR TrID SB Address SP AuthChallengeInfo 886 - SB is the type of referral being requested or granted. 887 - Address is the DNS name or IP address of a Switchboard Server that 888 has been assigned, and that the client should connect to. 889 - SP is the Security Package being used. In this version of the 890 protocol it is "CKI" only. 891 - AuthChallengeInfo is a cookie that the client needs to present to 892 the Switchboard server for authentication. 894 Movva and Lai Category - Informational 16 896 MSN Messenger Service 1.0 Protocol Aug - 99 898 8.2 Switchboard Connections and Authentication 900 After the XFR reply is received, the client makes a TCP/IP 901 connection to the Switchboard server using port 1863. Note that a 902 lack of version negotiation in the switchboard connection is a 903 limitation of the current implementation. 905 The client first needs to authenticates with the Switchboard Server: 907 C: USR TrID UserHandle AuthResponseInfo 908 S: USR TrID OK UserHandle FriendlyName 910 - AuthResponseInfo is the cookie for CKI security package returned 911 by the Notification Server in the XFR. 912 - UserHandle and FriendlyName are the Switchboard's echoes of the 913 user handle and friendly name of the user. 915 8.3 Inviting Users to a Switchboard Session 917 Any user in a Switchboard session can invite other users to join the 918 session. The CAL command is sent to the Switchboard server for this 919 purpose: 921 C: CAL TrID UserHandle 922 S: CAL TrID Status SessionID 924 The Messenger servers verify that the calling user has permissions 925 to contact the called user, with consideration given to the called 926 user's privacy settings and its online state. If instant messaging 927 with this user is not allowed, the server responds to the calling 928 user with an error. If it is allowed, the Switchboard server causes 929 a RNG command to be sent to the called client (see below), and 930 returns a CAL echo to the calling client. The CAL echo has these 931 parameters: 933 - Status is a predefined status code - in this implementation it 934 must be "RINGING". 935 - SessionID is the ASCII representation of a decimal number that 936 uniquely identifies this session on the Switchboard Server. 938 8.4 Getting Invited to a Switchboard Session 940 The other side of the session establishment is the behavior of the 941 called client. The called client receives a RNG from its 942 Notification Server and is expected to connect to the Switchboard 943 Server and respond with an ANS. 945 The client receives a RNG from the Notification Server as follows: 947 S: RNG SessionID SwitchboardServerAddress SP AuthChallengeInfo 948 CallingUserHandle CallingUserFriendlyName 950 - SessionID is a numeric ASCII session ID. 952 Movva and Lai Category - Informational 17 954 MSN Messenger Service 1.0 Protocol Aug - 99 956 - SwitchboardServerAddress is a DNS name or IP Address 957 - SP is the security package in use. In this implementation only 958 "CKI" is supported. 959 - AuthChallengeInfo is the cookie to be passed back to the 960 switchboard to gain entrance to the session. 961 - CallingUserHandle is the user handle of the caller. 962 - CallingUserFriendlyName is the custom user name of the caller. 964 To join the session, the called client connects to the Switchboard 965 Server and carries out the following exchange to join the session: 967 C: ANS TrID LocalUserHandle AuthResponseInfo SessionID 968 S: IRO TrID Participant# TotalParticipants UserHandle 969 FriendlyName 970 S: ANS TrID OK 972 The IRO commands relay to the newly joined client roster information 973 about the current session. Each IRO command message from the 974 Switchboard contains one participant in the session. 975 - Participant# contains the index of the participant described in 976 this IRO command (e.g. 1 of N, 2 of N). 977 - TotalParticipants contains the total number of participants 978 currently in the session. 980 The entire session roster will be sent to the new client joining the 981 session before any JOI or BYE commands described below. 983 If no one is in the session when the user joins (an unexpected error 984 condition), the server skips directly to "ANS TrID OK" command. All 985 the responses from the server related to the issued ANS command will 986 contain the same TrID as the original client ANS request. 988 8.5 Session Participant Changes 990 When a new user joins a Switchboard session, the server sends the 991 following command to all participating clients, including the client 992 joining the session: 994 S: JOI CalleeUserHandle CalleeUserFriendlyName 996 - CalleeUserHandle is the user handle of the new participant. 997 - CalleeUserFriendlyName is the Custom User Name of the new 998 participant. 1000 If a client's connection with the Switchboard Server is dropped for 1001 any reason, the server sends the following command to the remaining 1002 clients in the session: 1004 S: BYE CalleeUserHandle 1006 - CalleeUserHandle is the user handle of the participant that left 1007 the session. 1009 Movva and Lai Category - Informational 18 1011 MSN Messenger Service 1.0 Protocol Aug - 99 1013 Privacy Note: 1014 If the client moved a contact to the BL while Switchboard sessions 1015 are active, it is the client's responsibility to leave any session 1016 that should now be blocked. The servers only enforce privacy 1017 permissions when inviting users to a session. Further, the servers 1018 only enforce privacy permission with respect to the calling user, 1019 and not the other participants in a Switchboard session. Therefore, 1020 in a multipoint session, it is possible for a user to participate in 1021 a session with someone whom he has blocked, if a third party is 1022 performing the invitation. 1024 8.6 Leaving a Switchboard Session 1026 When a client wishes to disconnect from the session, it sends the 1027 following command and waits for the Switchboard to close the 1028 connection: 1030 C: OUT 1032 8.7 Instant Messages 1034 Sending an Instant Message 1036 Once a client-to-client session has been established via the 1037 Switchboard Server, sending an Instant Message to the participants 1038 of the session is done as follows: 1040 C: MSG TrID [U | N | A] Length\r\nMessage 1041 S: NAK TrID 1042 S: ACK TrID 1044 U, N, and A correspond to the three delivery acknowledgement modes: 1045 Unacknowledged, Negative-Acknowledgement-Only, and Acknowledgement. 1046 Depending on the value of this parameter, either nothing, NAK, or 1047 ACK will be sent back by the Switchboard Server to the client. 1049 For Unacknowledged mode, the Switchboard Server does not respond to 1050 the sending client with the success or failure of message delivery. 1052 For Negative-Acknowledgement-Only mode, the Switchboard Server 1053 responds to the send client only if the message could not be 1054 delivered to the recipient client. 1056 Acknowledgement mode is not currently implemented. 1058 Length is the length of the Message parameter in bytes, whereas 1059 Message is the actual message as described below. 1061 8.8 Receiving an Instant Message 1063 A client can receive a system-generated message from the 1064 Notification Server, or it can receive an instant message from 1066 Movva and Lai Category - Informational 19 1068 MSN Messenger Service 1.0 Protocol Aug - 99 1070 another client via a Switchboard Server. The message is received in 1071 the following format: 1073 S: MSG UserHandle FriendlyName Length\r\nMessage 1075 The UserHandle and FriendlyName are those of the sending user. 1076 Length is the length of the message in bytes. 1078 Message is a MIME encoded stream, using a standard MIME header as 1079 defined by RFC-1521 and RFC-822. 1081 Message is constructed as: 1083 MIME-Header\r\nMIME-Header\r\n\r\nMessageData 1085 MIME-Header is constructed as: 1087 string": "string 1088 (E.g. "Content-Type: text/plain") 1090 The Content-Type MIME headers that the current client will use and 1091 recognize are: 1093 "text/plain;charset=UTF-8" 1094 "text/plain" 1096 If "charset=UTF-8" appears at the end of the Content-Type, the 1097 Message Data is UTF-8 encoded. 1099 Note: The Switchboard Server does not interpret the contents of the 1100 Message. 1102 9. Author's Addresses 1104 Ramu Movva 1105 Microsoft Corporation 1106 One Microsoft Way 1107 Redmond WA 98052 1108 ramum@microsoft.com 1110 William Lai 1111 Microsoft Corporation 1112 One Microsoft Way 1113 Redmond, WA 98052 1114 wlai@microsoft.com 1116 Movva and Lai Category - Informational 20