Provider: Signing

.gitignore

@@ -1,11 +1,12 @@
 */generated
 .gradle
+demoapp/build
 build/
 !gradle/wrapper/gradle-wrapper.jar
 !**/src/main/**/build/
 !**/src/test/**/build/
 .kotlin
-provider/src/androidInstrumentedTest/kotlin/generated
+*/src/androidInstrumentedTest/kotlin/generated
 
 ### IntelliJ IDEA ###
 .idea
@@ -40,6 +41,21 @@ bin/
 
 ### Mac OS ###
 .DS_Store
+.Trashes
+*.swp
+*~.nib
+DerivedData/
+*.pbxuser
+*.mode1v3
+*.mode2v3
+*.perspectivev3
+!default.pbxuser
+!default.mode1v3
+!default.mode2v3
+!default.perspectivev3
+*.xccheckout
+xcuserdata/
+*.moved-aside
 
 ### Gradle ###
 local.properties

CHANGELOG.md

@@ -3,7 +3,13 @@
 
 ## 3.0
 
-### NEXT
+### 3.7.0 (Supreme 0.2.0)
+* Implement supreme signing capabilities
+* Introduce Attestation Data Structure
+* Dependency Updates:
+  * Kotlin 2.0.20
+  * kotlinx.serialization 1.7.2 stable (bye, bye unofficial snapshot dependency!)
+  * kotlinx-datetime 0.6.1
 
 ### 3.6.1
 * Externalise `UVarInt` to  multibase

README.md

@@ -99,6 +99,83 @@ material._
 
 <br>
 
+### Signature Creation
+
+To create a signature, obtain a `Signer` instance.
+You can do this using `Signer.Ephemeral` to create a signer for a throwaway keypair:
+```kotlin
+val signer = Signer.Ephemeral {}.getOrThrow()
+val plaintext = "You have this.".encodeToByteArray()
+val signature = signer.sign(plaintext).signature
+println("Signed using ${signer.signatureAlgorithm}: $signature")
+```
+
+If you want to create multiple signatures using the same ephemeral key, you can obtain an `EphemeralKey` instance, then create signers from it:
+```kotlin
+val key = EphemeralKey { rsa {} }.getOrThrow()
+val sha256Signer = key.getSigner { rsa { digest = Digests.SHA256 } }.getOrThrow()
+val sha384Signer = key.getSigner { rsa { digest = Digests.SHA384 } }.getOrThrow()
+```
+
+The instances can be configured using the configuration DSL.
+Any unspecified parameters use sensible, secure defaults.
+
+#### Platform Signers
+
+On Android and iOS, signers using the systems' secure key storage can be retrieved.
+To do this, use `PlatformSigningProvider` (in common code), or interact with `AndroidKeystoreProvider`/`IosKeychainProvider` (in platform-specific code).
+
+New keys can be created using `createSigningKey(alias: String) { /* configuration */ }`,
+and signers for existing keys can be retrieved using `getSignerForKey(alias: String) { /* configuration */ }`.
+
+For example, creating an elliptic-curve key over P256, stored in secure hardware, and with key attestation using a random challenge provided by your server, might be done like this:
+```kotlin
+val serverChallenge: ByteArray = TODO("This was unpredictably chosen by your server.")
+PlatformSigningProvider.createSigningKey(alias = "Swordfish") {
+  ec {
+    // you don't even need to specify the curve (P256 is the default) but we'll do it for demonstration purposes
+    curve = ECCurve.SECP_256_R_1
+    // you could specify the supported digests explicity - if you do not, the curve's native digest (for P256, this is SHA256) is supported
+  }
+  hardware {
+    // you could use PREFERRED if you want the operation to succeed (without hardware backing) on devices that do not support it
+    backing = REQUIRED
+    attestation { challenge = serverChallenge }
+    protection { 
+      timeout = 5.seconds
+      factors {
+        biometry = true
+        deviceLock = false
+      }  
+    }
+  }
+}
+```
+
+If this operation succeeds, it returns a `Signer`. The same `Signer` could later be retrieved using `PlatformSigningProvider.getSignerForKey(alias: String)`.
+
+When you use this `Signer` to sign data, the user would be prompted to authorize the signature using an enrolled fingerprint, because that's what you specified when creating the key.
+You can configure the authentication prompt:
+```kotlin
+val plaintext = "A message".encodeToByteArray()
+val signature = signer.sign(plaintext) { 
+  unlockPrompt {
+    message = "Signing a message to Bobby"
+  }
+}.signature
+```
+... but you cannot change the fact that you configured this key to need biometry. Consider this when creating your keys.
+
+#### Key Attestation
+
+The Android KeyStore offers key attestation certificates for hardware-backed keys.
+These certificates are exposed by the signer's `.attestation` property.
+
+For iOS, Apple does not provide this capability.
+We instead piggy-back onto iOS App Attestation to provide a home-brew "key attestation" scheme.
+The guarantees are different: you are trusting the OS, not the actual secure hardware; and you are trusting that our library properly interfaces with the OS.
+Attestation types are serializable for transfer, and correspond to those in Indispensable's attestation module.
+
 ### Signature Verification
 
 To verify a signature, obtain a `Verifier` instance using `verifierFor(k: PublicKey)`, either directly on a `SignatureAlgorithm`, or on one of the specialized algorithms (`X509SignatureAlgorithm`, `CoseAlgorithm`, ...).
@@ -108,7 +185,7 @@ As an example, here's how to verify a basic signature using a public key:
 ```kotlin
 val publicKey: CryptoPublicKey.EC = TODO("You have this and trust it.")
 val plaintext = "You want to trust this.".encodeToByteArray()
-val signature = TODO("This was sent alongside the plaintext.")
+val signature: CryptoSignature = TODO("This was sent alongside the plaintext.")
 val verifier = SignatureAlgorithm.ECDSAwithSHA256.verifierFor(publicKey).getOrThrow()
 val isValid = verifier.verify(plaintext, signature).isSuccess
 println("Looks good? $isValid")

build.gradle.kts

@@ -1,8 +1,8 @@
 import org.jetbrains.dokka.gradle.DokkaMultiModuleTask
 
 plugins {
-    id("at.asitplus.gradle.conventions") version "2.0.0+20240725"
-    id("com.android.library") version "8.2.0" apply (false)
+    id("at.asitplus.gradle.conventions") version "2.0.20+20240829"
+    id("com.android.library") version "8.2.2" apply (false)
 }
 group = "at.asitplus.signum"
 

demoapp/DEVELOPMENT.md

@@ -0,0 +1,6 @@
+**REQUIRES a MacOS Host to build all modules**
+
+* recursively clone this repo
+* set `sdk.dir=/absulute/path/to/Android/sdk` inside `kmp-crypto/local.properties`
+* `cd kmp-crypto && ./gradlew publishAllPublicationsToLocalRepository`
+* import the this project into Android studio

demoapp/README.MD

@@ -0,0 +1,39 @@
+# KMP Crypto Demo Multiplatform (iOS, Android JVM) App
+
+
+![img.png](img.png)
+
+This app showcases the KMP Crypto provider on the desktop, on Android and on iOS.
+It is possible to generate key pairs, sign data, and verify the signature.
+
+On iOS, only P-256 keys can be attested.
+The JVM does not support attestation.
+
+`*** TODO CLEANUP BELOW THIS LINE ***`
+
+Android and iOS support mandatory authentication for key usage. While somewhat similar functionality can be achieved on both platforms, iOS comes with some peculiarities.
+Most prominently: It is possible to specify a max validity duration of an authentication context. This property, however, has jwf semantics, since a once authenticated LAContext will remain in this state for eternety.
+Hence, reauthentication needs to be implemented manually.
+
+The BiometricAuthAdapter on Android requires some more polishing, but it should clearly convey the underlying idea even in its current state.
+
+## Before running!
+ - check your system with [KDoctor](https://github.com/Kotlin/kdoctor)
+ - install JDK 17 on your machine
+ - add `local.properties` file to the project root and set a path to Android SDK there
+
+### Android
+To run the application on android device/emulator:  
+ - open project in Android Studio and run imported android run configuration
+
+To build the application bundle:
+ - run `./gradlew :composeApp:assembleDebug`
+ - find `.apk` file in `composeApp/build/outputs/apk/debug/composeApp-debug.apk`
+
+### iOS
+To run the application on iPhone device/simulator:
+ - Open `iosApp/iosApp.xcproject` in Xcode and run standard configuration
+ - Or use [Kotlin Multiplatform Mobile plugin](https://plugins.jetbrains.com/plugin/14936-kotlin-multiplatform-mobile) for Android Studio
+
+
+

demoapp/build.gradle.kts

@@ -0,0 +1,17 @@
+plugins {
+    alias(libs.plugins.multiplatform).apply(false)
+    alias(libs.plugins.compose).apply(false)
+    alias(libs.plugins.android.application).apply(false)
+    alias(libs.plugins.buildConfig).apply(false)
+ //   id("at.asitplus.gradle.conventions") version "1.9.23+20240319+1"
+}
+
+allprojects {
+    repositories {
+        maven(rootProject.projectDir.absolutePath+"/kmp-crypto/repo")
+        maven("https://s01.oss.sonatype.org/content/repositories/snapshots")
+        maven(uri("https://raw.githubusercontent.com/a-sit-plus/kotlinx.serialization/mvn/repo"))
+        mavenCentral()
+        google()
+    }
+}

demoapp/composeApp/build.gradle.kts

@@ -0,0 +1,111 @@
+import com.android.build.api.dsl.Packaging
+
+plugins {
+    alias(libs.plugins.multiplatform)
+    alias(libs.plugins.compose)
+    alias(libs.plugins.compose.runtime)
+    alias(libs.plugins.android.application)
+    alias(libs.plugins.buildConfig)
+}
+
+kotlin {
+    jvm()
+    jvmToolchain(17)
+    androidTarget {
+        compilations.all {
+            kotlinOptions {
+                jvmTarget = "17"
+            }
+        }
+    }
+
+    listOf(
+        iosX64(),
+        iosArm64(),
+        iosSimulatorArm64()
+    ).forEach {
+        it.binaries.framework {
+            baseName = "ComposeApp"
+            isStatic = true
+        }
+    }
+
+    sourceSets {
+        all {
+            languageSettings {
+                optIn("org.jetbrains.compose.resources.ExperimentalResourceApi")
+            }
+        }
+        commonMain.dependencies {
+            implementation("at.asitplus.signum:supreme:0.2.0-SNAPSHOT") {
+                isChanging = true
+            }
+            implementation(compose.runtime)
+            implementation(compose.material3)
+            implementation(compose.materialIconsExtended)
+            @OptIn(org.jetbrains.compose.ExperimentalComposeLibrary::class)
+            implementation(compose.components.resources)
+            implementation(libs.voyager.navigator)
+            implementation(libs.composeImageLoader)
+            implementation(libs.napier)
+            implementation(libs.kotlinx.coroutines.core)
+        }
+
+        commonTest.dependencies {
+            implementation(kotlin("test"))
+        }
+
+        androidMain.dependencies {
+            implementation(libs.androidx.appcompat)
+            implementation(libs.androidx.activityCompose)
+            implementation(libs.compose.uitooling)
+            implementation(libs.kotlinx.coroutines.android)
+            implementation(libs.androidx.biometric)
+        }
+
+
+        jvmMain.dependencies {
+            implementation(compose.desktop.currentOs)
+        }
+
+    }
+}
+
+android {
+    namespace = "at.asitplus.cryptotest"
+    compileSdk = 34
+
+    defaultConfig {
+        minSdk = 33
+        targetSdk = 34
+
+        applicationId = "at.asitplus.cryptotest.androidApp"
+        versionCode = 1
+        versionName = "1.0.0"
+    }
+    sourceSets["main"].apply {
+        manifest.srcFile("src/androidMain/AndroidManifest.xml")
+        res.srcDirs("src/androidMain/resources")
+        resources.srcDirs("src/commonMain/resources")
+    }
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+    buildFeatures {
+        compose = true
+    }
+    composeOptions {
+        kotlinCompilerExtensionVersion = "1.5.4"
+    }
+
+   packaging {
+       resources.excludes.add("META-INF/versions/9/OSGI-INF/MANIFEST.MF")
+   }
+}
+
+buildConfig {
+    // BuildConfig configuration here.
+    // https://github.com/gmazzo/gradle-buildconfig-plugin#usage-in-kts
+}
+

demoapp/composeApp/src/androidMain/AndroidManifest.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <application
+        android:name=".AndroidApp"
+        android:icon="@android:drawable/ic_menu_compass"
+        android:label="CryptoTest App"
+        android:theme="@style/Theme.AppCompat.DayNight.NoActionBar">
+        <activity
+            android:name=".AppActivity"
+            android:configChanges="orientation|screenSize|screenLayout|keyboardHidden"
+            android:launchMode="singleInstance"
+            android:windowSoftInputMode="adjustPan"
+            android:exported="true">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+    </application>
+
+</manifest>

demoapp/composeApp/src/androidMain/kotlin/at/asitplus/cryptotest/App.android.kt

@@ -0,0 +1,17 @@
+package at.asitplus.cryptotest
+
+import android.app.Application
+import android.os.Bundle
+import androidx.activity.compose.setContent
+import androidx.fragment.app.FragmentActivity
+
+class AndroidApp : Application()
+
+class AppActivity : FragmentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContent {
+            App()
+        }
+    }
+}