keystone-engine-keystone/bindings/java/README.md

Java bindings for Keystone

Java bindings for the Keystone engine. Require JDK 10+.

Sample

    import keystone.Keystone;
    import keystone.KeystoneArchitecture;
    import keystone.KeystoneMode;
    import keystone.exceptions.AssembleFailedKeystoneException;
    
    public class App {
    
        public static void main(String[] args) {
            try (Keystone keystone = new Keystone(KeystoneArchitecture.X86, KeystoneMode.Mode32)) {
                try {
                    var result = keystone.assemble("INC ecx; DEC edx");
    
                    System.out.println("Number of statements encoded: " + result.getNumberOfStatements());
                    System.out.println("Base address: " + String.format("0x%08X", result.getAddress()));
                    System.out.print("Encoded bytes: ");
    
                    for (byte b: result.getMachineCode()) {
                        System.out.print(String.format("%X ", b));
                    }
    
                } catch (AssembleFailedKeystoneException e) {
                    System.out.println(e.getMessage());
                }
            }
        }
    }

Output:

Number of statements encoded: 2
Base address: 0x00000000
Encoded bytes: 41 4A

Other samples are provided by the unit tests included with the library, which cover most of the code.

Getting Started

1. Clone the repository locally.
2. Download or compile Keystone library and store it in the folder src/main/resources/{os-prefix}/{keystone-lib}, according the specifications of JNA, or the related unit test.
3. Compile the Java bindings and issue the JAR using Maven mvn package. The unit tests are automatically while running the goal.
4. In your project, include target/binding-java-{version}.jar and JNA using your favourite dependency manager, or include target/binding-java-{version}-jar-with-dependencies.jar that is packaged with JNA.

Exception handling

Each operation that returns the native enumeration ks_err is wrapped in an instance of a subclass of KeystoneException, thrown when an error occurs. The Javadoc indicates the exceptions thrown by the Java bindings for Keystone.

Garbage collection

Keystone library requires to open and close an handle, that must be collected once an instance of the class Keystone is disposed. For that purpose, the class implements the interface AutoCloseable. Nonetheless, the Java bindings also implement a cleaning mechanism that automatically collects the handle when the instance of the class is phantom reachable, meaning no memory leak can happen, even if the instance is not closed properly.

Native function calls

The Java bindings for Keystone rely on JNA Direct Mapping to improve the performances of native calls, approaching that of custom JNI.

Found an issue or bug ?

Feel free to open a GitHub issue on the official repository of Keystone and ping the contributors.

Contributors

Author: Jämes Ménétrey (@ZenLulz)

Maintainers:

• Need some people here :) Feel free to contribute !

Want to contribute ?

Hey you! Your help is more than welcome! Things to keep in mind when working on the Java bindings for Keystone:

• Think about the backward compatibility; while code refactoring is a good practice, changing entirely the API may result in struggles.
• Elaborate the unit tests that prove your code is working. Test all the paths of the newly-added functions/classes (IntelliJ can show some metrics using Coverage). Keep the code coverage high!
• Please; write the required Javadoc, so every developer has the chance to understand your code.
• Update the changelog with a summary of your changes.

Version notation

The version of the Java bindings for Keystone is indicated in the file Maven configuration file (pom.xml). The major, minor and incremental versions (w.x.y) match the version of the library Keystone that the bindings is developed with. The build number (the -z in w.x.y-z) is incremented for each newer version of the Java bindings. Please, don't forget to increment this version when you submit a pull request.

On the last commit for a pull request, please create a tag called java-bindings-w.x.y-z.

Pull request submission

Ping the contributors of the Java bindings when submitting a pull request, so your changes can be peer reviewed.

License

The Java bindings for Keystone is open-sourced software licensed under the MIT license. The license of the library Keystone may be different and is available at the root of the repository of Keystone.