Running the OpenTDF Java SDK on Android

[arkavo-com]

We just shipped our app's Android client on top of the OpenTDF Java SDK (io.opentdf.platform:sdk 0.15.0). Content is encrypted to standard (ZIP/Archive) TDF on the device — same wire format on iOS and Android, so a TDF created on one decrypts on the other. The Java SDK isn't officially marketed as an Android target, but with a few build-side accommodations it works end-to-end on a real device against an OpenTDF platform deployment.

Sharing the notes that weren't obvious from the README, in case they help anyone else.

What worked out of the box

• SDKBuilder.newBuilder().platformEndpoint(...).clientSecret(id, secret).useInsecurePlaintextConnection(dev).build() — same setup as a JVM client.
• sdk.createTDF(InputStream, OutputStream, TDFConfig) for encryption — output is real standard TDF (ZIP local-file-header magic PK\x03\x04 is the round-trip canary).
• KAS rewrap, OIDC token acquisition against Keycloak, attribute resolution — all handled inside the SDK; no need for the bespoke KasClient / OauthTokenSource we had on 0.7.5.

The four Android-specific things we had to do

1. Strip server-side transitive deps. The 0.15.0 POM pulls a JVM-server toolchain that won't dex (or duplicates Firebase's google common protos). Our implementation(libs.opentdf.sdk) exclusion block:

exclude(group = "io.grpc", module = "grpc-netty-shaded")           // ~25 MB; SDK uses ConnectRPC/OkHttp on the client side
exclude(group = "build.buf", module = "protovalidate")             // pulls cel + duplicate com.google.api.* classes
exclude(group = "org.projectnessie.cel")
exclude(group = "org.apache.logging.log4j")                        // JNDI lookups fail to dex
exclude(group = "org.apache.tomcat", module = "annotations-api")

Important: keep com.google.api.grpc:proto-google-common-protos. The SDK needs it at runtime to deserialize RewrapResponse — we excluded it once and got cryptic failures inside rewrap.

Also packaging.resources.excludes for duplicate BouncyCastle OSGI manifests:

META-INF/versions/*/OSGI-INF/MANIFEST.MF

2. Kotlin metadata version skew. The SDK jar ships Kotlin 2.1 metadata even though its public API is Java. Our Compose build is on 1.9.x. Fix:

freeCompilerArgs += listOf("-Xskip-metadata-version-check")

The 2.1 stdlib it pulls in is binary-compatible; this just silences the compile-time metadata-version assertion.

3. TDF.Reader is package-private. SDK.loadTDF(...) returns a TDF.Reader, but the enclosing io.opentdf.platform.sdk.TDF class isn't exported. From Kotlin you can't even name the return type without it being public. We solved it with a 25-line same-package Java shim:

package io.opentdf.platform.sdk;

public final class TdfDecryptBridge {
    public static byte[] readPayload(SDK sdk, SeekableByteChannel channel, Config.TDFReaderConfig config)
            throws IOException {
        TDF.Reader reader = sdk.loadTDF(channel, config);
        ByteArrayOutputStream out = new ByteArrayOutputStream();
        reader.readPayload(out);
        return out.toByteArray();
    }
}

Would be nice to have byte[] SDK.decrypt(SeekableByteChannel, TDFReaderConfig) or to make TDF.Reader public — happy to PR if there's appetite.

4. In-memory SeekableByteChannel for decrypt. loadTDF needs seekable input (standard TDF is a ZIP). On mobile we don't want to spill the ciphertext to disk just to read it. A ~30-line read-only ByteArraySeekableByteChannel over a ByteArray is enough — position(), read(ByteBuffer), size(), and throw on write/truncate.

Recipient encoding (attribute-based access control on a mobile client)

The interesting product question: how do you express "Alice and Bob can read this" without putting their emails in the TDF manifest? We use a single attribute namespace and, per recipient, an attribute value that is the SHA-256 of email.lowercase().trim():

fqn = "${namespace}/value/${sha256(email).hex}"

Then Config.withDataAttributes(*fqns) at encrypt time. The platform-side subject mapping has to hash the incoming Keycloak email claim the same way before matching — that's the only contract. We pinned the transform with a known SHA-256 vector in a unit test, because changing it after release would silently de-entitle every existing artifact.

Release-parity guards

Because the dev defaults (opentdf/secret, http://localhost:8080, plaintext) are baked into BuildConfig for ergonomic local dev, we added a Gradle task that fails assembleRelease if any of them survive into a release build. The exact dev secret is in the public README, so leaking it into an APK would be embarrassing.

Limitations / open questions

• We deliberately dropped NanoTDF (removed from the SDK at 0.12.0). Standard TDF gives iOS↔Android parity, which is what we needed anyway.
• We haven't yet measured cold-start cost of the BouncyCastle init on lower-end devices.
• The package-private TDF.Reader is the only sharp edge left — would prefer not to keep the bridge if there's a sanctioned API.

Happy to share the full build.gradle.kts exclusions block or the TdfDecryptBridge shim if anyone wants to lift them.