######################################################################
# Copyright (c) Trend Micro Inc. 2004-2013, All Rights Reserved      #
######################################################################

######################################################################
# Requirements
######################################################################
- Trend Micro Deep Security Manager 9.0
NOTE: Third Brigade Deep Security Manager 5.x or 6.x is not supported
by this sample SDK. More advanced versions of the Axis, Ant and Java
Runtime may have not been tested with this version of the Web Service
API samples but will most likely work.

- Apache Axis 1.4 (binary - axis-bin-1_4.zip) http://ws.apache.org/axis/
- JDK 1.6.0_26 (and optionally JRE 1.6.0_26 if you plan to run the samples in a separate JRE)

If you're building from the command prompt:
- Ant 1.7.1 (http://ant.apache.org/)

If you're building/developing in Eclipse:
- Eclipse 4.x


######################################################################
# Initial Steps
######################################################################
1. The following steps assume the SDK package was extracted to:

	c:\work\

2. Enabling the Deep Security Manager Web Service
Please refer to product documentation for help in enabling the Web Service.

3. Obtaining the Deep Security Manager Web Service API WSDL
The Deep Security Manager Web Service API describes its services in a published WDSL document. The 
SOAP Axis library is used to generate source code from the WSDL that reflects all the services 
available through the Web Service. This source code can be used to build Java applications
that can communicate with the Deep Security Manager Web Service API.

In order to develop for the Deep Security Manager Web Service API, the manager WSDL file will
need to be downloaded from a Deep Security Manager install.

a) Open an internet browser and connect to the Deep Security Manager Web Service URI:

	https://<hostname/IP>:4119/webservice/Manager?WSDL

b) Save the document as Manager.wsdl to the root of the WebServiceSamples directory.

	c:\work\Deep_Security_9_WebService_SDK\SOAPSamples\Manager.wsdl

4. Importing a Deep Security Manager public certificate into the JRE certificate store.
Communication between a client application and the Deep Security Manager Web Service interface
occurs over SSL encryption. Inorder for the Axis library to successfully communicate to a
SSL peer, the peer public certificate will need to be imported into the JRE's certificate store.

There are many ways to retrieve an installed Deep Security Manager's public certificate. The
following is one method:

Using Internet Explorer 7:
a) Launch IE 7 and connect to the Deep Security Manager web page.
b) Click on the Certificate panel next to the address bar.
c) Click View Certificates.
d) Click the Details tab.
e) Click "Copy to File..."
f) Export the certificate as "DER encoded binary X.509 (.CER)".
g) Save it to the root of the WebServiceSamples directory as manager.cer.

	c:\work\Deep_Security_9_WebService_SDK\SOAPSamples\manager.cer

Using Firefox 18:
a) Launch Firefox and connect to the Deep Security Manager web page.
b) Double-click on the Lock icon next to the address.
c) Click More Information.
d) Click View Certificate
e) Click the Details tab.
f) Click Export...
g) Export the certificate as "X.509 Certificate (DER)".
h) Save it to the root of the WebServiceSamples directory as manager.cer.

	c:\work\Deep_Security_9_WebService_SDK\SOAPSamples\manager.cer

Next import the public certificate into the JRE trust certificate store:

a) From the command prompt (As Administrator), change to the root directory of the JRE.

	cd C:\Program Files\Java\jre1.6.0_26

If using a JDK's JRE (which could be the case if the samples are intended to be
executed from the command prompt) the JRE can be located under \jre in the JDK directory.
	
	cd C:\Program Files\Java\jdk1.6.0_26\jre

b) Import the certificate into the root store.

	.\bin\keytool.exe -import -noprompt -alias <Friendly Name> -file <location of .cer file> -keystore .\lib\security\cacerts -storepass changeit

Example:

	.\bin\keytool.exe -import -noprompt -alias DeepSecurityManager -file "c:\work\Deep_Security_9_WebService_SDK\SOAPSamples\manager.cer" -keystore ".\lib\security\cacerts" -storepass changeit


NOTE: All distributions of a WebService application will be required to import or
copy this cacert certificate store file to the destination system for the target JRE used.

5. Download and uncompress Apache Axis.

	c:\work\axis

6. (If building the samples from the Command Prompt) Download and uncompress Apache Ant.

	c:\work\apache-ant

######################################################################
# Building and Running the Samples from the Command Prompt
######################################################################
a) Launch a Command Prompt.
b) Set the environment path to include the the JDK \bin and Ant \bin directories.

On Windows Command Prompt:

	set PATH=$PATH;c:\work\apache-ant\bin;C:\Program Files\Java\jdk1.6.0_26\bin

On Linux or Unix the Java binaries will already be available and no change is needed. If Ant
is installed on the system, it will be be available. Only if an alternative JDK/JRE is used 
should the path need to be modified.

c) Edit the build.xml Ant script file in the root of the sample directory.

	c:\work\Deep_Security_9_WebService_SDK\SOAPSamples\build.xml

Modify the src.axis.dir property value to the location of the Axis \lib directory:

	<property name="src.axis.dir" value="c:\work\axis\lib" />

d) Run the Ant script to generate the Web Service code from the WSDL and compile all the samples.

	ant build

NOTE: To clean up all generated files, run the following command:

	ant clean

At this point all the samples have been compiled and copied into a new jar file called samples.jar.
It can be found in the root WebServicesSamples directory. All compiled source can be found in the 
newly created \build directory.

	c:\work\Deep_Security_9_WebService_SDK\SOAPSamples\samples.jar
	c:\work\Deep_Security_9_WebService_SDK\SOAPSamples\build\

The sample applications can be executed from the sample.jar. Use the following example usage to 
execute them:

	java -classpath .\samples.jar;c:\work\axis\lib\* com.trendmicro.webserviceclient.samples.Connect
	java -classpath .\samples.jar;c:\work\axis\lib\* com.trendmicro.webserviceclient.samples.AgentInformation
	java -classpath .\samples.jar;c:\work\axis\lib\* com.trendmicro.webserviceclient.samples.FirewallEvents
	java -classpath .\samples.jar;c:\work\axis\lib\* com.trendmicro.webserviceclient.samples.DpiEvents
	java -classpath .\samples.jar;c:\work\axis\lib\* com.trendmicro.webserviceclient.samples.SystemEvents
	java -classpath .\samples.jar;c:\work\axis\lib\* com.trendmicro.webserviceclient.samples.CreateIpList
	java -classpath .\samples.jar;c:\work\axis\lib\* com.trendmicro.webserviceclient.samples.AssignDpiRule

Note that each sample application has its own command line usage. By executing the application 
without any arguments the usage will be displayed.

> java -classpath ..\samples.jar;c:\work\axis\lib\* com.trendmicro.webserviceclient.samples.Connect
Invalid number of arguments found.
Connect  <webservice url> <username> <password>
This sample application can be used to authenticate to a Deep Security
Manager WebService end point.

Here is an example of the Connect application with the correct usage:

> java -classpath ..\samples.jar;c:\work\axis\lib\* com.trendmicro.webserviceclient.samples.Connect https://192.168.200.144:4119/webservice/Manager?WSDL masteradmin password
Attempting to authenticate to Manager WebService...
Authentication successful.
Authentication session ID string recieved: 0CA8E23075296FD4E4AB6A4477A9DB8D

Ending session...
End session successful.


######################################################################
# Building and Running the Sample from Eclipse
######################################################################
1. Launch Eclipse, create a new Workspace.
2. Create a new Java Project.
  a) Select File -> New -> Java Project
  b) Name the project WebServiceSamples.
  c) Create it from existing source by specifying the Java sample root 
     directory by Deep Security version as the source directory.
     
     e.g. \WebServices\DeepSecurityManager_v9.0\Java\
     
  d) Click Next.
  e) Select the Libraries tab.
  f) Click Add External Jars.
  g) Navigate to the Axis library directory and select all the JAR files.
  h) Click Finish.

NOTE: Ignore any errors at this time. The Web Service API code has not been
generated yet.

3. Edit the build.xml Ant script file in the root of the WebServicesSamples 
project. Modify the src.axis.dir property value to the location of the Axis \lib directory:

	<property name="src.axis.dir" value="c:\work\axis\lib" />

4. Generate the Web Service API source from the manager.wsdl file by completing
the following by right clicking the build.xml file and select "Run As..." -> "Ant Build".

NOTE: Make sure the Manager.wsdl obtained in prevoious steps is located in the root 
directory of the Java project.

e.g. \WebServices\DeepSecurityManager_v9.0\Java\Manager.wsdl

5. Right click on the project and select "Refresh" (or press the F5 button) to 
refresh the project source. The missing class errors will no longer appear.

NOTE: Ignore the Axis warnings, they are not a concern.

At this point all the samples are ready to be modified and executed as desired. To
execute any of the sample application class files in the Package Explorer under
WebServicesSamples -> src -> com.trendmicro.webserviceclient.samples, just
right click on any of them and select "Run As" -> "Java Application".

The sample applications are command line based, so runtime arguments will be needed.
However the usage for each will be displayed in the Eclipse Console window when run.

  Invalid number of arguments found.
  Connect  <webservice url> <username> <password>
  This sample application can be used to authenticate to a Deep Security
  Manager WebService end point.

To specify arguments for a sample application:
a) Attempt to run the application once by right clicking on the sample file and 
selecting "Run As" -> "Java Application".

NOTE: This step is necessary only the first time the sample is run as it will register
in the project as an application.

b) Right click on the same sample application and select "Run As" -> "Open Run Dialog..."
c) Select the Arguments tab.
d) Specific the desired "Program arguments". For example, for the Connect.java application
the Web Service URL and user account are required.

	https://<manager hostname/IP>/webservice/Manager <username> <password>

e) Click Apply and Close.

Now each time you execute that sample application by right clicking on it and selecting
"Run As" ->  "Java Application", the arguments will be passed to it.

  Attempting to authenticate to Manager WebService...
  Authentication successful.
  Authentication session ID string recieved: F842656DD2422B5874140DD645E16939

  Ending session...
  End session successful.




Explore the samples! Suggest new ones! Have fun! Let us know!