Dedexer user's manual

Dedexer

Dedexer is a disassembler tool for DEX files. DEX is a format introduced by the creators of the Android platform. The format and the associated opcode set is in distant relationship with the Java class file format and Java bytecodes. Dedexer is able to read the DEX format and turn into an "assembly-like format". This format was largely influenced by the Jasmin syntax but contains Dalvik opcodes. For this reason, Jasmin is not able to compile the generated files.

Read more about DEX disassembling in this blog entry or read this introductory presentation. Also see the pages maintained by Dan Bornstein, the original author of Dalvik about the Dalvik virtual machine that also has a Dalvik bytecode section.

Download

Access the download page from here.

News

2011.12.05 - Dedexer 1.17 was given clean certification by Softpedia.
2010.12.14 - Dedexer was given 5 stars award by soft82. It has also received clean certification.
2010.12.13 - Dedexer 1.13 again made it into Softpedia, this time into the Windows programming tool section.
2009.12.02 - I will make a longer presentation about the Dalvik bytecode and Dedexer on Droidcon London 2009.
2009.10.22 - I will make a short presentation of Dedexer for the London Android Group. Presentation is available here.
2009.08.23 - Dedexer 1.5 is now featured in Softpedia. Even though it is in the Mac developer tools section, dedexer has always been platform-independent.

How to use

Download ddx.jar and launch dedexer like this:

java -jar ddx.jar

Typical invocation is the following:

java -jar ddx.jar -d <directory> <dex file>

<Directory> is the file system location where dedexer generates its output file and <dex file> is the location of the input file. Additonally, the -o flag can be added to the command line which generates a detailed log file about the internal structure of the DEX file.

Register tracing

Dedexer's new feature is register tracing. If this feature is enabled, dedexer behaves like a bytecode verifier and tracks how an instruction influences the types stored in registers. This information is printed after the instruction. For example:

const/4 v1,1
; v1 : single-length
iget-boolean v0,v2,android/widget/AbsListView.mScrollingCacheEnabled Z
; v0 : single-length , v2 : Landroid/widget/AbsListView;

This feature can be enabled by the -r flag.

Symbolic ODEX disassembly

Dedexer disassembles Optimized DEX (ODEX) files by default, without having to specify any flags. The disassembled program, however, will contain the vtable indexes and memory offsets of the invoke-virtual-quick and iget/iput-quick instruction parameters. Dedexer is able to resolve these indexes into symbolic method and field names if the dependencies of the ODEX file under disassembly are available.

Dependencies are other ODEX files that contain classes that the ODEX file under disassembly uses. These files can normally be found in /data/dalvik-cache directory on the target system. Unlike normal DEX files, an ODEX file is tied to its dependencies and exact disassembly cannot be guaranteed if the very same files are not available that were used when the DEX file was optimized. Unlike Dalvik, Dedexer does not verify the dependency files by hash but correct operation is not guaranteed if the dependencies are not the same as the those used during optimization.

The ODEX file lists its dependencies. If symbolic disassembly is requested with the -e <directory> flag, Dedexer reads the dependency list and looks for the dependency files in the directory specified by the flag. Only the file name part of the dependency file is used, e.g. if -e /tmp was specified and the dependency list in the ODEX file contains /data/dalvik-cache/system@framework@ext.jar@classes.dex, Dedexer will look for /tmp/system@framework@ext.jar@classes.dex file. If the -e flag is specified and any of the files in the dependency list is not found, Dedexer stops with an error after listing the missing dependencies.

Note that an ordinary ODEX file contains the largest ODEX files (framework.jar, core.jar) as dependencies. Loading these can take a lot of memory and Dedexer may run out of the default Java heap size. If you experience OutOfMemoryErrors, increase the Java heap size (-Xmx512m has always worked for me).

How to compile

You are encouraged to extend the tool, there is a lot to do! In order to compile dedexer, you need JUnit 4.5. There are no particular restrictions on the Java environment, JDK 1.5.0 and JDK 6 were tested.

Download ddx.zip file, edit the build.xml and update the home and junit-home properties to reflect the layout of your file system. Then you can build dedexer by invoking ant. The "ant junit" command runs the unit tests too.

License

Dedexer is in the public domain, no rights are reserved. If you reuse it, please, retain the credits.

Gabor Paller
http://pallergabor.uw.hu

1.22	Special characters in string constants are now escaped. rsub-int and rsub-int/lit8 instruction names replaced sub-int/lit16 and sub-int/lit8 according to the official instruction set documentation.
1.21	String table handling was refactored as the old version did not handle multi-byte string length and non-ASCII string table entries properly. Thanks to Siegfried Rasthofer for identifying these bugs.
1.20	Two bugs related to file syntax have been fixed. There was an extra dash in the name of the "mul-int/lit8" instruction and the semicolon was omitted at the end of certain class references. Thanks to Siegfried Rasthofer for identifying these bugs.
1.19	Bug was fixed that swallowed data areas that immediately followed sparse-switch and packed-switch jump tables. This was due to an erroneous calculation of the jump table length that did not affect the decompilation of the jump table itself but omitted other data areas following those jump tables. Thanks to Siegfried Rasthofer for identifying the bug.
1.18	Bug was fixed that resulted in dropping labels if more than one label was placed at one location. This typically affected default labels of switch statements.
1.17	Support for execute-inline/range optimized instruction added. Inline function table was fixed for version 0x36 ODEX file. Inline function indexes differ between 0x35 and 0x36 ODEX file versions, both index tables are supported now. Inline function names are now resolved even if symbolic ODEX disassembly is not enabled.
1.16	New ODEX version code and instructions were added.
1.15	Bugfix release: const-string/jumbo is now supported. Thanks to Guillermo A. Pérez for providing this improvement.
1.14	Bugfix release: multidimensional types were not handled properly. Thanks to Nelson Elhage for identifying the problem and providing the fix.
1.13	Bugfix release: endless loop in register analysis (-r switch) occured when disassembling some DEX files. Fixed.
1.12	Bugfix release: bug in parameter annotation processing fixed, unit tests now run on Linux too.
1.11	Support for const-string/jumbo added
1.10	Bugfix release: in case of class inconsistency, the dataflow analyser now calculates the youngest ancestor of the two inconsistent classes.
1.9	Bugfix release: a number of bugs fixed in the symbolic ODEX disassembly feature
1.8	Full symbolic ODEX disassembly feature
1.7	Trace disassembler, register tracing added
1.6	Bugfix release: annotations in ODEX fault fixed
1.5	Full annotation support, including .throws, .inner, .enclosing decompilation.
1.4	Bugfix release. array-length instruction parsing bug fixed.
1.3	Bugfix release. Classes with no superclass (java.lang.Object) are correctly disassembled.
1.2	Bugfix release.
1.1	ODEX support, debug info parsing (line numbers, local variables)
1.0	Initial version.