Get started · Android
Android apps
Android apps use kcoap’s JVM artifacts; there is no separate Android target. CI builds a sample app at API level 26 with R8 and lint, in a classical and a post-quantum flavor. It has not run on an emulator or a device yet.
- ArtifactsThe
jvmones - MinimumAPI level 26 (Android 8.0)
- CryptographyThe platform’s JCA providers
- R8 rulesShipped in kcoap’s jars
Prerequisites
- An app with
minSdk26 or higher, built with the Android Gradle plugin. The sample uses AGP 9.4.1 with compileSdk and targetSdk 36. - Kotlin 2.3 or newer. AGP 9 compiles Kotlin with the Kotlin Gradle plugin on the build’s classpath; the sample puts 2.4.21 there, the version kcoap is built with.
- A JDK 17 or newer, to run Gradle.
Install status
kcoap 0.1.0 is on Maven Central. API level 26 is held by checks of every jar against the API 26 signature and by the sample’s R8 build in CI, not yet by a run on an emulator or a phone. Whether the X25519 and Ed25519 probes answer on API levels 26 to 32 is still open.
Set up
-
Check the repositories
kcoap comes from Maven Central, which the
settings.gradle.ktsof a new Android project already lists.settings.gradle.kts
dependencyResolutionManagement { repositories { google() mavenCentral() // kcoap } } -
Add the modules and Java 17 bytecode
kcoap’s classes are Java 17 bytecode, and Kotlin inlines kcoap’s inline functions only into bytecode of the same target or newer. D8 handles Java 17 bytecode at any minSdk. The bill of materials,
kcoap-bom, sets one version for every kcoap module, so the modules name none.Kotlin DSL
app/build.gradle.kts
android { defaultConfig { minSdk = 26 } compileOptions { sourceCompatibility = JavaVersion.VERSION_17 targetCompatibility = JavaVersion.VERSION_17 } } dependencies { implementation(platform("dev.kcoap:kcoap-bom:0.1.0")) implementation("dev.kcoap:kcoap-coap") implementation("dev.kcoap:kcoap-transport-ktor") implementation("dev.kcoap:kcoap-crypto-default") implementation("dev.kcoap:kcoap-oscore") implementation("dev.kcoap:kcoap-edhoc-oscore") // implementation("dev.kcoap:kcoap-crypto-bc") // post-quantum EDHOC }Version catalog
gradle/libs.versions.toml
[versions] kcoap = "0.1.0" [libraries] kcoap-bom = { module = "dev.kcoap:kcoap-bom", version.ref = "kcoap" } kcoap-coap = { module = "dev.kcoap:kcoap-coap" } kcoap-transport-ktor = { module = "dev.kcoap:kcoap-transport-ktor" } kcoap-crypto-default = { module = "dev.kcoap:kcoap-crypto-default" } kcoap-oscore = { module = "dev.kcoap:kcoap-oscore" } kcoap-edhoc-oscore = { module = "dev.kcoap:kcoap-edhoc-oscore" } kcoap-crypto-bc = { module = "dev.kcoap:kcoap-crypto-bc" } [bundles] kcoap = [ "kcoap-coap", "kcoap-transport-ktor", "kcoap-crypto-default", "kcoap-oscore", "kcoap-edhoc-oscore", ]app/build.gradle.kts
android { defaultConfig { minSdk = 26 } compileOptions { sourceCompatibility = JavaVersion.VERSION_17 targetCompatibility = JavaVersion.VERSION_17 } } dependencies { implementation(platform(libs.kcoap.bom)) implementation(libs.bundles.kcoap) // implementation(libs.kcoap.crypto.bc) // post-quantum EDHOC }Do not add
kcoap-transport-ktor-websocket-serverto an app: the ktor server libraries under it usejava.beansandClassValue, which Android does not have. The WebSocket client,kcoap-transport-ktor-websocket, is fine. -
Ask for the network
UDP sockets need the
INTERNETpermission, even on the loopback interface.app/src/main/AndroidManifest.xml
<uses-permission android:name="android.permission.INTERNET" />
First client and server
A server and a client in the same app, each on its own UDP socket on the loopback interface. Port 0 lets the system pick a free port; the client reads the server’s from its transport.
LoopbackGet.kt
import dev.kcoap.coap.CoapResponse
import dev.kcoap.coap.client.CoapClient
import dev.kcoap.coap.client.CoapClientConfig
import dev.kcoap.coap.server.CoapServer
import dev.kcoap.transport.ktor.KtorUdpTransport
import kotlinx.coroutines.CoroutineScope
import kotlin.time.Duration.Companion.seconds
suspend fun loopbackGet(scope: CoroutineScope): String {
val serverTransport = KtorUdpTransport.bind("127.0.0.1", 0)
val server = CoapServer(serverTransport, scope) {
resource("hello") { get { CoapResponse.content("Hello") } }
}
val port = serverTransport.localEndpoint.port
val uri = "coap://127.0.0.1:$port/hello"
val config = CoapClientConfig { requestTimeout = 10.seconds }
val transport = KtorUdpTransport.bind("127.0.0.1", 0)
val client = CoapClient(transport, scope, config)
return try {
val answer = client.get(uri)
"GET $uri: ${answer.code} ${answer.payloadAsText()}"
} finally {
client.close()
server.close()
}
}Shortened from the sample’s LoopbackGets.kt, which CI builds and shrinks with R8; the sample also sends the same GET under OSCORE. This shortened form is not compiled on its own.
Run it from a coroutine scope that lives as long as the screen, and cancel the scope when Android destroys the Activity:
MainActivity.kt
import android.app.Activity
import android.os.Bundle
import android.util.Log
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.cancel
import kotlinx.coroutines.launch
class MainActivity : Activity() {
private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default)
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
scope.launch {
// GET coap://127.0.0.1:…/hello: 2.05 Content Hello
Log.i("kcoap", loopbackGet(scope))
}
}
override fun onDestroy() {
scope.cancel()
super.onDestroy()
}
}The scope and its lifecycle are those of the sample’s MainActivity, which CI builds.
Keys and state in an app
- One set of OSCORE contexts per process. Derive each context once, in the
Applicationor a singleton, never per Activity. Android can run two Activities of an app at once, and two live contexts under one name hand out the same sequence numbers, which reuses nonces. - Sequence numbers outside Auto Backup. Pre-shared OSCORE keys need a durable
SequenceNumberStore. The sample’sFileSequenceNumberStorefollows the JVM and Android recipe with API 26 calls only, and keeps its files innoBackupFilesDir: a sequence number restored from a backup reuses nonces. - EDHOC needs no durable store. Its keys are new for each session. Cipher suite 2 (P-256) is the one every platform runs.
- Post-quantum EDHOC comes from
kcoap-crypto-bc, asBouncyCastleCryptoBackend(DefaultCryptoBackend()). The sample’spostQuantumflavor builds and shrinks with it, but it has not run on a device.
Platform notes
R8 and lint
An app needs no R8 rules of its own. kcoap-crypto-default carries META-INF/proguard/kcoap-crypto-default.pro, which AGP applies by itself: cryptography-kotlin refers to Bouncy Castle and uses it only when it finds it at runtime, and the rules tell R8 those classes may be missing. The sample shrinks both flavors with proguard-android-optimize.txt and an empty rules file.
Lint’s InvalidPackage check flags library references to Java packages Android lacks, such as java.lang.management in ktor-utils and javax.naming in Bouncy Castle. Each one is triaged as unreachable or guarded. If your lint treats it as fatal, downgrade it as the sample does:
app/build.gradle.kts
android {
lint {
warning += "InvalidPackage"
}
}TLS
KtorTlsConnector, the coaps+tcp client of the JVM guide, is in the same jar. On Android it checks the server’s chain with the host through the platform, so your network security configuration applies per domain. It has not run on Android yet.
What holds API level 26
checkAndroidApi checks every kcoap jvm jar against the API 26 signature, and checkAndroidApiDependencies checks the libraries behind them against a triaged baseline. No core library desugaring is needed at minSdk 26. The findings, library by library.
Not done yet on Android
- No run on an emulator or a device, and no report of which algorithms each API level offers.
- No Android Keystore backend; keys are opaque handles, so one can hold them later.
- No lifecycle handling beyond what your scope does, and no Android guide.
Troubleshooting
- Could not find
dev.kcoap:…:0.1.0 - Check that the repositories in
settings.gradle.ktsincludemavenCentral(). WithRepositoriesMode.FAIL_ON_PROJECT_REPOS, repositories in a module’s build file are refused. - R8 fails the release build on missing Bouncy Castle classes
- Check that
kcoap-crypto-defaultis on the classpath: its jar carries the rules. - Binding the socket fails with a permission error
- Add the
INTERNETpermission to the manifest. - Lint fails on
InvalidPackage - Downgrade it to a warning, as above.
- The build fails on
java.beansorClassValue - Remove
kcoap-transport-ktor-websocket-server; an app does not need it.
Next steps
- The Android sample: what it checks, what an app needs, and the API level findings.
- The client and server guide and the OSCORE guide.
- Features: what kcoap implements and how it is checked.