Asn1Browser v4.4

Installation

Contents

• Introduction
• Installing Asn1Browser
• JVM configuration
• Running Asn1Browser
• Installing a plugin
• Using a plugin
• Uninstalling a plugin
• Uninstalling Asn1Browser

Introduction

This document describes how to install and uninstall Asn1Browser and an Asn1API for Asn1Browser.

The installation procedure of Asn1Browser has the following steps :

1. Installing Asn1Browser
2. Running Asn1Browser

The installation procedure of a plugin also known as an Asn1API for Asn1Browser has the following steps :

1. Installing a plugin
2. Using a plugin

Afterwards, please refer to the User Guide to learn more about Asn1Browser.

To uninstall a plugin, see :

1. Uninstalling a plugin

To uninstall Asn1Browser, see :

1. Uninstalling Asn1Browser

Installing Asn1Browser

Asn1Browser is installed by a self-installing executable for Windows platforms, zip files are provided for others platforms.

The distribution leads to the following image in the installation directory :

• asn1Browser/ReadMe.html
• asn1Browser/License.html
• asn1Browser/ReleaseNotes.html
• asn1Browser/bin/ : executable files and JVM configuration file.
• asn1Browser/lib/asn1Browser.jar : the core of Asn1Browser.
• asn1Browser/lib/unigoneCommon.jar : library from uniGone.
• asn1Browser/lib/antlr.jar : library from Terence Parr (jGuru.com).
• asn1Browser/lib/gnu.jar : libray from the GNU Project (Free Software Foundation).
• asn1Browser/lib/jpcap.jar : libray containing JNI for interfacing libpcap or WinPcap with Java.
• asn1Browser/docs/index.html : the index of the documentation.
• asn1Browser/docs/guide/ : the documentation.
• asn1Browser/util/WinPcap4.0/WinPcap_4_0_2.exe : this tool must be installed independently on your Windows platform in order packet capture mode works. see Note.
• asn1Browser/util/WinPcap4.0/Jpcap.dll : this dll must be installed in the bin directory of your JVM. see Note.
• asn1Browser/profiles_Asn1Sample.cfg : the profile file of the Asn1Sample plugin (or Asn1API for Asn1Browser).
• asn1Browser/asn1API/Asn1Sample/lib/Asn1Sample.jar : decoding classes generated by Asn1Compiler from the Asn1Sample ASN.1 syntax.
• asn1Browser/asn1API/Asn1Sample/asn1/Asn1Sample.asn1 : the Asn1Sample ASN.1 syntax.
• asn1Browser/record/Asn1Sample_asb_record.txt : a log file generated by Asn1Browser when using the Asn1Sample ASN.1 syntax.
• asn1Browser/uninstall/ : contains the uninstall program to remove the distribution from your disk.
• asn1Browser/asn1Compiler_asb : this directory is installed only if you are using uniGone Asn1Browser Professional. It contains Asn1Compiler which allows the compilation of any ASN.1 syntax; thus making PDUs coded using any syntax displayable in the browser.

On Windows platforms, SUN jre 1.4.2 is installed in jre directory. The installed jre includes Jpcap.dll containing JNI material for packet capture mode.

Note for "packet capture" mode (available on Windows OS) : to use packet capture mode, WinPcap layer is required as well as the installation of the jpcap.dll file.

- on Windows platform :

1 - WinPcap must be installed independently using an external installer provided by the Politecnico di Torino. WinPcap 4.0 is required and packet capturer mode has been currently tested with it on Windows 98, NT/2000, XP, Vista. After installing Asn1Browser, uninstall previously installed WinPcap if any unless it is WinPcap 4.0 and then just launch WinPcap_4_0_2.exe. If you have some problems running the packet capture mode, please do :

- uninstall WinPcap
- reboot the computer
- install WinPcap 4.0 using WinPcap_4_0_2.exe.

If the problems persist please check http://winpcap.polito.it/ to see if WinPcap is supported on your platform.

2 - Jpcap.dll must be included in the JVM : copy asn1Browser/util/WinPcap4.0/Jpcap.dll into the bin directory of your JVM. For example, if your JVM is installed in c:\Program Files\Java\jr6, simply copy asn1Browser/util/WinPcap4.0/Jpcap.dll into c:\Program Files\Java\jr6\bin.

JVM configuration

The executable file asn1Browser/bin/Asn1Browser.exe has been built by the ZeroG InstallAnywhere tool. It is used to launch Asn1Browser on Windows platform more easily than the batch file. It tries and locate the JVM on the computer. If there is no JVM, it requires it.

The "asn1Browser/bin/Asn1Browser.lax" configuration file (located in the installation directory) allows you to customize the JVM. In this file, '\' must be escaped writing '\\'.

For example, you can define the location of your JVM :

lax.nl.current.vm=d:\\j2sdk1.6.0\\jre\\bin\\java.exe

The "asn1Browser/bin/Asn1Browser.lax" configuration file (located in the installation directory) allows you to customize the JVM initial and maximum heap size. Reading big files may require more memory than the default value allocated to the JVM.

For example if you add the following lines to the "lax" file then the initial and maximum heap size will be set to 768 Mb.

#   JVM initial heap size
#   ---------------------
#   Specify the initial size, in bytes, of the memory allocation pool for the JVM
lax.nl.java.option.java.heap.size.initial=805306368

#   JVM maximum heap size
#   ---------------------
#   Specify the maximum size, in bytes, of the memory allocation pool for the JVM
lax.nl.java.option.java.heap.size.max=805306368

Note that this value depends of your computer configuration.

Running Asn1Browser

To run Asn1Browser you have to run the executable file installed in the "asn1Browser/bin" directory.

Note : Asn1Browser is a pure Java application. Indeed, to run it, you have to start a Java virtual machine, specify a list of jar files (you may use the "-classpath" option of your Java application launcher or use the CLASSPATH environment variable) and invoke the "com.unigone.asn1Browser.Asn1Browser" class. The jar files are those in the "asn1Browser/lib" directory.

Installing a plugin

For decoding a ASN.1 based protocol message, the browser needs to refer to what is called a plugin or an Asn1API for Asn1Browser. A plugin (in the following documentation we will employ both terms plugin or Asn1API for Asn1Browser) contains :

• Java decoding classes generated from an ASN.1 syntax by Asn1Compiler.
• a profile file for Asn1Browser.

In the following "<Asn1API>" is to be replaced by the name of your plugin.

A plugin can be installed by the "Plugins" menu. Actually, a plugin stands in a zip file named <Asn1API>_asb.zip. The installation download this file from the uniGone's web site and unzip it in the 'asn1Browser' directory (the zip file is deleted after installation). You could do the same by hand if you wish.

The installation of a plugin leads to the following image :

• asn1Browser/profiles_<Asn1API>.cfg : the profile file of Asn1Browser.
• asn1Browser/asn1API/<Asn1API>/lib/<Asn1API>.jar : the decoding classes generated from the ASN.1 syntax called the library.
• asn1Browser/asn1API/<Asn1API>/asn1/ : the ASN.1 syntax used to generate the library.

If you are using Asn1Browser Professional, you will have the capabilty of generating the library but the profile definition will have to be manually built. The library is generated through the compiler provided with the package. Installation into the browser must then be achieved manually. To do so, you just have to :

1. make a copy of the jar file generated by the compiler into the appropriate directory asn1Browser/asn1API/<Asn1API>/lib/
2. build a specific profile file for the ASN.1 syntax to be used as explained in the configuration chapter
3. copy this profile file into asn1Browser directory (naming is important : the file name must begin with 'profiles' - commonly profiles_<Asn1API>.cfg)

User plugin base

If you have several licenses to use the browser (or a site license), you can manage your own plugins download base (without needing a http server). First of all, let's explain how is organized our plugins base on the uniGone's web site. This base needs to offer both evaluation and release plugins. Authentication is required for release plugins while none is required for evaluation.

We will take an example of 2 plugins CSTAp2 and H323. The base is organized in the download directory like this:

...-download
            |_ Asn1API-v2 
                         |_ CSTAp2_asb
                                      |_ release
                                                |_ CSTAp2_asb.zip
                                      |_ CSTAp2_asb-Eval.zip

                         |_ H323_asb
                                      |_ release
                                                |_ H323_asb.zip
                                      |_ H323_asb-Eval.zip

            |_ products-list.txt

For building your own base you will need to build the same directory image, you need to :

1. build the base where plugins are to be installed.
   For example, we choose a location on a machine with a hostname 'tomate'. On that machine, we will install the plugins base in a directory named 'myAsn1Browserplugins'. We suppose we have to install the 2 plugins, CSTAp2 and H323. They may have been built by Asn1Browser Professional, or downloaded from uniGone's web site.
   In 'myAsn1Browserplugins' just build the same directory image as above.
   1. If you have purchased release plugins, you will surely need to avoid users from authenticating (although they can authenticate providing whatever credentials). Thus we propose to fool the authentication process replacing the evaluation plugins by the release ones. For doing so, you have just to rename the CSTAp2_asb.zip file into CSTAp2_asb-Eval.zip and install it in 'myAsn1Browserplugins/Asn1API-v2/CSTAp2_asb'. Do the same for H323.
2. define a file listing the plugins available in the base.
   The file (which default name is "products-list.txt" - this name may be modified through the View/Options menu) shall contain one plugin per row where a plugin is named myPlugin_asb. Here is the content of the products-list.txt containing our 2 plugins:
   CSTAp2_asb
   H323_asb
3. through the View/Options menu, users will have to specify the new base "file:///\\tomate\myAsn1Browserplugins" and optionally change the download list filename. If you have release plugins and have proceeded as explained in 1.1, users won't have to authenticate and they will get the release plugins (otherwise they may authenticate providing whatever credentials they want).

Using a plugin

A profile file is provided with a plugin. This file defines a profile which allows you to use the plugin. Please refer to the User Guide.

Uninstalling a plugin

To uninstall a plugin, just remove the "asn1Browser/asn1API/<Asn1API>/" directory and the profiles_<Asn1API>.cfg in the asn1Browser directory.

Uninstalling Asn1Browser

To uninstall Asn1Browser:

• for Windows platform : go to the "asn1Browser/uninstall" directory in your installation directory and launch the "uninstall.exe" tool.
• for other platforms, simply remove directory "asn1Browser".

Note : If installed, WinPcap will remain installed unless you uninstall it using its embedded uninstaller.