Skip to main content
Version: v0.25.0 (Latest)

Platform Setup

Platform-specific configuration on top of the base Installation. Most IDK modules work out of the box everywhere, but BLE, NFC, and secure key storage need extra setup.

Android​

Gradle Configuration​

app/build.gradle.kts
android {
    compileSdk = 35

    defaultConfig {
        minSdk = 27
        targetSdk = 35
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = "17"
    }
}

Bluetooth Low Energy (BLE)​

Required for mDoc proximity presentation over Bluetooth.

Add permissions to AndroidManifest.xml:

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<uses-feature android:name="android.hardware.bluetooth_le" android:required="false" />

NFC with Host Card Emulation (HCE)​

Required for mDoc presentation via NFC tap.

Add permissions and register the HCE service in AndroidManifest.xml:

<uses-permission android:name="android.permission.NFC" />
<uses-feature android:name="android.hardware.nfc" android:required="false" />

<application>
    <service
        android:name="com.sphereon.mdoc.transport.nfc.MdocNfcService"
        android:exported="true"
        android:permission="android.permission.BIND_NFC_SERVICE">
        <intent-filter>
            <action android:name="android.nfc.cardemulation.action.HOST_APDU_SERVICE" />
        </intent-filter>
        <meta-data
            android:name="android.nfc.cardemulation.host_apdu_service"
            android:resource="@xml/mdoc_nfc_service" />
    </service>
</application>

Android Keystore (Mobile KMS)​

The lib-crypto-kms-provider-mobile module uses the Android Keystore for hardware-backed key storage. No additional manifest configuration is needed; the Keystore is available on all devices running API 27+.

iOS​

Bluetooth and NFC Entitlements​

Add the following to your Info.plist:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app uses Bluetooth to transfer credentials</string>

<key>NSBluetoothPeripheralUsageDescription</key>
<string>This app uses Bluetooth to transfer credentials</string>

<key>NFCReaderUsageDescription</key>
<string>This app uses NFC to present credentials</string>

<key>UIBackgroundModes</key>
<array>
    <string>bluetooth-central</string>
    <string>bluetooth-peripheral</string>
</array>

For NFC, add the NFC Tag Reader entitlement:

<key>com.apple.developer.nfc.readersession.formats</key>
<array>
    <string>TAG</string>
</array>

Secure Enclave (Mobile KMS)​

The lib-crypto-kms-provider-mobile module uses the iOS Secure Enclave for hardware-backed key storage on devices that support it (iPhone 5s and later, iPads with Touch ID or Face ID). No additional entitlements are required; the Secure Enclave is accessed through the standard Keychain Services API.

JVM​

Java Version​

The IDK requires Java 17 or later. For server applications:

build.gradle.kts
java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(17))
    }
}

Ktor​

For Ktor server integration, include the server plugin:

dependencies {
    implementation("com.sphereon.idk:ktor-server-kotlin-inject:0.25.0")
}

See the Ktor Integration guide for details.

JavaScript and WebAssembly​

IDK modules compile to both JavaScript (ES modules) and WebAssembly (wasmJs) targets, each supporting both browser and Node.js environments.

JavaScript (ES Modules)​

JavaScript targets produce ES2015 modules with TypeScript definitions. They work with standard bundlers (Webpack, Vite, esbuild) and can be consumed from TypeScript and JavaScript projects.

WebAssembly (wasmJs)​

The wasmJs target compiles to WebAssembly with a JavaScript interop layer, useful when you need better performance for cryptographic operations in the browser.

Both targets support BigInt for large number operations and generate TypeScript .d.ts files alongside the compiled output.

Node.js​

For server-side JavaScript/TypeScript applications, both the JS and wasmJs targets can be used with Node.js. This is useful for building credential verification services, REST APIs, or CLI tools in the Node.js ecosystem.

Linux Native​

The IDK compiles to Linux x64 native binaries. This target is primarily used for CLI tools and server applications that need to run without a JVM. No additional configuration is required beyond standard Kotlin/Native setup.

Next Steps​