Version: v0.13

Installation

This guide covers the installation and configuration of the Identity Development Kit (IDK) for Android, iOS, and JVM projects.

Repository Configuration

The IDK artifacts are published to the Sphereon Maven repository. Configure your build system to include this repository.

Android/kotlin
iOS/Swift

Add the Sphereon repository to your project's settings.gradle.kts or root build.gradle.kts:

repositories {
    mavenCentral()
    maven {
        url = uri("https://nexus.sphereon.com/repository/sphereon-opensource-releases/")
    }
    maven {
        url = uri("https://nexus.sphereon.com/repository/sphereon-opensource-snapshots/")
    }
}

Add the IDK Swift package to your Xcode project:

Open your project in Xcode
Select File > Add Package Dependencies
Enter the package URL: https://github.com/nicklasw/idk-swift
Select the version or branch you want to use

Alternatively, add the package to your Package.swift:

dependencies: [
    .package(url: "https://github.com/nicklasw/idk-swift", from: "0.13.0")
]

Module Dependencies

The IDK is organized into focused modules. You can include individual modules based on your needs, or use the lib-all artifact for convenience.

All-in-One Dependency

For most applications, the simplest approach is to include all modules:

Android/kotlin
iOS/Swift

dependencies {
    implementation("com.sphereon.idk:lib-all:0.13.0")
}

// The iOS package includes all modules by default
import SphereonIDK

Individual Modules

For more control over your dependency footprint, include only the modules you need:

Core and Configuration

dependencies {
    // Core APIs, configuration, and dependency injection support
    implementation("com.sphereon.idk:lib-core-api-public:0.13.0")
    implementation("com.sphereon.idk:lib-core-api-default:0.13.0")
    implementation("com.sphereon.idk:lib-conf-settings:0.13.0")

    // Core events system (optional)
    implementation("com.sphereon.idk:lib-core-events-public:0.13.0")
    implementation("com.sphereon.idk:lib-core-events-impl:0.13.0")

    // HTTP client (for REST operations)
    implementation("com.sphereon.idk:lib-data-link-http-client:0.13.0")
}

Cryptography

dependencies {
    // Core cryptographic operations (COSE, JOSE, X.509)
    implementation("com.sphereon.idk:lib-crypto-core:0.13.0")

    // Key Management Service abstraction
    implementation("com.sphereon.idk:lib-crypto-kms-common:0.13.0")

    // KMS Providers (include the ones you need)
    implementation("com.sphereon.idk:lib-crypto-kms-provider-software:0.13.0")  // Software keys
    implementation("com.sphereon.idk:lib-crypto-kms-provider-mobile:0.13.0")    // iOS/Android secure storage
    implementation("com.sphereon.idk:lib-crypto-kms-provider-aws:0.13.0")       // AWS KMS
    implementation("com.sphereon.idk:lib-crypto-kms-provider-azure:0.13.0")     // Azure Key Vault
}

Mobile Credentials (mDoc)

dependencies {
    // mDoc data models and core types
    implementation("com.sphereon.idk:lib-mdoc-core:0.13.0")

    // Engagement and transfer management
    implementation("com.sphereon.idk:lib-mdoc-datatransfer:0.13.0")

    // Transport core (shared transport abstractions)
    implementation("com.sphereon.idk:lib-mdoc-transport-core:0.13.0")

    // Transport implementations (include the ones you need)
    implementation("com.sphereon.idk:lib-mdoc-transport-ble:0.13.0")     // Bluetooth Low Energy
    implementation("com.sphereon.idk:lib-mdoc-transport-nfc:0.13.0")     // NFC
    implementation("com.sphereon.idk:lib-mdoc-transport-restapi:0.13.0") // HTTP/WebSocket
    implementation("com.sphereon.idk:lib-mdoc-transport-oid4vp:0.13.0")  // OID4VP integration

    // Reader utilities (for verifier applications)
    implementation("com.sphereon.idk:lib-mdoc-reader:0.13.0")

    // CBOR encoding/decoding
    implementation("com.sphereon.idk:lib-cbor:0.13.0")
}

OAuth 2.0

dependencies {
    // OAuth 2.0 client
    implementation("com.sphereon.idk:lib-oauth2-client-public:0.13.0")
    implementation("com.sphereon.idk:lib-oauth2-client-impl:0.13.0")

    // OAuth 2.0 server components (for server applications)
    implementation("com.sphereon.idk:lib-oauth2-server-authorization-public:0.13.0")
    implementation("com.sphereon.idk:lib-oauth2-server-authorization-impl:0.13.0")
    implementation("com.sphereon.idk:lib-oauth2-server-resource-public:0.13.0")
    implementation("com.sphereon.idk:lib-oauth2-server-resource-impl:0.13.0")

    // JWT Validation (for validating access tokens)
    implementation("com.sphereon.idk:lib-oauth2-jwt-validation-api:0.13.0")
    implementation("com.sphereon.idk:lib-oauth2-jwt-validation-impl:0.13.0")
}

OpenID4VP

dependencies {
    // Common OID4VP types
    implementation("com.sphereon.idk:lib-openid-oid4vp-common-public:0.13.0")
    implementation("com.sphereon.idk:lib-openid-oid4vp-common-impl:0.13.0")

    // Holder/wallet implementation
    implementation("com.sphereon.idk:lib-openid-oid4vp-holder-public:0.13.0")
    implementation("com.sphereon.idk:lib-openid-oid4vp-holder-impl:0.13.0")

    // Verifier/relying party implementation
    implementation("com.sphereon.idk:lib-openid-oid4vp-verifier-public:0.13.0")
    implementation("com.sphereon.idk:lib-openid-oid4vp-verifier-impl:0.13.0")

    // Universal OID4VP (combined holder + verifier with HTTP adapter)
    implementation("com.sphereon.idk:lib-openid-oid4vp-universal-public:0.13.0")
    implementation("com.sphereon.idk:lib-openid-oid4vp-universal-impl:0.13.0")

    // DCQL query support
    implementation("com.sphereon.idk:lib-openid-oid4vp-dcql:0.13.0")
}

Decentralized Identifiers (DID)

dependencies {
    // Core DID models and utilities
    implementation("com.sphereon.idk:lib-did-core-public:0.13.0")

    // DID resolution
    implementation("com.sphereon.idk:lib-did-resolver-public:0.13.0")
    implementation("com.sphereon.idk:lib-did-resolver-impl:0.13.0")

    // DID management (create, update, deactivate)
    implementation("com.sphereon.idk:lib-did-manager-public:0.13.0")
    implementation("com.sphereon.idk:lib-did-manager-impl:0.13.0")

    // DID methods (include the ones you need)
    implementation("com.sphereon.idk:lib-did-methods-key:0.13.0")   // did:key
    implementation("com.sphereon.idk:lib-did-methods-jwk:0.13.0")   // did:jwk
    implementation("com.sphereon.idk:lib-did-methods-web:0.13.0")   // did:web

    // DID persistence (optional)
    implementation("com.sphereon.idk:lib-did-persistence-api:0.13.0")
    implementation("com.sphereon.idk:lib-did-persistence-memory:0.13.0")   // In-memory
    implementation("com.sphereon.idk:lib-did-persistence-sqlite:0.13.0")   // SQLite

    // DID REST server (Universal Resolver compatible)
    implementation("com.sphereon.idk:lib-did-rest-resolver-server:0.13.0")
}

SD-JWT

dependencies {
    implementation("com.sphereon.idk:lib-sdjwt-public:0.13.0")
    implementation("com.sphereon.idk:lib-sdjwt-impl:0.13.0")
}

Trust Validation

dependencies {
    // Generic trust validation framework
    implementation("com.sphereon.idk:lib-trust-core:0.13.0")

    // ETSI Trust Service Status Lists
    implementation("com.sphereon.idk:lib-trust-etsi:0.13.0")
}

Data Storage

dependencies {
    // Key-value store abstraction
    implementation("com.sphereon.idk:lib-data-store-kv-public:0.13.0")
    implementation("com.sphereon.idk:lib-data-store-kv-impl:0.13.0")

    // KV store backends (include one)
    implementation("com.sphereon.idk:lib-data-store-kv-impl-memory:0.13.0")   // In-memory
    implementation("com.sphereon.idk:lib-data-store-kv-impl-kottage:0.13.0")  // Kottage (persistent)

    // Party/identity management models
    implementation("com.sphereon.idk:lib-data-store-party-public:0.13.0")
}

Framework Support

dependencies {
    // Spring Boot integration
    implementation("com.sphereon.idk:spring-support:0.13.0")

    // Ktor server integration
    implementation("com.sphereon.idk:ktor-support:0.13.0")
    implementation("com.sphereon.idk:ktor-server-kotlin-inject:0.13.0")
}

Platform-Specific Configuration

Android

Add the following to your app's build.gradle.kts:

android {
    compileSdk = 35

    defaultConfig {
        minSdk = 27
        targetSdk = 35
    }

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

    kotlinOptions {
        jvmTarget = "17"
    }
}

For BLE and NFC functionality, add the required permissions to your AndroidManifest.xml:

<!-- Bluetooth permissions -->
<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" />

<!-- Location (required for BLE scanning on some Android versions) -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<!-- NFC permissions -->
<uses-permission android:name="android.permission.NFC" />

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

For NFC Host Card Emulation (HCE), register the service in your manifest:

<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>

iOS

Add the required capabilities to your app's entitlements:

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

Add the following to your Info.plist:

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

<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>UIBackgroundModes</key>
<array>
    <string>bluetooth-central</string>
    <string>bluetooth-peripheral</string>
</array>

Verifying Installation

After configuring your dependencies, verify the installation by creating a simple test:

Android/kotlin
iOS/Swift

import com.sphereon.crypto.kms.KeyManagerService
import com.sphereon.crypto.SignatureAlgorithm

fun verifyInstallation() {
    // If this compiles, basic imports are working
    val algorithm = SignatureAlgorithm.ES256
    println("IDK installation verified: $algorithm")
}

import SphereonIDK

func verifyInstallation() {
    // If this compiles, basic imports are working
    let algorithm = SignatureAlgorithm.es256
    print("IDK installation verified: \(algorithm)")
}

Next Steps

With the IDK installed, proceed to configure your application:

Set up Dependency Injection with the scope hierarchy
Configure your Application Component
Review Configuration options

Repository Configuration​

Module Dependencies​

All-in-One Dependency​

Individual Modules​

Core and Configuration​

Cryptography​

Mobile Credentials (mDoc)​

OAuth 2.0​

OpenID4VP​

Decentralized Identifiers (DID)​

SD-JWT​

Trust Validation​

Data Storage​

Framework Support​

Platform-Specific Configuration​

Android​

iOS​

Verifying Installation​

Next Steps​