A lightweight, thread-safe, SharedPreferences-style encrypted key-value preference storage library for Kotlin Multiplatform (KMP).
It transparently encrypts all key-value entries using AES-256-GCM authenticated encryption, storing the master encryption key inside platform-native secure hardware/OS key stores (Android Keystore, Apple Keychain, OS Credential Managers).
| Platform | Master Key Protection | Snapshot Storage |
|---|---|---|
| π€ Android | Android Keystore (non-exportable AES-256-GCM key) | Private SharedPreferences |
| π iOS | Apple Keychain (AfterFirstUnlockThisDeviceOnly) |
NSUserDefaults |
| π₯οΈ Desktop (JVM) | macOS Keychain / Windows Credential Manager / Linux Secret Service (via Java Keyring) | POSIX-secured user file (~/.securepreferences/) |
| π Extensible | SecurePreferencesFactory for custom crypto & storage adapters |
Custom implementation |
- Cryptography: AES-256-GCM with a fresh 96-bit Initialization Vector (IV/nonce) generated for every write operation.
- Coroutines & Concurrency: Fully suspending API (
suspend) with thread-safe in-process mutation locks. - Serialization:
kotlinx.serializationfor typed JSON preference payload snapshotting. - Java Keyring: Native credential store integration for macOS, Windows, and Linux on JVM.
- Apple Security Framework: Native iOS Keychain APIs for key creation, protection, and retrieval.
- Optional Koin Support: Pre-built Koin module artifact (
:secure-preferences-koin) for Android Dependency Injection.
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven { url = uri("https://jitpack.io") }
}
}Version Catalog (gradle/libs.versions.toml):
[versions]
securePreferences = "0.1.0"
[libraries]
secure-preferences-core = { group = "io.github.kratos1996", name = "secure-preferences-kmp", version.ref = "securePreferences" }
secure-preferences-koin = { group = "io.github.kratos1996", name = "secure-preferences-koin", version.ref = "securePreferences" }Version Catalog (gradle/libs.versions.toml):
[versions]
securePreferences = "0.1.0"
[libraries]
secure-preferences-core = { group = "com.github.Kratos1996.SecurePreferencesKMP", name = "secure-preferences-kmp", version.ref = "securePreferences" }
secure-preferences-koin = { group = "com.github.Kratos1996.SecurePreferencesKMP", name = "secure-preferences-koin", version.ref = "securePreferences" }sourceSets {
commonMain.dependencies {
implementation(libs.secure.preferences.core)
}
}For Android apps using Koin Dependency Injection:
dependencies {
implementation(libs.secure.preferences.core)
implementation(libs.secure.preferences.koin)
}Initialize using SecurePreferencesAndroid:
import com.ishant.securepreferences.SecurePreferencesConfig
import com.ishant.securepreferences.android.SecurePreferencesAndroid
val preferences = SecurePreferencesAndroid.create(
context = context,
config = SecurePreferencesConfig(name = "user_session"),
)
// Suspending write calls
preferences.putString("access_token", "secret_jwt_token")
preferences.putBoolean("is_logged_in", true)
preferences.putInt("user_id", 1024)
// Suspending read calls
val token: String? = preferences.getString("access_token")
val isLoggedIn: Boolean = preferences.getBoolean("is_logged_in", defaultValue = false)
val userId: Int = preferences.getInt("user_id", defaultValue = -1)Initialize using SecurePreferencesIos:
import com.ishant.securepreferences.SecurePreferencesConfig
import com.ishant.securepreferences.ios.SecurePreferencesIos
val preferences = SecurePreferencesIos.create(
config = SecurePreferencesConfig(name = "user_session"),
)
preferences.putString("access_token", "secret_jwt_token")
val token = preferences.getString("access_token")Initialize using SecurePreferencesDesktop (supports macOS, Windows, and Linux):
import com.ishant.securepreferences.SecurePreferencesConfig
import com.ishant.securepreferences.desktop.SecurePreferencesDesktop
val preferences = SecurePreferencesDesktop.create(
config = SecurePreferencesConfig(name = "user_session"),
)
preferences.putString("access_token", "secret_jwt_token")
val token = preferences.getString("access_token")Register securePreferencesModule inside your Koin startup block:
import com.ishant.securepreferences.SecurePreferencesConfig
import com.ishant.securepreferences.koin.securePreferencesModule
import org.koin.android.ext.koin.androidContext
import org.koin.core.context.startKoin
startKoin {
androidContext(applicationContext)
modules(
securePreferencesModule(
config = SecurePreferencesConfig(name = "user_session"),
),
)
}Inject SecurePreferences into your Repositories or ViewModels:
import com.ishant.securepreferences.SecurePreferences
class AuthRepository(
private val preferences: SecurePreferences,
) {
suspend fun saveAuthToken(token: String) {
preferences.putString("auth_token", token)
}
suspend fun getAuthToken(): String? {
return preferences.getString("auth_token")
}
suspend fun logout() {
preferences.clear()
}
}val sessionStore = named("session")
val settingsStore = named("settings")
startKoin {
androidContext(applicationContext)
modules(
securePreferencesModule(
config = SecurePreferencesConfig(name = "session"),
qualifier = sessionStore,
),
securePreferencesModule(
config = SecurePreferencesConfig(name = "settings"),
qualifier = settingsStore,
),
)
}For custom platform extensions or testing, use SecurePreferencesFactory:
val preferences = SecurePreferencesFactory.create(
config = SecurePreferencesConfig(name = "custom"),
cipher = myCustomCipher,
storage = myCustomStorage,
)All read and write methods are suspend functions:
| Method | Description |
|---|---|
putString(key: String, value: String) |
Saves a string preference |
getString(key: String, default: String? = null): String? |
Reads a string preference |
putInt(key: String, value: Int) |
Saves an integer preference |
getInt(key: String, default: Int = 0): Int |
Reads an integer preference |
putLong(key: String, value: Long) |
Saves a long preference |
getLong(key: String, default: Long = 0L): Long |
Reads a long preference |
putFloat(key: String, value: Float) |
Saves a float preference |
getFloat(key: String, default: Float = 0f): Float |
Reads a float preference |
putDouble(key: String, value: Double) |
Saves a double preference |
getDouble(key: String, default: Double = 0.0): Double |
Reads a double preference |
putBoolean(key: String, value: Boolean) |
Saves a boolean preference |
getBoolean(key: String, default: Boolean = false): Boolean |
Reads a boolean preference |
remove(key: String) |
Deletes a specific key |
clear() |
Deletes all keys and clears the store |
contains(key: String): Boolean |
Checks if a key exists |
getAllKeys(): Set<String> |
Returns all stored key names |
- Authenticated Encryption: Uses AES-256-GCM. A fresh 96-bit nonce/IV is generated for every write operation.
- Envelope Privacy: Both preference keys and values are encrypted inside the snapshot payload. The disk contains only ciphertext.
- Tamper Protection: Authenticated Additional Data (AAD) binds each snapshot to its configured namespace (
SecurePreferencesConfig.name), preventing cross-store snapshot swapping. - Fail-Closed Design: Any tampered or corrupted snapshot throws
SecurePreferencesException.CorruptValuerather than returning fallback values.
To publish the library locally or to remote Maven repositories:
./gradlew publishToMavenLocal./gradlew publish(Requires Sonatype GPG keys and credentials configured in gradle.properties or environment variables)
Copyright 2025 Ishant Sharma
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License.
You may obtain a copy of the License.