Export (0) Print
Expand All

Messenger Lock and Key API

The Messenger service  APIs can be used to access a Messenger service programmatically. These Messenger service interfaces and objects are locked by a mechanism called "Messenger Lock and Key" and must be unlocked before they can be used to connect to the Microsoft .NET Messenger Service. The lock and key restriction does not apply when connecting to corporate instant messaging servers, such as Microsoft Exchange Instant Messaging.

This topic explains how to unlock the Messenger service  APIs using Messenger Lock and Key. Programming with the Messenger service  APIs is discussed separately in Messenger Session Invite and Messenger Private APIs and Windows Messenger.

This topic contains the following sections.

Introduction

The Lock and Key mechanism applies to more than one of the objects exposed by the Messenger client and must be used to unlock each Messenger service object used by an application. For more information, see Interfaces and Objects.

The Messenger Lock and Key mechanism is an authentication process initiated by a Messenger client application. Each step of the process is described in detail in the Authentication Process section.

The section on Security and Encryption describes general precautions that can be taken to prevent Messenger client applications from exposing authentication information.

Note  To unlock and use the Messenger service  APIs, you must use a valid ID/key pair. For more information, see Developing and Testing Applications with the Messenger Service APIs.

Important  ID/key pairs are no longer being issued.

Terminology

The following terms have a specific meaning within the context of the Messenger APIs.

Messenger clientApplication that uses the APIs exposed by Windows Messenger to provide client-side functionality for use with Messenger service s.
Messenger service Service that a Messenger client application uses. Messenger client applications can use Microsoft .NET Messenger Service.
Messenger Lock and KeyA friendly name for the mechanism that is used to unlock Messenger service  APIs programmatically.
Messenger Session InviteA friendly name for a set of Messenger service  APIs that are locked with the Lock and Key mechanism, For more information, see Messenger Session Invite and Messenger Private APIs.
IDAn alphanumeric string value that identifies an application used to unlock the Messenger service  APIs.
KeyAn alphanumeric string value that identifies an application used to access the Messenger service  APIs.
RSA-MD5 Message Digest Algorithm (MD5)MD5 is used to hash data that is exchanged between your application and the Microsoft .NET Messenger Service during a challenge-response transaction.
RequestThe first step in the Lock and Key authentication process. An application must issue a request through the Messenger client API in order to receive a challenge to which it then can reply with a response.
ChallengeA response from a Messenger service to an application's request. A challenge is issued in the form of a Unicode string. A challenge can be issued to a Messenger client at any time, even without a request from a Messenger client application.
ResponseA response from a Messenger client application to a challenge it has received from a Messenger service .
ResultThe result of a Lock and Key authentication transaction between a Messenger client application and a Messenger service . The result can either be successful or unsuccessful.
Server CloudA computer network with a topology that is configured to host applications and services.

 

 

Note  Microsoft maintains a list of all valid ID/Key pairs that have been assigned for use by applications. For more information, see Developing and Testing Applications with the Messenger Service APIs.

Prerequisites

This section illustrates basic programming techniques that you can use to unlock the Messenger service  APIs. Therefore, the reader should be familiar with using and referencing APIs that are exposed by Component Object Model (COM) objects.

Some familiarity with hashing and authentication techniques will be beneficial to the reader, because the Messenger Lock and Key mechanism makes use of the MD5 hash algorithm, which helps provide an additional degree of security to the authentication process. Before implementing an application that uses the Messenger service  APIs, obtain a valid ID/Key pair from Microsoft. This ID/Key pair must be used to authenticate an application and unlock the Messenger service  APIs.

Interfaces and Objects

The Messenger service  APIs provide programmable objects and COM interfaces that you can use in a Messenger client application. Each is discussed in this section.

Objects

The Messenger service  API exposes two programmable objects that implement the Messenger Lock and Key mechanism. The following table links to the reference pages for the Microsoft Visual C++ objects.

C++ Object ReferencesDescription
MsgrSessionManager Messenger Session Object
MessengerPriv Messenger Private Object

 

If either a MsgrSessionManager or MessengerPriv object is used by an application, each object must first be unlocked before it can be used. If more than one object is instantiated by an application, then each object must be unlocked separately using the Messenger Lock and Key mechanism.

Interfaces

The following table lists the interfaces used with Messenger Lock and Key.

InterfaceDescription
IMsgrLock Implements the Messenger Lock and Key API.
IMessengerPrivate A Messenger service   API that implements IMsgrLock and provides programmatic access to the MessengerPriv object.
IMsgrSessionManager A Messenger service that implements IMsgrLock and provides programmatic access to the MsgrSessionManager object.

 

As you can see from the following table, there is a correspondence between the interfaces and the programmable objects described in the previous section. IMsgrLock provides the API for a Messenger client to invoke each step of the Messenger Lock and Key authentication process. IMsgrLock also exposes the Status property, which can be used to obtain the status of the API locking for a given object.

The following table lists the dispinterfaces that are used with Messenger Lock and Key.

DispinterfaceDescription
DMessengerPrivateEvents Fires notifications from a Messenger service for applications that implement IMessengerPrivate.
DMsgrSessionManagerEvents Fires notifications from a Messenger service for applications that implement IMsgrSessionManager.

 

Messenger Lock and Key events are fired to DMessengerPrivateEvents or DMsgrSessionManagerEvents, depending on the type of object from which the IMsgrLock interface is obtained.

Authentication Process

A Messenger client application must provide authentication to a Messenger service in each of the following scenarios.

  • When a Messenger service requests authentication with a challenge.
  • When a Messenger client application requires access to one or more of the Messenger service  APIs.

In both scenarios, the Messenger Lock and Key mechanism is used to provide authentication and unlock the Messenger service  APIs. The Messenger Lock and Key mechanism is implemented so that objects are unlocked individually. Therefore, the authentication process detailed in this section must be done for each Messenger service object in use by an application.

The following sections describe each step of the Messenger Lock and Key authentication process. Subsequent sections illustrate how a MsgrSessionManager object can be unlocked with Messenger Lock and Key. The same process is used to unlock any Messenger service object. Therefore, the IMessengerPrivate object can be unlocked using exactly the same procedure as shown in the following code, which unlocks the MsgrSessionManager object.

Request

This is the first step in the authentication process of a Messenger client application. Initially, a Messenger client application must issue a request for authentication to a Messenger service . In the first transaction between the Messenger client application and a Messenger service , the application must call the RequestChallenge method.

In order for a Messenger client application to participate in an authentication transaction, it must first instantiate an object. The Messenger client application must provide the appropriate event handlers for these events.

The RequestChallenge method takes a single parameter that uniquely identifies the authentication transaction. A random number should be used for this purpose.

Note  A Messenger client application must provide Lock and Key authentication for each Messenger object it creates. It must also re-authenticate after it has gone offline.

Challenge-Response

The Messenger service responds to an application's request with an authentication challenge. The application receives the server challenge when the OnLockChallenge event is fired.

The OnLockChallenge event handler has two arguments. The first, lCookie, is the same value that the Messenger client application passes to the Messenger service when the RequestChallenge method is invoked. The second argument, sChallenge, is a string that is generated by the Messenger service .

The first step in the OnLockChallenge event handler compares the value of lCookie with the variable passed by the RequestChallenge method to verify that the event notification corresponds to the applications challenge request. If the correct notification is received, then the server challenge string, bstrChallenge, is stored for later use in a variable. A Boolean variable is also set to TRUE in this handler, this value is used in other parts of the code to verify that a challenge has been received by the application.

After the OnLockChallenge event handler has received and verified the server's challenge, the application can proceed by formulating and sending its response.

You must concatenate the server challenge string and your key. It is important to combine the values prior to hashing so that authentication is successful.

Note  Each application must obtain its own ID/Key pair.

After the Messenger service challenge and Messenger client application key strings have been combined, a method on a hypothetical MD5 provider object is called to hash the resulting string using an MD5 algorithm.

The MD5 hashed string is passed as the second parameter of the SendResponse method. The use of the MD5 hash helps provide additional security during the authentication process.

After the Messenger client has received the authentication transaction, it processes the data and returns a result.

Note  It is the responsibility of the developer to implement or locate an implementation of the MD5 hash algorithm. MD5 has been implemented in several libraries that can by used with a variety of programming languages. Some are freely distributed in the public domain and can be found on the Internet.

Result

A Messenger client application receives the result of a Messenger Lock and Key authentication transaction with the OnLockResult event.

A Messenger client application cannot unlock the licensed Messenger client APIs more than once during a session. Therefore, if an application attempts to re-authenticate during the same session, the MSGR_E_API_ALREADY_UNLOCKED error code is returned and there is no resulting transaction.

Security and Encryption

External References

Although it is generally useful to encapsulate components using DLL files, the use of external references by an application can sometimes introduce a security hole. For example, using an external DLL that implements MD5 is not recommended, because this provides an opportunity for hackers to replace the external DLL file with a simple component that echoes the data sent by the application.

Therefore, instead of using an external DLL to perform MD5 hash, it is strongly recommended that any Messenger client application includes its own MD5 implementation. Using an internal code implementation instead of referencing an external DLL helps protect the security of the application.

ID/Key Pairs

As illustrated in the section on the Messenger Lock and Key Authentication Process, an MD5 algorithm is used to hash some of the authentication data, which helps provide an additional degree of security. A unique ID/key pair must be assigned for use by a particular Messenger client application. For more information, see Developing and Testing Applications with the Messenger Service APIs.

Hiding ID/Key Pairs

When source code is compiled, the resulting binary executable file invariably contains searchable strings of data. For example, when variables are declared and initialized with values, these can be detected by examining the contents of a compiled executable file. Therefore, care must be taken in developing a Messenger client application to ensure that the ID/Key pair is reasonably well hidden inside the executable file. Several techniques can be used to obfuscate or scramble sensitive data. Generally, the sensitive data is broken into its constituent characters. These characters are then transformed or encrypted so that the ID/Key is not trivial to read directly from the uncompiled source code. Additional code is implemented to reassemble the ID/Key programmatically at runtime.

Using one or more techniques to hide the ID/Key pair in the executable file of a Messenger client application is strongly recommended.

Related Topics

Messenger Session Invite and Messenger Private APIs
Windows Messenger

 

 

Send comments about this topic to Microsoft

Build date: 6/30/2010

Community Additions

ADD
Show:
© 2014 Microsoft