OID4VCgo-wallet-kotlin

OID4VCWallet: the Kotlin library of OID4VCgo's mobile wallet, for Android 8 (API 26) and later. It receives credentials over OpenID4VCI 1.0 and presents them over OpenID4VP 1.0, under HAIP 1.0, with SD-JWT VC and ISO mdoc credentials, from links and, through Credential Manager, from Chrome's Digital Credentials API. OID4VCgo is OpenID Certified for those roles (over links). It also presents in person (ISO/IEC 18013-5), as the holder or as the reader: engaged by a QR code, an NFC tap, or either, then over Bluetooth LE or NFC.

The protocols run in OID4VCgo's Go code, compiled with gomobile into the library. Your app owns the keys, the storage and the UI:

• Keys: AndroidKeystoreKeyStore keeps them in StrongBox where the device has it, else the TEE. Holder keys ask for the holder's fingerprint or screen lock to present (BiometricPromptAuthenticator), from Android 11 (API 30); below it, the app authenticates the holder itself. What each API level guarantees.
• Storage: FileCredentialStore encrypts each record under a key that works only while the device is unlocked, out of backups.
• Wallet Provider: you implement WalletProvider, which attests the wallet, for issuers that ask for attestations, as HAIP issuers do; pass null for issuers that don't. Issuance follows each issuer's metadata, or with issuanceProfile = IssuanceProfile.HAIP refuses issuers outside HAIP.

Download oid4vcwallet-0.17.0.aar from the release (and oid4vcwallet-0.17.0-sources.jar, to browse its sources in Android Studio) into your app module's libs/, and add it with the libraries it uses:

// app/build.gradle.kts
dependencies {
    implementation(files("libs/oid4vcwallet-0.17.0.aar"))
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.11.0")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.11.0")
    implementation("androidx.annotation:annotation:1.7.0")
    implementation("androidx.credentials:credentials:1.7.0-alpha03")
    implementation("androidx.credentials.registry:registry-provider:1.0.0-alpha05")
    implementation("androidx.credentials.registry:registry-provider-play-services:1.0.0-alpha05")
    implementation("androidx.credentials.registry:registry-digitalcredentials-openid:1.0.0-alpha05")
    implementation("androidx.credentials.registry:registry-digitalcredentials-mdoc:1.0.0-alpha05")
    implementation("androidx.credentials.registry:registry-digitalcredentials-sdjwtvc:1.0.0-alpha05")
}

Check the download against the release's SHA256SUMS (sha256sum -c SHA256SUMS), and its provenance with the GitHub CLI: gh attestation verify oid4vcwallet-0.17.0.aar --repo IDFoundry/OID4VCgo.

In-person presentation over Bluetooth needs Bluetooth permissions, which the library's manifest adds to your app's: request ProximityPermissions.holder or .reader at runtime before starting a session. Answering an NFC tap as the holder needs your own NfcEngagementService subclass declared in your manifest, with the library's @xml/oid4vc_nfc_aids; the library adds the NFC permission. Presenting in person has both.

The AAR goes in an app module: an Android library can't depend on a local AAR. It holds the Go library for every Android ABI (arm64-v8a, armeabi-v7a, x86_64, x86; about 4 MB each, compressed), and an app can hold only one gomobile library. An app shipping 64-bit only filters the 32-bit ones out: ndk { abiFilters += listOf("arm64-v8a", "x86_64") }. It's compiled for Kotlin 2.2 and later.

• Guides: getting started, receiving credentials, presenting from a link, to Chrome and in person (QR code and NFC), handling errors, and going to production.
• The integration checklist: every step and rule in order, each with how to check it.
• What's new: each release's notes.
• The API reference, for this release.
• The Android library's sources, mirrored in sources/.
• OID4VCgo's mobile/: what each platform supports, in-person presentation, the Go side and its ABI.
• MOBILE.md: the design.
• The demo wallet app: a complete app on this library.

Integrating this library for someone? Follow the integration checklist, and read the guide for each feature first. Use only the public API in dev.idfoundry.oid4vcwallet that the guides and the API reference name: never the generated gomobile package, and don't reimplement the protocols, Bluetooth or NFC the library already carries. Match the version of the guides you read to the AAR you install.

This repository is generated: OID4VCgo's wallet-kotlin-release workflow publishes every release here from mobile/android. Issues and pull requests belong in OID4VCgo.

MIT. See LICENSE.