oe-java
A reference project that shows how to call Open Enclave enclaves from a Java application through a JNI bridge. It bundles a sample enclave, host-side glue, and a Gradle-based app so you can experiment end-to-end with ECALL/OCALL flows from the JVM.
Quickstart
Generate JNI headers with Gradle (required before the C++ build):
./gradlew compileJava
Configure CMake and build the native artifacts (enclave + JNI host library):
cmake --preset default
cmake --build --preset default
This produces build/lib/liboe_jni.{so|dylib|dll} and signs the sample enclave into build/artifacts/enclaves/example/example.signed.
Update app/src/main/java/org/oejava/example/App.java so the hard-coded path passed to ExampleEnclave.create() points at the signed enclave generated above, then run the Java sample:
./gradlew run
Gradle sets java.library.path to build/lib, so the JVM picks up liboe_jni automatically. Use the --simulate flag when building/running the native host if you do not have SGX hardware available.
Repository layout
app/ – Gradle project with the Java example (App) and the JNI stub class (ExampleEnclave).
enclaves/example/ – The sample enclave (EDL file, trusted implementation, signing config).
host/ – JNI bridge (jni_bridge.cpp), OCALL implementations, and an optional CLI host (host.cpp).
cmake/OEEnclave.cmake – Helper function add_oe_enclave() that drives oeedger8r, enclave compilation, and signing.
scripts/ – Convenience scripts, including check_sgx.sh (hardware capability probe) and devcontainer helpers.
.devcontainer/ – Docker setup for a reproducible development environment with OE, JDK 21, CMake, and tooling pre-installed.
Generated output lives under build/ (CMake) and app/build/ (Gradle).
Prerequisites
- Open Enclave SDK 0.19.x or newer (provides
oeedger8r, oehost, oesign, headers, and libraries).
- CMake ≥ 3.20, Clang/LLVM ≥ 11, and
ninja or Make (the presets use Unix Makefiles by default).
- JDK 21 (managed automatically if you rely on the Gradle toolchain) and Gradle wrapper (
./gradlew).
- SGX2-capable hardware + drivers for a hardware-backed run, or use OE's simulation mode.
- Optional: Docker if you prefer the supplied devcontainer (
scripts/devcontainer-*.sh).
Check SGX support quickly with:
scripts/check_sgx.sh
Building the native side
./gradlew compileJava emits JNI headers under build/generated/jni/. Rerun this whenever you change ExampleEnclave.java.
cmake --preset default configures the project with BUILD_JNI_HOST=ON and BUILD_HOST_EXE=OFF.
cmake --build --preset default compiles the enclave, generates all EDL stubs, builds liboe_jni, and signs the enclave. Use cmake --build --preset default --target sign_all if you only need to re-sign after editing .conf files.
Enable the tiny CLI host for debugging by configuring with the test preset or passing -DBUILD_HOST_EXE=ON, then run it against the signed enclave:
cmake --preset test
cmake --build --preset test --target oe_cli
./build/bin/oe_cli --simulate build/artifacts/enclaves/example/example.signed
Omit --simulate when running on hardware with SGX enabled.
Running and testing the Java layer
After wiring the enclave path, ./gradlew run launches org.oejava.example.App, which creates the enclave, performs the helloworld ECALL, and tears it down.
Unit tests (currently a placeholder) run via:
./gradlew test
If you run outside Gradle, set java.library.path (or LD_LIBRARY_PATH/DYLD_LIBRARY_PATH) so the JVM can load liboe_jni, and make sure the signed enclave is accessible to the host process.
Devcontainer workflow
Edit .devcontainer.env (create it if needed) and set SSH_PUBKEY to the public key you want inside the container.
Bring the container up:
./scripts/devcontainer-up.sh
The image ships with the Open Enclave SDK, JDK 21, CMake, Neovim, and other tooling. Additional helpers in scripts/ can attach, stop, or tear down the container.
Tips & next steps
- When adding new enclaves, create a directory under
enclaves/ and call add_oe_enclave() in its CMakeLists.txt; the helper aggregates all generated untrusted stubs for the host.
- JNI signatures live in
build/generated/jni. Keep Gradle and CMake builds in sync so regenerated headers are picked up.
- Use OE's simulation mode (
OE_ENCLAVE_FLAG_SIMULATE) while iterating on machines without SGX, then rebuild with debug=false for production.
- Clean builds with
rm -rf build app/build or invoke cmake --build --preset default --target clean and ./gradlew clean.