Skip to content New Self-host your password sync in 15 minutes Read more Menu Download OpenVireo

The core for the JVM and Android: accounts, vaults, sync, share links and .kdbx files, on the same Rust code as the iOS, desktop and web apps. UniFFI generates the Kotlin API (package com.openvireo.core) from bindings/ov-ffi, and JNA loads it. The artifact also has:

  • ready-made Host parts (com.openvireo.core.hosts), so a program needs no glue;
  • a Java API without coroutines (com.openvireo.core.java), where every suspend method returns a CompletableFuture.
ArtifactForNatives
com.openvireo:openvireo-core-jvmKotlin and Java 11+ on macOS, Linux and Windowsdarwin-aarch64, darwin-x86-64, linux-x86-64, linux-aarch64, win32-x86-64 in the jar; JNA picks the right one
com.openvireo:openvireo-core-androidAndroid 8.0+ (minSdk 26)libov_ffi.so for arm64-v8a, armeabi-v7a, x86_64

Both depend on JNA 5 and kotlinx-coroutines-core. The version is the core’s version. The build and developer notes are in bindings/kotlin.

Install

The artifacts are on GitHub Packages. GitHub Packages asks for a token even for public packages, so every consumer needs a GitHub personal access token (classic) with the read:packages scope. This goes away once the artifacts are on Maven Central.

Keep the token out of the build file. Put it in ~/.gradle/gradle.properties:

gpr.user=your-github-login
gpr.key=ghp_...

Gradle (settings.gradle.kts or build.gradle.kts):

repositories {
    mavenCentral()
    maven {
        url = uri("https://maven.pkg.github.com/openvireo/openvireo-core")
        credentials {
            username = providers.gradleProperty("gpr.user").orElse(providers.environmentVariable("GITHUB_ACTOR")).get()
            password = providers.gradleProperty("gpr.key").orElse(providers.environmentVariable("GITHUB_TOKEN")).get()
        }
    }
}

dependencies {
    implementation("com.openvireo:openvireo-core-jvm:X.Y.Z")      // or openvireo-core-android
}

In GitHub Actions, give the job permissions: packages: read. If GITHUB_TOKEN is still refused (401 or 403), use a PAT stored as a secret instead.

Maven: add the token to ~/.m2/settings.xml:

<settings>
  <servers>
    <server>
      <id>openvireo</id>
      <username>your-github-login</username>
      <password>ghp_...</password>
    </server>
  </servers>
</settings>

and the repository and dependency to pom.xml. The <id> must match:

<repositories>
  <repository>
    <id>openvireo</id>
    <url>https://maven.pkg.github.com/openvireo/openvireo-core</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>com.openvireo</groupId>
    <artifactId>openvireo-core-jvm</artifactId>
    <version>X.Y.Z</version>
  </dependency>
</dependencies>

Kotlin

Every call that touches the network or storage is a suspend function and takes a CancelToken. Local work is synchronous: reading and editing an open vault, and the crypto functions.

import com.openvireo.core.*
import com.openvireo.core.hosts.defaultHost
import kotlinx.coroutines.runBlocking
import java.nio.file.Path

fun main() = runBlocking {
    val client = OvClient(
        ClientConfig(DeviceInfo(id = null, name = "backup tool", platform = Platform.CLI), offline = false, server = null),
        defaultHost(cacheDir = Path.of("ov-cache")),
    )
    val account = signIn(client, "[email protected]", ask("Master password: ").toByteArray())

    for (info in account.vaults(CancelToken())) {
        val vault = account.openVault(info.id, CancelToken())
        for (entry in vault.entries(false)) {          // false: leave out the Recycle Bin
            println("${info.name} / ${entry.groupPath.joinToString("/")} ${entry.title} ${entry.username}")
        }
    }
}
  • DeviceInfo.name is what the account’s device list shows. Programs on the JVM use Platform.CLI.
  • offline = true keeps the offline cache: unlock, list and open vaults without the network, and keep edits until they upload. It needs a persistent BlobCache (defaultHost(cacheDir = ...)).
  • server is a discovery document to use instead of fetching one. Leave it null.
  • Every generated object is AutoCloseable: close() (or use { }) frees its native handle now instead of when it is garbage-collected.

Sign in

suspend fun signIn(client: OvClient, email: String, password: ByteArray): Account {
    val account = client.connect("https://accounts.openvireo.com", CancelToken())
    if (account.isSignedIn()) {
        // A stored session (persistent SecureStore): unlock it, no OPAQUE round trip.
        account.unlock(password, null, CancelToken())
        return account
    }

    val input = LoginInput(email, password, secretKey = null, totp = null, trustDevice = true)
    var step = try {
        account.login(input, CancelToken())
    } catch (e: OvException) {
        if (e.code != OvErrorCode.INVALID_SECRET_KEY) throw e
        // A new device: the Secret Key isn't stored here yet.
        account.login(input.copy(secretKey = ask("Secret Key: ").toByteArray()), CancelToken())
    }

    while (step is LoginStep.NeedsTotp) {
        step = try {
            account.submitTotp(step.challenge, ask("Two-step code: "), CancelToken())
        } catch (e: OvException) {
            if (e.code != OvErrorCode.INVALID_MFA) throw e   // mfa_expired: start again
            step
        }
    }
    return account
}

ask stands for however your program prompts (print(prompt); readln()).

  • connect fetches the server’s discovery document and loads a stored session if there is one. The account is then signed in but locked, and unlock opens it with the master password.
  • A device that has never seen the account doesn’t have the Secret Key. login without one fails with invalid_secret_key. Ask for the key and try again. With trustDevice = true the core keeps it in the SecureStore.
  • A wrong password, or an email with no account, is unauthorized. A wrong Secret Key is also unauthorized, with details {"reason": "keyset_unwrap_failed"} instead of "opaque_refused".
  • Two-step sign-in returns LoginStep.NeedsTotp. A wrong code is invalid_mfa and the same challenge takes another (challenge.attempt() counts the tries). After the fifth wrong code, or once the challenge expires, the result is mfa_expired and the sign-in starts again.
  • account.signOut(forgetDevice, CancelToken()) ends the session and deletes the offline cache, including edits that haven’t synced.

Add an entry, sync, share

val vault = account.openVault(vaultId, CancelToken())
val entryId = vault.addEntry(
    vault.ensureGroup("Servers/Prod"),                 // or vault.rootGroupId()
    EntryInput(
        fields = listOf(
            FieldInput("Title", "Router".toByteArray(), null),
            FieldInput("UserName", "admin".toByteArray(), null),
            FieldInput("Password", "correct horse".toByteArray(), null),
        ),
        removeFields = emptyList(),
        tags = null,
        iconId = null,
        expiry = EntryExpiry.Keep,
    ),
)
val report = vault.sync(SyncOptions(localChanged = true), CancelToken())

val payload = itemSharePayload(vault.entry(entryId), defaultShareFields(), null)
val share = account.createShare(payload, ShareOptions(3600u, 1u, null, vault.id(), entryId), CancelToken())
println(share.url.decodeToString())
  • Edits stay in the local copy until sync. localChanged = true uploads them, after merging in what other devices uploaded. localChanged = false only pulls.
  • entry(id) gives the full record. Field values are ByteArray (UTF-8 for text). find("ov://Vault/Group/Title") and readField("ov://Vault/Group/Title/Password") look an entry or a field up by reference.
  • share.url is a ByteArray, because it holds the link’s key. To open a link without an account, call client.shareInfo(api, parseShareLink(link).id, ...), then client.openShare(api, link, null, info, ...), where api is account.serverConfig().api.

Errors

Everything throws OvException. It has one variant, OvException.Failure, and extensions in com.openvireo.core read its fields without a cast:

try {
    account.login(input, CancelToken())
} catch (e: OvException) {
    when (e.code) {
        OvErrorCode.UNAUTHORIZED -> println("wrong email, password or Secret Key")
        OvErrorCode.NETWORK_ERROR -> println("offline: ${e.errorMessage}")
        OvErrorCode.RATE_LIMITED -> println("try again in ${e.retryAfter}s")
        else -> println("${e.wireCode} (${e.status}): ${e.errorMessage}")
    }
}
Field
codean OvErrorCode
wireCodethe stable string ("unauthorized"). It’s the server’s own code when that isn’t one of OvErrorCode.
errorMessageEnglish text for logs. e.message is a summary of every field.
statusthe HTTP status (Int?)
retryAfterseconds (Long?), for RATE_LIMITED
(e as OvException.Failure).detailsa JSON object string with camelCase keys
(e as OvException.Failure).serverCodethe server’s code when it isn’t one of OvErrorCode

The codes are the TypeScript SDK’s, one for one, plus internal. The SDK’s error list says what each one means.

Coroutines and cancellation

  • Call the suspend functions from any coroutine and any dispatcher. They don’t block the calling thread.
  • Cancelling the calling coroutine drops the core’s future, and with it the Host call in progress. The coroutine gets a CancellationException.
  • A CancelToken: calling cancel() from any thread makes every call that holds the token fail with OvException code ABORTED. One token can be shared by several calls. Once cancelled, a token stays cancelled.
  • The synchronous functions do CPU work in the core. For a big vault, call them off the main thread.

Names that differ from Swift

Every generated object is AutoCloseable (close() frees the handle), and exceptions are Throwables, which already have a message. So a few members have other names in Kotlin and Java:

Swift / PythonKotlin and Java
EventStream.close()EventStream.closeStream()
ByteStream.close() (a Host stream)ByteStream.closeStream()
ServiceAccount.close()ServiceAccount.endSession()
OvError.Failure.messageOvException.Failure.errorMessage
TransportError.Tls/Other.messageTransportException.Tls/Other.reason

close() on those objects frees the native handle. It doesn’t end the stream or the session.

Java

com.openvireo.core.java is the whole API for Java. It’s in the same jar and AAR.

import com.openvireo.core.*;
import com.openvireo.core.java.*;
import java.nio.charset.StandardCharsets;
import java.nio.file.Path;
import java.util.List;
import java.util.concurrent.CompletionException;

JOvClient client = new JOvClient(
    new ClientConfig(new DeviceInfo(null, "backup tool", Platform.CLI), false, null),
    JDefaultHosts.create(Path.of("ov-cache")));
JAccount account = client.connect("https://accounts.openvireo.com").join();

LoginInput input = new LoginInput(email, password, null, null, true);
LoginStep step;
try {
    step = account.login(input).join();
} catch (CompletionException e) {
    if (JErrors.code(e) != OvErrorCode.INVALID_SECRET_KEY) throw e;
    input.setSecretKey(askSecretKey());
    step = account.login(input).join();
}
while (step instanceof LoginStep.NeedsTotp) {
    JTotpChallenge challenge = new JTotpChallenge(((LoginStep.NeedsTotp) step).getChallenge());
    step = account.submitTotp(challenge, askCode()).join();
}

for (VaultInfo info : account.vaults().join()) {
    JVault vault = account.openVault(info.getId()).join();
    for (EntrySummary entry : vault.entries(false)) {
        System.out.println(info.getName() + " / " + entry.getTitle() + " " + entry.getUsername());
    }
}

JVault vault = account.openVault(vaultId).join();
List<FieldInput> fields = List.of(
    new FieldInput("Title", "Router".getBytes(StandardCharsets.UTF_8), null),
    new FieldInput("Password", "correct horse".getBytes(StandardCharsets.UTF_8), null));
String entryId = vault.addEntry(vault.rootGroupId(),
    JRecords.newEntryInput(fields, List.of(), null, null, EntryExpiry.Keep.INSTANCE));
vault.sync(new SyncOptions(true, false)).join();

SharePayload payload = JOv.itemSharePayload(vault.entry(entryId), JOv.defaultShareFields(), null);
CreatedShare share = account.createShare(payload,
    JRecords.newShareOptions(3600L, 1L, null, vault.id(), entryId)).join();
  • Wrappers. JOvClient, JAccount, JVault, JServiceAccount, JSelfHosted, JEventStream and JTotpChallenge wrap the generated objects. Objects come back wrapped. To wrap one you got from a record, use new JTotpChallenge(step.getChallenge()). unwrap() gives the generated object, and close() frees it. Records, enums, CancelToken and Host are the generated types and need no wrapper.
  • Futures. Each suspend method returns CompletableFuture<T> (CompletableFuture<Void> when there’s no result). Synchronous methods are plain calls and declare throws OvException where the core can fail.
  • No CancelToken needed. Each method that takes a CancelToken has an overload without it. future.cancel(true) then cancels the call: the coroutine, the core’s future and the Host call in progress. Pass a token to cancel several calls together, and they fail with ABORTED.
  • JOv has every free function as a static: the crypto primitives, share links, TOTP, OPAQUE, and the wire codes.
  • Unsigned numbers. Kotlin hides constructors and getters that use unsigned types from Java. In Java they become the next wider signed type (UInt becomes long, UShort becomes int), and values going in are range-checked. Records that have unsigned fields are built with JRecords.new<Record>(...) and read with JRecords.get<Field>(record), for example JRecords.newShareOptions(3600L, 2L, null, null, null), JRecords.newKdfOverrides(19456L, 2L, 1L) and JRecords.getOpensLeft(info).
  • Records with defaults need every argument from Java: new SyncOptions(true, false).

Errors in Java

A future fails with OvException. join() wraps it in CompletionException, and get() in ExecutionException. JErrors unwraps either one and returns null for any other exception:

try {
    account.login(input).join();
} catch (CompletionException e) {
    OvErrorCode code = JErrors.code(e);
    if (code == OvErrorCode.UNAUTHORIZED) {
        System.out.println("wrong email, password or Secret Key");
    } else if (code == null) {
        throw e;                                   // not from the core
    } else {
        System.out.println(JErrors.wireCode(e) + " " + JErrors.status(e) + ": " + JErrors.errorMessage(e));
    }
}

JErrors also has retryAfter, details, serverCode and ovException(e).

Threads

Futures run on JScope.defaultScope(), a SupervisorJob on Dispatchers.Default. Each wrapper constructor also takes an Executor (or a CoroutineScope), and objects it returns use the same one:

JOvClient client = new JOvClient(config, host, Executors.newFixedThreadPool(4));

Don’t call join() inside a Host part. The part runs on the core’s threads, and blocking there can deadlock.

The Host

The core never opens a socket or a file, reads the clock or touches a keychain. It calls a Host made of five parts, and defaultHost(...) (Kotlin) or JDefaultHosts (Java) fills in all of them:

PartJVM defaultAndroid defaultOthers shipped
HttpTransportJavaNetHttpTransportUrlConnectionTransportUrlConnectionTransport on the JVM
SecureStoreMemoryStoreMemoryStorenone
BlobCacheFileCache(cacheDir), or MemoryCache without a directoryFileCache(noBackupFilesDir/openvireo-cache)MemoryCache
ClockSystemClockSystemClock
LogSinkJulLogSink (java.util.logging, loggers openvireo.<module>)AndroidLogSink (logcat, tag OpenVireo)
defaultHost(cacheDir = Path.of("ov-cache"), store = MyKeychainStore())          // Kotlin, JVM
Host host = JDefaultHosts.builder().store(myKeychainStore).cache(new FileCache(Path.of("ov-cache"))).build();

MemoryStore keeps nothing between runs, so each run is a new device: it signs in from scratch and needs the Secret Key. To keep sessions and trusted Secret Keys, write a SecureStore over the OS keychain, or over the Android Keystore on Android. No keychain store ships yet.

The cache holds only ciphertext and public data (vault blobs encrypted under the vault key, the wrapped keyset, the discovery document).

Transports

  • JavaNetHttpTransport (JVM only) is built on java.net.http.HttpClient. It’s fully async and streams the server’s events. Its client is built with Redirect.NEVER and no CookieHandler. If you pass your own HttpClient (for a proxy or custom TLS), build it the same way, or the constructor refuses it. requestTimeout (60 s) bounds the wait for response headers.
  • UrlConnectionTransport is built on HttpURLConnection and runs on Dispatchers.IO. It works everywhere, but has two caveats on the desktop JVM:
    • The JVM’s own HttpURLConnection can’t send PATCH, and the core uses PATCH to rename organisations, vaults and service accounts. Those calls fail with TransportException.Other. Android’s HttpURLConnection (OkHttp underneath) sends PATCH.
    • HttpURLConnection always uses the process-wide CookieHandler. If anything in the process calls CookieHandler.setDefault(...), this transport sends and stores cookies, which the core’s contract forbids. Use JavaNetHttpTransport in such a process.

Writing a part

In Kotlin, implement the generated interfaces (HttpTransport, SecureStore, BlobCache with suspend methods; Clock and LogSink plain). In Java, implement JHttpTransport, JSecureStore and JBlobCache, which return futures, and build the Host with JHosts.create(http, store, cache, clock, log) or JHosts.builder(). Clock and LogSink are functional interfaces, so lambdas work:

Host host = JHosts.create(myTransport, myStore, myCache, System::currentTimeMillis, (level, target, msg) -> {});

JHosts.fromKotlin(new JavaNetHttpTransport()) turns a shipped Kotlin part into its Java interface, so you can decorate it.

The rules:

  • Threads. The core calls Host parts from its own threads, in coroutines on Dispatchers.Default. Do blocking I/O inside withContext(Dispatchers.IO) { ... } in Kotlin, or complete the future from your own executor in Java. Never block a Dispatchers.Default thread.
  • A transport must not follow redirects, must not store or send cookies, must send the core’s headers as given, and must return every HTTP status as a response. It throws TransportException (Offline, Timeout, Tls(reason), Other(reason)) only when there’s no response.
  • A store or cache returns null for a missing key. When it can’t read or write, it throws ovException(OvErrorCode.INTERNAL, "why") (Kotlin, com.openvireo.core.hosts), or completes the future with JErrors.ovException(code, message) (Java).
  • Anything else thrown reaches the core as a network error (from a transport) or internal.
  • Never log request headers: they carry bearer tokens.

Android

dependencies {
    implementation("com.openvireo:openvireo-core-android:X.Y.Z")
}
import com.openvireo.core.*
import com.openvireo.core.hosts.defaultHost

val client = OvClient(
    ClientConfig(DeviceInfo(id = null, name = Build.MODEL, platform = Platform.ANDROID), offline = true, server = null),
    defaultHost(applicationContext),
)

From Java: new JOvClient(config, JDefaultHosts.create(context)).

  • Call the suspend functions from lifecycleScope or viewModelScope. They never block the main thread. Keep the synchronous ones, such as Vault.entries on a big vault, off the main thread.

  • The app needs the INTERNET permission.

  • Cache location. defaultHost(context) puts the offline cache in noBackupFilesDir/openvireo-cache. That directory is app-private and not backed up, and the system doesn’t clear it. Don’t use context.cacheDir: the system clears it when storage is low, which drops the offline copy and any edits not yet synced. Pass cacheDir = to choose another directory.

  • ABIs. The AAR has the core for arm64-v8a, armeabi-v7a and x86_64. JNA’s AAR also brings armeabi, x86, mips and mips64. Limit the app to the three ABIs, or it installs on an x86 device (an old emulator) and fails when the core loads:

    android {
        defaultConfig {
            ndk { abiFilters += listOf("arm64-v8a", "armeabi-v7a", "x86_64") }
        }
    }
    
  • R8 / ProGuard. JNA finds native methods, structures and callbacks by reflection. The AAR ships consumer rules that keep com.sun.jna.** and com.openvireo.core.**, and they apply automatically. You don’t need to add anything.

  • Size. About 1.5 to 1.8 MiB of compressed native code per ABI. A Play Store app bundle delivers one ABI per device. The build notes have the measurements.

Secrets

Passwords, Secret Keys and field values cross into the JVM as ByteArray, and Kotlin Strings you make from them can’t be wiped at all. The core zeroizes its own copies. The JVM can’t guarantee that for yours: call fill(0) (Arrays.fill(a, (byte) 0)) on arrays you no longer need, and avoid turning secrets into Strings. Records’ toString() prints their fields, so don’t log records that hold secrets.

Self-hosted servers

  • Your own account server: pass its issuer URL to connect. It must be https://. Loopback (http://localhost:8000) is the one exception, and any other http:// URL fails with insecure_url.
  • A standalone sync server (paired devices, no account): SelfHosted.pair(client, url, code, deviceName, CancelToken()), later restoreSelfHosted(client, url), then syncDatabase(id, kdbxBytes, credentials, CancelToken()). In Java, use JSelfHosted.pair(...) and JOv.restoreSelfHosted(...). The pairing token is kept in the SecureStore and the sync state in the BlobCache, so both must persist.
  • Service accounts (ov_sa_... tokens): ServiceAccount.fromToken(client, token, CancelToken()) (JServiceAccount.fromToken in Java). Then vaults, read("ov://Vault/Entry/Field"), write and inject. endSession() wipes its keys and cached vaults from memory, and later calls fail with signed_out.

The examples are tested

DocsSamplesTest (Kotlin) and JavaDocsSamplesTest (Java) in bindings/kotlin/core-jvm/src/test run the samples on this page against the in-memory servers (cargo xtask kotlin --smoke).

The Core bindings docs cover OpenVireo core, develop (bcbf55a), last updated 21 November 2026. Found a mistake? Edit this page on GitHub.