File post in case of OCS (one to one)
Lets assume 2 ppl X and Y having a private IM conversation, when X sends a file to Y, internally X’s client sends a SIP message like this:
The content type is “text/msmsgsinvite”, however the identification of file post is the Application-Name: File Transfer. The content also includes the file name and the invitation cookie and the size of the file and that it requires encryption.
User Y accepts the request by sending the following message:
Then user X sends a 200 ok message and then x directly connects to Y’s mentioned IP:Port and then the file transfer happens using the MSN_Secure_FTP protocol, which is described below:
The documentation for this protocol is not available. We need to explore this further.
The MSN_Secure_FTP protocol seems to be derived from the MSNFTP protocol which has similar features.
File transfer negotiation was first seen in version 3 of the official client, and has been upgraded in version 5 to better handle computers which have problems receiving incoming TCP connections (such as those behind NAT firewalls). The file transfer protocol itself is documented here.
Overview
Alice wants to send a file to Bob, so she sends an invitation to him. This invitation must give a filename and size. If Alice is unable to receive incoming connections, the invitation should mention the lack of connectivity.
Bob replies with a message either accepting or cancelling the file. If he declines, his reply must give a reason (e.g. file rejected). If he accepts, and Alice's invitation stated that she cannot receive incoming connections, heshould offer to act as the server in the file transfer. Otherwise, he should simply accept her invitation.
If Bob offered to act as the server, the negotiation is complete. Otherwise, Alice must send a reply accepting Bob's message and offer to act as the server.
The negotiation is now complete. If the file transfer fails, a time-out message may follow.
The message in which the offer to act as the server is made must give an IP address and port, and may give a local IP address and port. If Bob is acting as the server, he must specify that Alice (the sender) is to connect to Bob (the receiver).
Sending Invitation Messages
Each invitation message is sent through a switchboard session as a MSG with MIME-Version: 1.0 and a content-type of text/x-msmsgsinvite; charset=UTF-8. The body of an invitation message is a set of fields. As usual, fields may be sent in any order, and any unrecognised fields must be ignored. The complete set of fields is given below. Fields marked "required" must be sent. Fields marked "optional" may be sent, but the receiver should be prepared to cope with messages that don't include them. In file transfer, the client may ignore all optional fields - versions of the official client below 5.0 always ignore optional fields, versions 5.0 and above never do. The exception to this is that if you send a "Connectivity" field, you must handle the "Sender-Connect" field if it is sent in the reply.
The official client will only negotiate in switchboard sessions with exactly two people in them, so if inviter and invitee don't share such a session, the client sending the invitation must first create one. It is not necessary to reply to an invitation in the same session which it was sent. For example, if Alice and Bob are in a switchboard, Alice sends an invitation to Bob, then Carol enters the switchboard, Bob must send his reply in a different switchboard session.
Protocol
Each message contains one "invitation command". The sequence in which commands must be sent is:
1. The inviter sends an INVITE command
2. the invitee ACCEPTs the invitation
3. If the invitee did not offer to serve, the inviter ACCEPTs
4. Either client may then send a CANCEL command with a cancel code of FTTIMEOUT, if there is a problem during transfer. For example, the official client will listen for an incoming connection for 30 seconds, then cancel the offer.
Either party can send a CANCEL command at any time after the first message is sent. No further messages should be sent after this.
Common Fields
All messages in a negotiation include the following fields:
Invitation-Command (required)
The type of message being sent. See the protocol section, above for valid invitation commands.
Invitation-Cookie (required)
A random integer between 1 and 2^32 - 1, uniquely identifying a negotiation (note that a cookie of 0 is invalid). This value is decided by the sender of the INVITE, and must remain constant throughout a negotiation
INVITE Fields
INVITE commands include the following fields:
Application-Name (required)
A natural-language description of the class. This can vary - for example, the official client calls the file transfer class File Transfer in English, Filoverføring in Norwegian, and ファイル送信 in Japanese. This should only be used to describe a class to the user - for example, if the Application-GUID isn't recognised
Application-GUID (required)
The unique identifier of the class. A class always has the same GUID, and no two classes ever have the same GUID. Strictly speaking, that makes it a CLSID (a GUID used to identify a class). The GUID for file transfer is "{5D3E02AB-6190-11d3-BBBB-00C04F795683}", and for some reason, the official client checks this case-sensitively.
Application-File (required)
The name of the file to be sent
Application-FileSize (required)
The size in bytes of the file to be sent. If this size differs from the size given during the file transfer session, that value takes priority
Connectivity (optional)
If the client knows it cannot receive incoming connections, it should send this with a value of 'N'. The official client decides this based on the initial profile, but you could just as well ask the user if you prefer.
CANCEL Fields
Only one field is required by CANCEL commands - Cancel-Code. This is a short reason for cancellation. You should treat this as a free-form string, but the general-purpose codes which have been encountered in the official client are:
FAIL
The receiving client does not know any of the specified Session-protocols
FTTIMEOUT
There was an error transferring the file itself
OUTBANDCANCEL
The switchboard window in which the INVITE message was sent is closing
REJECT
The principal has declined the invitation
REJECT_NOT_INSTALLED
The client does not support that application GUID
TIMEOUT
The client sending an INVITE has got bored of waiting for your ACCEPT (or the principal has cancelled the request)
ACCEPT Fields
The following field exists in all ACCEPT commands:
Launch-Application (required)
Instructs the other client (not) to launch an external application. Since file transfer is handled internally by the official client, this is normally "FALSE". I don't know under what condition you would set this to "TRUE"
The ACCEPT command with the offer to serve includes these fields:
IP-Address (required)
The primary IP address for the client to connect to. The official client gets the address of your network's Internet gateway from the initial profile.
IP-Address-Internal (optional)
The secondary IP address for the client to connect to (if the primary address failed). Recent versions of the official client put the address of your network card here.
Port (required)
The primary TCP port your server is listening on. This should be 6891. Some versions of the official client will misbehave if you use a different address. This field is the counterpart to "IP-Address".
PortX (optional)
The secondary TCP port your server is listening on. This should be 11178. Some versions of the official client will misbehave if you use a different address. This field is the counterpart to "IP-Address-Internal", so include this field if and only if you include that one.
PortX-Internal (optional)
If included, this field must be equal to "PortX". This is probably a work-around for older versions of the official client
AuthCookie (required)
A random integer between 1 and 2^32 - 1, used in the file transfer session to uniquely identify the file being sent (in case two files are being sent at once)
Sender-Connect (optional)
Normally, the computer receiving the file initiates a connection to the sender. If the sender should connect to the receiver (e.g. if the sender is behind a firewall), this is sent with a value of "TRUE"
Example Invitations
Here is an example of a successful file transfer invitation between two clients which support the upgraded invitation method.
>>> MSG 12 N 294
MIME-Version: 1.0
Content-Type: text/x-msmsgsinvite; charset=UTF-8
Application-Name: File Transfer
Application-GUID: {5D3E02AB-6190-11d3-BBBB-00C04F795683}
Invitation-Command: INVITE
Invitation-Cookie: 85366
Application-File: Autoexec.bat
Application-FileSize: 187
Connectivity: N
<<<>
MIME-Version: 1.0
Content-Type: text/x-msmsgsinvite; charset=UTF-8
IP-Address: 81.99.77.64
IP-Address-Internal: 10.5.1.3
Port: 6891
PortX: 11178
AuthCookie: 544120
Sender-Connect: TRUE
Invitation-Command: ACCEPT
Invitation-Cookie: 227948
Launch-Application: FALSE
Request-Data: IP-Address:
Here is an example of a successful file transfer invitation between two clients which do not support the upgraded invitation method. However, there was a problem in the transfer itself.
>>> MSG 4 N 277
MIME-Version: 1.0
Content-Type: text/x-msmsgsinvite; charset=UTF-8
Application-Name: File Transfer
Application-GUID: {5D3E02AB-6190-11d3-BBBB-00C04F795683}
Invitation-Command: INVITE
Invitation-Cookie: 33267
Application-File: readme.txt
Application-FileSize: 60904
<<<>
MIME-Version: 1.0
Content-Type: text/x-msmsgsinvite; charset=UTF-8
Invitation-Command: ACCEPT
Invitation-Cookie: 33267
Launch-Application: FALSE
Request-Data: IP-Address:
>>> MSG 4 N 238
MIME-Version: 1.0
Content-Type: text/x-msmsgsinvite; charset=UTF-8
Invitation-Command: ACCEPT
Invitation-Cookie: 33267
IP-Address: 10.44.102.65
Port: 6891
AuthCookie: 93301
Launch-Application: FALSE
Request-Data: IP-Address:
>>> MSG 4 N 151
MIME-Version: 1.0
Content-Type: text/x-msmsgsinvite; charset=UTF-8
Invitation-Command: CANCEL
Invitation-Cookie: 85366
Cancel-Code: FTTIMEOUT
This section discusses the general invitation mechanism used by everything except file transfer. The official client allows 3rd party programs to register themselves as invitation types (for example, the game "MechWarrior Mercenaries" does this). If you are writing an application and want the official client to support your invitation type, check out MSDN's Messenger API documentation.
Overview
Alice wants to negotiate a session with Bob, so she sends an invitation to him. This invitation must describe the invitation type (e.g. voice conversation) and may include application-specific information Bob will need to know (e.g. the voice conversation protocols supported by Alice's computer).
Bob replies with a message either accepting or cancelling the invitation. If he accepts, his reply must contain his IP address, must request Alice's IP address, and may include information which Alice will require (e.g. his chosen voice conversation protocol). If he declines, his reply must give a reason (e.g. voice transfer not supported).
Alice accepts Bob's reply, and sends a message to that effect. Her reply must contain her IP address.
Depending on the invitation-type, Bob may send a final message with some contextual information.
The negotiation is now complete.
Sending Invitation Messages
Each invitation message is sent through a switchboard session as a MSG with MIME-Version: 1.0 and a content-type of text/x-msmsgsinvite; charset=UTF-8. The body of an invitation message is a set of fields. As usual, fields may be sent in any order, and any unrecognised fields must be ignored. The complete set of fields is given below. Fields marked "required" must be sent. Fields marked "optional" may be sent, but the receiver should be prepared to cope with messages that don't include them. Unlike in file transfer, the client must handle optional fields if they are sent.
The official client will only negotiate in switchboard sessions with exactly two people in them, so if inviter and invitee don't share a private session, the client sending the invitation must first create one. It is not necessary to reply to an invitation in the same session which it was sent. For example, if Alice and Bob are in a switchboard, Alice sends an invitation to Bob, then Carol enters the switchboard, Bob must send his reply in a different switchboard session.
If you wish to invite two people to the same session, you should send two separate invitations.
Protocol
Each message contains one "invitation command". The sequence in which commands must be sent is:
1. The inviter sends an INVITE command
2. the invitee ACCEPTs the invitation
3. The inviter opens a socket to listen for a connection, then ACCEPTs.
4. The inviter then sends some Context. (only in some invitation-types)
Either party can send a CANCEL command at any time after the first message is sent. No further messages can be sent after this.
Common Fields
All messages in an invitation include the following fields:
Invitation-Command
The type of message being sent. See the protocol section, above for valid invitation commands.
Invitation-Cookie
An integer between 1 and 2^32 - 1, uniquely identifying a negotiation (note that a 0 is an invalid cookie). This value is decided by the sender of the INVITE, and must remain constant throughout a negotiation. The official client selects cookies at random.
Session-ID
A unique identifier for the current MSN Messenger client. This identifies a particular instance of a particular client - each client should generate a new session ID every time it starts, and use the same ID until the program is finished. If the client logs out, then back in again, it should continue using the same session ID.
INVITE Fields
The INVITE command includes the following fields:
Application-Name
A natural-language description of the class. This can vary - for example, the official client calls the file transfer class File Transfer in English, Filoverføring in Norwegian, and ファイル送信 in Japanese. This should be used to describe a class to the user - for example, if the Application-GUID isn't recognised.
Application-GUID
The unique identifier of the class. Despite the name, this can be any identifier, as discussed above. A class always has the same Application-GUID, and no two classes ever have the same GUID. Strictly speaking, that make it a CLSID (a GUID used to identify a class). Unlike with file transfers, this GUID is checked case-insensitively.
Application-URL (optional)
A URL with information about downloading the specified application. An application always has the same Application-URL. If the Application-GUID isn't recognised, the client may suggest the user visit the URL. Note: do not automatically load the URL, as an attacker could easily use this force you to load a page which exploits a bug in your web browser.
Session-Protocol
Session protocol(s) supported by sending the client. The official client only supports SM1.
Context-Data (optional)
A string used for an application-specific purpose (e.g. negotiating details of the protocol to use)
CANCEL Fields
Only one extra field is required by CANCEL commands - Cancel-Code. This is a short reason for cancellation. You should treat this as a free-form string, but the values supported by the official client are:
FAIL
The receiving client cannot parse an invitation message you sent it (e.g. because it doesn't recognise any of the specified session protocols).
OUTBANDCANCEL
The switchboard window in which the INVITE message was sent is closing.
REJECT
The principal has declined the invitation
REJECT_NOT_INSTALLED
The client does not support that application GUID.
TIMEOUT
The client has got bored of waiting for your reply (or the principal has cancelled the invitation).
First ACCEPT Fields
The first ACCEPT command includes these fields:
Session-Protocol
Selected session protocol (taken from the list given in the INVITE message). If there are no acceptable protocols, the invitation is cancelled with a cancel-code of FAIL.
Context-Data (optional)
A string used for an application-specific purpose (e.g. negotiating details of the protocol to use)
Launch-Application
Instructs the other client (not) to launch an external application. Normally "TRUE". I don't know under what condition you would set this to "FALSE".
Request-Data
The value of this field must be "IP-Address:". Requests that the other client send its IP address.
IP-Address
The IP address (and optionally port number) of the computer which will act as client.
Second ACCEPT Fields
The second ACCEPT command includes these fields:
Launch-Application
Instructs the other client (not) to launch an external application. Normally "TRUE". I don't know under what condition you would set this to "FALSE".
IP-Address
The IP address (and optionally port number) of the computer which will act as server.
Context Fields
The Context command includes these fields:
Context-Data
A string used for an application-specific purpose (e.g. negotiating details of the protocol to use)
Example Invitations
Here is an example of a successful voice conversation invitation, from the point-of-view of the invitee.
>>> MSG bob@hotmail.com Bob 353\r\n
MIME-Version: 1.0\r\n
Content-Type: text/x-msmsgsinvite; charset=UTF-8\r\n
\r\n
Application-Name: voice conversation\r\n
Application-GUID: {02D3C01F-BF30-4825-A83A-DE7AF41648AA}\r\n
Session-Protocol: SM1\r\n
Context-Data: Requested:SIP_A,;Capabilities:SIP_A,;\r\n
Invitation-Command: INVITE\r\n
Invitation-Cookie: 1578608\r\n
Session-ID: {CD482FDC-AE24-3574-C2A5-493813AD94D1}\r\n
\r\n
<<<>\r\n
MIME-Version: 1.0\r\n
Content-Type: text/x-msmsgsinvite; charset=UTF-8\r\n
\r\n
Invitation-Command: ACCEPT\r\n
Context-Data: Requested:SIP_A,;\r\n
Invitation-Cookie: 1578608\r\n
Session-ID: {A8B34C0E-2EEF-932F-F120-F7492E39CDA9}\r\n
Session-Protocol: SM1\r\n
Launch-Application: TRUE\r\n
Request-Data: IP-Address:\r\n
IP-Address: 203.122.147.102\r\n
\r\n
>>> MSG bob@hotmail.com Bob 242\r\n
MIME-Version: 1.0\r\n
Content-Type: text/x-msmsgsinvite; charset=UTF-8\r\n
\r\n
Invitation-Command: ACCEPT\r\n
Invitation-Cookie: 1578608\r\n
Session-ID: {CD482FDC-AE24-3574-C2A5-493813AD94D1}\r\n
Launch-Application: TRUE\r\n
IP-Address: 203.122.147.102:13455\r\n
\r\n
Connect to 203.122.147.102:13455 . . .\r\n
Here is an example of a voice conversation invitation which failed because the invitee did not have voice conversation installed:
>>> MSG bob@hotmail.com Bob 353\r\n
MIME-Version: 1.0\r\n
Content-Type: text/x-msmsgsinvite; charset=UTF-8\r\n
\r\n
Application-Name: Remote Assistance\r\n
Application-GUID: {56b994a7-380f-410b-9985-c809d78c1bdc}\r\n
Session-Protocol: SM1\r\n
Application-URL: http://www.microsoft.com\r\n
Invitation-Command: INVITE\r\n
Invitation-Cookie: 3863032\r\n
Session-ID: {DF93A302-30D2-DF92-C392-F391049DB9EA}\r\n
\r\n
<<<>\r\n
MIME-Version: 1.0\r\n
Content-Type: text/x-msmsgsinvite; charset=UTF-8\r\n
\r\n
Invitation-Command: CANCEL\r\n
Invitation-Cookie: 3863032\r\n
Cancel-Code: REJECT_NOT_INSTALLED\r\n
\r\n
source http://www.eggheadcafe.com/forumarchives/livecommdeveloper/Jul2005/post23106322.asp
