Wednesday, April 15, 2009

File post in OCS using ucma api:

The following registry entry changes are required.

 

Go to command prompt, type “regedit”.

 

Go to the following path:

 

HKEY_CURRENT_USER\Software\Policies\Microsoft\Communicator

 

Create a new DWORD value with value name “AllowUnencryptedFileTransfer” and value as “1”.


 

 

File Post

Bot posts a file to person “x”.

Preconditions:

1)      Both person “x” and bot must be logged in.

2)      An IM session must be created between Bot and person “x”.

Steps:

1)      Bot sends a file transfer invite message to person “x” which has the following format:

 

Content-Type: text/x-msmsgsinvite; charset=UTF-8

 

Application-Name: File Transfer\r\n

Application-GUID: {5D3E02AB-6190-11d3-BBBB-00C04F795683}\r\n

Invitation-Command: INVITE\r\n

Invitation-Cookie: <invitation cookie – random number>\r\n

Application-File: <file name to be transfered>\r\n

Application-FileSize: <file size>\r\n

Connectivity: N\r\n \r\n

 

 

2)      Person “x” gets the request, and can do 2 things – accept/reject;

 

If person “x” accepts the following details are received by the bot.

 

Content-Type: text/x-msmsgsinvite; charset=UTF-8

 

Invitation-Command: ACCEPT\r\n

Invitation-Cookie: <invitation cookie – same as previous number>\r\n

IP-Address: <IP address – where to connect>\r\n

Port: <port number – which port to connect>\r\n

PortX: <alternative port - can be ignored>\r\n

AuthCookie: cookie – to be used for authentication during FTP>\r\n

Request-Data: IP-Address:\r\n

 

       If person “x” cancels the request then,

 

Content-Type: text/x-msmsgsinvite; charset=UTF-8

 

Invitation-Command: ACCEPT\r\n

Invitation-Cookie: <invitation cookie – same as previous number>\r\n

Cancel-Code: <reason for cancellation>

 

On cancel command, the Bot should just ignore the message and not transfer the file. The below steps will not be followed.

 

3)      The above 2 messages are the sent using SIP messages. After this the file transfer happens using the MSNFTP protocol.

 

 

Person “x” client creates a TCP server and starts listening at the port (the one sent in the 2nd message).

The Bot creates a TCP client and connects to IP address : Port (the one sent in the 2nd message).

        As soon as the Bot connects, it receives a version command from Person “x’s” client:

 

VER MSNFTP

 

On receiving the version command, the Bot sends a version command:

 

VER MSNFTP

 

 

4)      The person “x’s” client sends an authentication message in the following format:

 

USR <username> <auth cookie>

 

Here the username is the username which wants to receive the file and the auth cookie is the one which was sent in the 2nd message.

 

The Bot verifies if it is the same username and auth cookie, if same it sends a FIL command in the following format:

 

FIL <File-size>

 

5)      The person “x’s” client on receiving the FIL command, sends a Transfer command in the following format:

 

TFR

 

6)      On receiving the TFR command, the Bot starts transferring the file bytes as packets in the following way:

 

The packet size is 2048 bytes:

Bytes header + 2045 bytes body

§  Headers: 3 bytes

·         1st byte

¨       ‘0’ indicate file not yet transferred

¨       ‘1’ indicate file is transferred

·         2nd and 3rd bytes indicates the size of the body:

                                                   Body size = 2nd byte + (3rd byte x 256)

 

At the end, the Bot transfers 3 bytes  header 1,0,0

·         1st byte

¨       ‘0’ indicate file not yet transferred

·         2nd and 3rd bytes indicates the size of the body:

                                                   Body size = 2nd byte + (3rd byte x 256)

                                                                    = 0 + 0 = 0

7)      The person “x’s” client sends a BYE command in the following format:

 

BYE <code>

 

The code could be as follows:

 

      2147942405               Failure: receiver is out of disk space

2164261682               Failure: receiver cancelled the transfer

      2164261683               Failure: sender has cancelled the transfer

      2164261694               Failure: connection is blocked

      16777987                   Success

      16777989                   Success

 

 

8)      At any time, the a CCL command can be sent by the person “x’s” client indicating that the person “x’s” client has cancelled the file transfer, in which case the file transfer should be stopped immediately and the TCP client connection should be closed.

 

CCL

 

If a BYE command is sent by person “x’s” client then the TCP client connection should be closed.

 

 

 

 

 

File Post

Person “x” posts a file to Bot.

Preconditions:

3)      Both person “x” and bot must be logged in.

4)      An IM session must be created between Bot and person “x”.

Steps:

1)      Person “x”  sends a file transfer invite message to Bot which has the following format:

 

Content-Type: text/x-msmsgsinvite; charset=UTF-8

 

Application-Name: File Transfer\r\n

Application-GUID: {5D3E02AB-6190-11d3-BBBB-00C04F795683}\r\n

Invitation-Command: INVITE\r\n

Invitation-Cookie: <invitation cookie – random number>\r\n

Application-File: <file name to be transfered>\r\n

Application-FileSize: <file size>\r\n

Connectivity: N\r\n

Encryption: S

 

 

2)      Bot gets the request

 

Bot accepts the file transfer request by sending the following message:

 

Content-Type: text/x-msmsgsinvite; charset=UTF-8

 

Invitation-Command: ACCEPT\r\n

Invitation-Cookie: <invitation cookie – same as previous number>\r\n

IP-Address: <IP address – where to connect>\r\n

Port: <port number – which port to connect>\r\n

AuthCookie: cookie – to be used for authentication during FTP>\r\n

Request-Data: IP-Address:\r\n

Sender-Connect: TRUE\r\n \r\n

 

3)      The above 2 messages are the sent using SIP messages. After this the file transfer happens using the MSNFTP protocol.

 

 

Bot client creates a TCP server and starts listening at the port (the one sent in the 2nd message).

The person client “x” creates a TCP client and connects to IP address: Port (the one sent in the 2nd message).

        As soon as the person “x” client connects, the bot sends a version command as follows:

VER MSNFTP

 

On receiving the version command, the Person “x’s” client sends a version command:

VER MSNFTP

 

 

4)      The Bot sends an authentication message in the following format:

 

USR <username> <auth cookie>

 

Here the username is the username which wants to receive the file and the auth cookie is the one which was sent in the 2nd message.

 

The Person “x’s” verifies if it is the same username and auth cookie, if same it sends a FIL command in the following format:

 

FIL <File-size>

 

5)      The Bot on receiving the FIL command, sends a Transfer command in the following format:

 

TFR

 

6)      On receiving the TFR command, the Person “x’s” client starts transferring the file bytes as packets in the following way:

 

The packet size is 2048 bytes:

Bytes header + 2045 bytes body

§  Headers: 3 bytes

·         1st byte

¨       ‘0’ indicate file not yet transferred

¨       ‘1’ indicate file is transferred

·         2nd and 3rd bytes indicates the size of the body:

                                                   Body size = 2nd byte + (3rd byte x 256)

 

The bot understand this format and captures the byte body accordingly.

 

7)      The person Bot sends a BYE command in the following format:

 

BYE 16777989

 

Indicating that the file transfer was successful.

 

If any exception occurred in between, then the Bot should send a cancelation command as follows:

 

CCL

 

Then the Bot should disconnect the server and close the connection to free the port.

The file is constructed using the bytes.

 

 

Friday, March 27, 2009

FILE POST IN OCS

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

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

Other Invitation Types

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