/************************************
* Readme.txt for the IPMP REL Tool
************************************/

A) - Overview

The IPMP_RELTool is a DLL software module which may be loaded by the MPEG-4 IPMP-X framework whenever an IPMP_DescPointer, containing the Descriptor ID of the REL Tool in an OD is given, and the associated IPMP_Descriptor is known at the terminal [1], or when another IPMP Tool (e.g. the Master Tool) receives an IPMP_ConnectTool message with the REL Tool descriptor in it.

The IPMP_RELTool is based on Microsoft MSXML4 parser and the example source codes from the ContentGuards example implementation of MPEG-21 REL Engine [4]. The current version supports only one Right play and one Condition validityInterval that are currently supported by the ContentGuards example implementation. The REL License and query are sent to the IPMP_RELTool inside IPMP_RightsData messages which are contained in IPMP_Secure_Container messages, although the mutual authentication and encryption/decryption tasks provided by the SecurityLib class are not implemented yet.

Once the License and query are received and copied internally, the IPMP_RELTool performs the validation procedure. A detailed explanation on how the validation procedure is performed may be found in [4]. The result is sent back to the Sender via IPMP_CanProcess message. Moreover, the IPMP_RELTool sends back to the Sender the information extracted from the License and query during the validation process, using an IPMP_OpaqueData message. This message contains, in case at least one matching grant was found, detailed information on the data found in the License, or more precisely, the Modulus and Exponent of the Issuers of any grant encountered, the Conditions and Issuers for all matching grants found in the validation process and which condition was met. In case no matching grant was found, the IPMP_OpaqueData message contains in a string the Issuers and the Condition, but stating that no matching grant was found. Finally in the case some errors occurred, the IPMP_OpaqueData contains the detailed info for the failure.



/***************************
B) - Running the application


1) The IPMP REL Tool requires the Microsoft MSXML 4.0 Parser installed. This can be obtained at: http://msdn.microsoft.com/downloads/default.asp?url=/downloads/sample.asp?url=/msdn-files/027/001/766/msdncompositedoc.xml 

2) Download from the NIST cvs repository the IM1 software module as explained in [2].

3) Open the workspace IM1.dsw in the folder \IM1\_Workspaces.

4) The current IPMP-X reference software implementation loads the IPMP Tools present in the directory \IM1\Debug on the basis of a string of bytes appended at the end of their DLL file after these are built., add the command AppendBin.bat. This will launch a batch file in the respective directories that will perform this operation. For more information on how to compose this string of bytes have a look at the documentation of the method IPMPServicesFull::CheckDllForTool in the file \IM1\Craig-IPMP\IPMPXFull\IPMPXFull.cpp. 

5) Go to build->batch build and deselect all of the release versions then click build.

6) Edit the file \IM1\_Registry\im1.reg. If not present the "IPMPSystem"="IPMPXFull.dll" entry, add it and update your registry.

7) Copy all DLLs from IM1\IM1Decoders\dlls to the IM1\Debug directory that Visual Studio has created.

8) Copy the \IM1\IPMP_MasterTool\filesForRunIt\ipmpx.trif file and paste it in the \IM1\Debug directory.

9) Copy all the files from \IM1\IPMP_RELTool\licensesAndQueryExamples into the \IM1\Debug directory. These are examples of licenses and query files provided in [4].

10) Set as Active Project the IPMPXFull project. 

11) In the settings of the IPMPXFull project, in the Debug\General Options, set as Executable the file: \IM1\Debug\IM1player.exe, Working Directory: \IM1\Debug, Program arguments: ipmpx.trif.

12) Launch the application.

13) When the pathname of the query is being asked, the one proposed is a valid query that should succeed in the validation process. Try to change the pathname of the query using some of the name proposed in the file ExamplesOfQueryPathnames.txt in the directory \IM1\IPMP_RELTool for having different results.

14) For modifying the ipmpx.trif file, for example changing the license pathname in the content, copy the ipmpx.txt and ipmpx.scr files from the \IM1\IPMP_MasterTool\filesForRunIt to the \IM1\Test directory, modify the ipmpx.txt and ipmpx.scr files ad create a new ipmpx.trif file as following: 
	- Add to the System path Environment variable the \IM1\Test directory
	- Open the DOS window and cd to the \IM1\Debug directory
	- Type BifsEnc ipmpx.txt
	- Type Mux ipmpx.scr
	- Copy the generated ipmpx.trif file into the IM1\Debug directory
  

/****************************************************
C) - Known limitations of the current implementation:

1) The Mutual Authentication that should take place between the Master Tool and the REL Tool is not implemented yet, as well as the encryption/decryption functions for sending message carried into the IPMP_SecureContainer.

2) The Master Tool and the REL Tool doesnt have the messages IPMP_GetTools, IPMP_GetToolsResponse, IPMP_GetToolContext and IPMP_GetToolContextResponse implemented, therefore in the ToolMessages exchanged between the two IPMP Tools the Receiver field is filled statically and not dynamically. If other IPMP Tools are loaded in the Terminal, the ToolMessages may be sent to the wrong Receiver. 


/*************
D) References:

[1] Study of FPDAM ISO/IEC 14496-1:2001 / AMD3 in ISO/IEC JTC 1/SC 29/WG11 N4849, Klagenfurth, Austria, July 2002.

[2] Mika?l Bourges-Svenier, Wo Chang, CVS access to MPEG reference software in ISO/IEC JTC1/SC29/WG11 M8705, Klagenfurth, Austria, July 2002.

[3] MPEG-4 Systems Software Status and Implementation Workplan in ISO/IEC JTC 1/SC 29/WG11 N5089, Klagenfurth, Austria, July 2002.

[4] Xin Wang, Thomas DeMartini, Jose Romero-Lobo and Edgar Valenzuela, An Example Implementation of MPEG-21 REL Reference Software in ISO/IEC JTC 1/SC 29/WG11 M9067, Shanghai, China, October 2002.

[5] Text of ISO/IEC 21000-5 CD  Part 5: Rights Expression Language in ISO/IEC JTC 1/SC 29/WG 11/N4942, Klagenfurt, Austria, July 2002.


