This document describes how to use Asn1Browser, member of uniGone Asn1Solutions software.
This software allows the analysis and display of ASN.1 encoded messages. These messages may be exchanged over TCP-IP by two applications or read in a log file generated by Asn1Browser itself or by another tool. Asn1Browser uses the specific ASN.1 syntax describing the exchanged messages to get the most readable display.
The decoding classes used by Asn1Browser are generated by Asn1Compiler. They are used in conjunction with the runtime library Asn1RT. Please refer to documentation associated with the compiler or to our web site to learn more about compliancies and restrictions.
To run Asn1Browser you need the following information :
All these information constitute a profile. Profiles are written in profile files. The bundle formed by the decoding classes (generated by Asn1Compiler) and a profile file is referred to as an Asn1API for Asn1Browser.
Asn1Browser is installed with an Asn1API called "Asn1Sample". Using this Asn1API, you can read the "<installation directory>/asn1Browser/record/Asn1Sample_asb_record.txt" log file (see Open a record session).
Notes :
Asn1Browser acts as a TCP-IP tee. So it must be configured to know the server IP address and TCP port. The client must be configured to connect to Asn1Browser IP address and local TCP port. The browser acts as a server for the current client of the application and it acts as a client for the current server.
You have to choose in the File menu "New connection" or use the "New connection" button to obtain the "New connection" box :
The "IP" panel invites you :
The "profile" panel invites you to select the profile to use for this connection.
Once you have entered the connection information, you can save this connection using "Save Connection As" in the File menu. The name of the file is free and it is recommended you install it in a special directory. Usually, the directory is named "connection" and the files have the extension ".net".You will then be able to open the same connection using this file using the "Open Connection" menu in the File menu.
At this time, Asn1Browser is waiting for a TCP-IP connection from the client. The lights of the status bar are red.
The client starts running and the status ligths will turn green on each side of the tee connection. Asn1Browser shows the name or address of the TCP client.
The client starts sending messages to the server and the browser will show the ASN.1 message in the "message panel" :
The messages sent from the client to the server are blue and the messages sent fom the server to the client are green. The "Colors" menu in the "View" menu allow the customization of these colors.
Help! : Some PDU can appear red, it means they have not been recognized by the decoder. Usually, the binary panel gives the message. The problem is often due to a wrong ASN.1 construction in the message. You have to analyze it. If ever you think the message is a well constructed ASN.1 message OR if the binary is not displayed, you can start an IP log ...
Note that the message panel does not display the main node of the PDU ("ROS CHOICE") but a particular one. Refer to the "display definition" of profile files.
To see the binary form of the PDU, you have to choose the "binary panel" in the "View" menu. The syntax panel will be split in two panels :
There is an AutoScroll mode. By default, it is "off" : the selected message remains displayed in the syntax window. When "on", the last received message is opened in the syntax window.
At any time of a net session, you can choose the recording of the message flow. This is achieved by using the record mode.
You will choose "Start" in the "Record" menu or with the "Start" button. Asn1Browser will ask you the name of the record file in which you want to save the message flow. The file is a text file (the extension of it is free).
You can choose to "suspend" and "resume" the recording. At the end, you will "stop" the record.
The record files can the be analyzed by Asn1Browser.
Here is an example of a record :
; Asn1Browser 3.1.1 - Copyright (C) 1999-2002 - asb_record
>14:38:36.0211
000000: a1 12 02 01 0c 02 01 0a 30 0a 80 02 32 30 62 04 |........0...20b.|
000016: 80 02 32 31 |..21|
ROS CHOICE
{
invoke SEQUENCE
{
invokeId InvokeId
{
present INTEGER = 12
}
opcode Code
{
local INTEGER = 10
}
argument OpenType
{
MakeCallArgument
{
callingDevice DeviceID
{
dialingNumber NumberDigits = 20
}
calledDirectoryNumber CalledDeviceID
{
deviceIdentifier ExtendedDeviceID
{
deviceIdentifier DeviceID
{
dialingNumber NumberDigits = 21
}
}
}
}
}
}
}
|
To close a session, you select "Close" in the "File" menu or choose the "Close" button. It is recommended to stop the client before closing Asn1Browser net session.
If a record has been started, it will be automatically stopped.
Usually, applications exchanging data are able to generate text or binary files in which sent and received messages are saved. Asn1Browser itself may generate text file.
These files may be read by Asn1Browser using a file filter. To build a new file filter, you have to refer to the Configuration guide.
To open a record file, you have to "Open record" in the "File" menu to obtain the "Open record" box :
The "profile" panel invites you to select the profile to use.
The "File" panel invites you to select the record files you want to read. You can select one or several files.
The messages read in the file(s) will be displayed. The session is called a record session. You can add other record files to this record session using the same menu.
Note : you can have a look to the file "Asn1Sample_asb_record.txt" in the record directory ; you will find in it examples for a lot of basic ASN.1 types. This file is to read with "Asn1Sample" profile.
To close a session, you select "Close" in the "File" menu or choose the "Close" button.
Depending on the system memory, Asn1Browser is able to keep in memory a limited number of messages. It will display only the most recent messages and will clean up from memory the first received. The number of cleaned up messages is displayed in the status bar. The number of messages kept in memory can be set using in the "View/Options..." menu.
Note : this limit doesn't prevent the PDUs to be recorded in the record file if a record has been started.
To analyze the IP exchanged messages between the two applications, you can select an "IP log" in the "View/Options..." menu. A file containing the TCP-IP data received by Asn1Browser will be recorded. This file is in the "<installation directory>/asn1Browser" directory and is named "asb_ip_log.txt".
This functionality can be usefull when trying to write a new message filter (refer to the Configuration guide), or when a message can not be decoded by Asn1Browser. In such a case, the binary panel may be empty. You must then select an IP log and send the message again to try to analyze the problem with the "asb_ip_log.txt" file.
Note : if you can not solve the problem, you can send to the uniGone Support :
A file filter (refer to the Configuration guide) is written using regular expressions. As it is not obvious to write a right one at the first time, it is useful to observe how it works.
To get a file filter log, you can select a "file filter log" in the "View/Options..." menu. The result will be stored in the "asb_trace.txt" file in the "<installation directory>/asn1Browser" directory.
The following explains how to analyze the file filter log.
Here is the log file we want to read with Asn1Browser :
; Asn1Browser 3.0.0 - (C) uniGone 1999-2001 - asb_record
>09:39:04.600
000000: a1 0e 02 01 01 02 01 47 30 06 80 04 38 36 34 31 |.......G0...8641|
ROS CHOICE
{
invoke Invoke
{
invokeId InvokeId
{
present INTEGER = 1
}
opcode operationCode
{
local INTEGER = 71
}
argument MonitorStartArgument
{
monitorObject MonitorObject
{
device DeviceID
{
dialingNumber NumberDigits = 8641
}
}
}
}
}
|
Here is the file filter used to read the log file :
fileFilter
{
id = "ff_asb_record"
class = "com.unigone.asn1Browser.file.dataFileReader.pattern.Pattern"
_checkNbline = 10
_description = "Asn1Browser record files"
checkPattern = "Asn1Browser.*asb_record"
filterIfTruePattern = "^;"
toServerPattern = "^>"
toClientPattern = "^<"
idHoroPattern = "^[<>]"
getHoroPattern = "[0-9]+:[0-9]+:[0-9]+.[0-9]+"
idStartDataPattern = "^[^<>].....:"
idDataPattern = "^......:"
idSkipBolDataPattern = "^......:"
idSkipEolDataPattern = "\|.*$"
idEndDataPattern = "^$"
}
|
As explained in the Configuration guide you may specify many file filters. Asn1Browser tries them one after one until the right one is found.
The file filter log indicates the number of the file filter tried :
@Profile.readFileName() - [fileFilter/messageFilter=#0] |
Then the analyze really begins. Each line read in the log file is reported in file filter log ; the read lines are given between square brackets.
First of all, one must check if the file matches the file filter with the "checkPattern". The maximum number of lines used for this is defined in the filter. In the example, one line is enough !
! checkFile [Asn1Browser record files], nbMaxLine = [10] ! checkFile : checkLine [1] [; Asn1Browser 3.0.0 - (C) uniGone 1999-2001 - asb_record] ! checkFile : file matches |
The analyze starts again at the beginning of the file to see if lines match the patterns.
! readFile : readLine [1][; Asn1Browser 3.0.0 - (C) uniGone 1999-2001 - asb_record] [1][filterIfTruePattern][true] |
This line matches the "filterIfTruePattern" pattern which means that the line can be ignored without further analysis.
! readFile : readLine [2][] [2][idStartDataPattern][false] ! readFile : readLine [3][>09:39:04.600] [3][toServerPattern][true] [3][getHoroPattern][true][09:39:04.600] [3][idStartDataPattern][false] |
As we can see, the line [2] (which is empty) doesn't match the "idStartDataPattern" pattern.
The line [3] is containing a ">" and the string "09:39:04.600". So the "toServerPattern" pattern and the "getHoroPattern" pattern are matched. But the "idStartDataPattern" pattern is not, the analysis goes on...
! readFile : readLine [4][000000: a1 0e 02 01 01 02 01 47 30 06 80 04 38 36 34 31 |.......G0...8641|] [4][idStartDataPattern][true] [4][idDataPattern][true][ a1 0e 02 01 01 02 01 47 30 06 80 04 38 36 34 31 ] ! readFile : readLine [5][] [5][idDataPattern][false] [5][idEndDataPattern][true] |
The line above are, at last, data that can contain the ASN.1 data. The line [4] matches : "idStartDataPattern" and "idDataPattern" patterns. The ASN.1 data are extracted from the line using for that the patterns "idSkipBolDataPattern" and "idSkipEolDataPattern".
The line [5], which is empty, matches the "idEndDataPattern" pattern so the analysis is summarized with :
===================================== date=09:39:04.600 data : a1 0e 02 01 01 02 01 47 30 06 80 04 38 36 34 31 ===================================== |
This shows the ASN.1 data that will be given to the decoder stage for an ASN.1 analysis.
Other lines don't match.
By default the message panel expands the first 50 nodes of the ASN.1 tree (in a breadth first order). If you want all the nodes to be automatically expanded you have to set the "Expand all ASN.1 nodes" option in the "View/Options..." menu.
Some ASN.1 values (especially OCTET STRING) can represent other protocol encoded values. Some plugins provide the browser with a "smart value", i.e. a display that enhances much the basic ASN.1 display (a byte array for an OCTET STRING for example). The browser is then able to display such values on the same line than the basic value but is also able to expand the smart value on several lines if any. To remove this expanded display, you have to unset the "Expand smart values" option in the "View/Options..." menu.
Plugin download base and download list filename (in download base) can be configured with these options in the Plugin panel. It allows users to install plugins in a local directory instead of uniGone's website (this may be useful for machines that don't have access to the internet).
Note : this mode requires installation of WinPcap for Windows or libpcap on Unix systems (see installation).
Asn1Browser acts as a packet sniffer. This mode is totally independant from the server or the client. The browser only requires to be installed on a machine on the same network.
You have to choose in the File menu "Open packet capture" or use the "Open packet capture" button to obtain the "Open packet capture" box :
The "Local network device" panel invites you :
Packets filtering can be achieved through a simple syntax drawn from WinPcap Packet capture filter expression syntax. Note that the filter applies directly on the WinPcap level and rejected packets are not given to the browser.
Optionally, you can define some known ports for protocols such as HTTP or SIP using the Options button. You can specify several ports you want to be treated as HTTP or SIP ports separating ports with commas.
If no ASN.1 analysis is performed, the browser will act as a simple packet sniffer. By default only the packet incoming number will be displayed in the "table view". Protocols such as IP, IPv6, UDP, TCP, ICMP, HTTP or even SIP may be viewed this way (the HTPP or SIP default ports may be changed when opening the packet capture session). For SIP users, note that SIP compact headers are replaced by complete headers.
If ASN.1 analysis is performed, after clicking "OK", Asn1Browser opens a packet capture window. By default, time, source IP address, source Port (TCP or UDP), destination IP address and destination port (TCP or UDP) are shown in the "table view".
The packet capture enables reading data from a file or captured from the network. Packets read from the network can be saved to a file once capture has been stopped.
To start a network capture select Capture/start.
During the capture, the packets are written in the table window and can be displayed in the detail window. Yet, they won't be analyzed by the ASN1 profile at once. Indeed, you should stop the capture in order ASN1 analysis is performed.
After stoping the capture, the "table view" will show all packets
as they have been received from the network device. If ASN.1 analysis is performed,
only packets containing data will be displayed. According to the chosen "table
view " configuration (set by the Table menu), packets fields will be displayed.
To get an advanced display, you must select a packet and then obtain the syntax
panel showing the packet decoding. If a packet m cannot be analyzed because
the message filter (see message filter
definition) requires more data, then it will be marked as "remaining data
in packet n" where n indicates the packet containing them.
The packet n containing the "remaining data" will use the data
contained in packet m to display the decoding.
A protocol stack can be complex using many protocols that can be imbricated. Since the browser doesn't rely on extra information such as TCP ports for example, protocols (we talk here about Protocols that have been defined in the profile, see Protocol definition) detection is impossible when the filter defined in the profile is the same for several protocols (sometimes a filter is ambiguous and doesn't allow protocol detection). This then makes the pure ASN.1 analysis impossible since the decoding engine doesn't have knowledge of protocols. Since Asn1Browser's purpose is to be a pure ASN.1 dedicated tool, some job is given to the user! Indeed, if there appears to be several protocols with the same filter, the decoding engine chains all of them. Provided they give an acceptable result (no decoder error and all data are used), they will all lead to a displayed decoding. The user will thus have to decide which decoding is acceptable given the context.
If several protocols are used together, they are sorted before they are used for decoding:
The decoding are then tried in this order. For protocols with ambiguous filter,
only "exact" decodings will be kept, decodings which throw exceptions
(meaning the data can't be decoded with the protocol) are simply ignored and
will not be displayed.