
Unified API for secure storage of API keys, tokens, passwords, certificates and signing keys using native secure stores; no plaintext fallback, actionable failure reasons, biometric and hardware-backed keys.
Kotlin Multiplatform storage for API keys, tokens, and passwords, backed by platform secure storage. There is no plaintext persistence fallback: every supported platform routes through its native secure-storage facility (Android Keystore, Apple Keychain, macOS Keychain, Linux Secret Service, or Windows DPAPI), or the call throws.
This exists for apps and libraries that need one interface for things like storing an
OAuth refresh token, a scoped API key, or a user's saved username and password across
Android, iOS, macOS, tvOS, watchOS, and desktop JVM — without writing a platform-specific
secure-storage adapter for each target. CredentialKeychain stores secrets by key, and
PasswordStore stores username/password credentials per server.
read/write/delete/clear behave the same
from commonMain; each platform target resolves to its own OS-backed secure store.Context), the
library throws KeychainUnavailableException instead of writing plaintext or an
in-memory stand-in you might mistake for durable storage.reason — Unsupported, Locked,
Canceled, AuthenticationInvalidated, Corrupted, or Failed — so you can retry
later, re-prompt, or reset the store.serviceName and accountName are
bound into the storage key rather than just a bare key string.| Platform | Kotlin targets | Backend |
|---|---|---|
| Android 6.0+ (API 23+) | android |
Android Keystore AES-256-GCM; ciphertext in app-private, non-backed-up files |
| iOS |
iosArm64, iosSimulatorArm64
|
Apple Keychain, device-only, configurable accessibility |
| tvOS |
tvosArm64, tvosSimulatorArm64
|
Apple Keychain, device-only, configurable accessibility |
| watchOS |
watchosArm64, watchosDeviceArm64, watchosSimulatorArm64
|
Apple Keychain, device-only, configurable accessibility |
| macOS | macosArm64 |
File-based login keychain through the Security framework |
| macOS desktop JVM | jvm |
Login keychain through /usr/bin/security
|
| Linux desktop JVM | jvm |
Secret Service through secret-tool
|
| Windows desktop JVM | jvm |
Current-user DPAPI (secrets), Credential Manager (passwords), and the current-user certificate store, called in-process through JNA |
JVM artifacts target Java 17. Intel Apple targets (iosX64, macosX64, tvosX64,
watchosX64) are not published; Intel Macs are supported through the JVM target. Windows
and Linux support requires a JVM — there are no mingwX64, linuxX64, or linuxArm64
native backends, and no web (js, wasmJs) targets.
// build.gradle.kts
kotlin {
sourceSets.commonMain.dependencies {
implementation("io.github.maniramezan:credential-keychain-kotlin:0.1.1") // x-release-please-version
// Optional: secrets that require biometric authentication to read.
implementation("io.github.maniramezan:credential-keychain-kotlin-biometric:0.1.1") // x-release-please-version
}
}Both artifacts share one version. The biometric artifact adds androidx.biometric and
kotlinx-coroutines-core. The core artifact's JVM variant depends on
JNA (net.java.dev.jna:jna) for the Windows
backends; its other variants have no dependencies.
No extra platform dependency, manifest entry, or entitlement is required to link the
library. On macOS and Linux the desktop JVM target shells out to an OS tool (security or
secret-tool) that must be present on the machine; on Windows it calls the Win32 APIs
directly — see
Contract and requirements.
In commonMain, obtain an instance through CredentialKeychain.forCurrentPlatform(...),
which resolves to the right backend for the target being compiled.
import com.maniramezan.credentialkeychain.CredentialKeychain
// Apple native or desktop JVM:
val keychain = CredentialKeychain.forCurrentPlatform(
serviceName = "my-app",
accountName = "user-123", // defaults to serviceName
)
keychain.write("api-key", "secret-token")
val token: String? = keychain.read("api-key") // null only if absent
keychain.delete("api-key")
keychain.clear() // removes every entry for my-app/user-123Call from a worker thread or coroutine dispatcher — every operation is synchronous and a
native backend may block or prompt the user. Use the failure reason to decide what to do:
suspend fun readApiKey(keychain: CredentialKeychain): String? = withContext(Dispatchers.IO) {
try {
keychain.read("api-key")
} catch (e: KeychainUnavailableException) {
when (e.reason) {
KeychainUnavailableException.Reason.Locked -> null // retry after the device unlocks
KeychainUnavailableException.Reason.Corrupted -> { keychain.clear(); null } // re-authenticate
else -> throw e
}
}
}Inject a single CredentialKeychain into shared application code (a repository, a
ViewModel, DI graph) rather than calling forCurrentPlatform at every call site — this
is also what lets Android supply its Context-based implementation without commonMain
needing to know about Context at all:
// In androidMain:
import com.maniramezan.credentialkeychain.CredentialKeychain
import com.maniramezan.credentialkeychain.forCurrentPlatform
val keychain: CredentialKeychain = CredentialKeychain.forCurrentPlatform(
context = applicationContext,
serviceName = "my-app",
accountName = "user-123",
)The Context-free factory on Android returns an unavailable store — every call throws
KeychainUnavailableException with reason Unsupported — rather than silently working
without one. This avoids retaining an Activity or requiring global initialization just so
commonMain can call a zero-argument factory.
val keychain = CredentialKeychain.forCurrentPlatform(
serviceName = "my-app",
accountName = "user-123",
options = KeychainOptions(
appleAccessibility = AppleAccessibility.AfterFirstUnlock, // iOS/tvOS/watchOS background access
desktopCommandTimeout = 60.seconds, // macOS/Linux JVM tool timeout, including access prompts
),
)Options that don't apply to the current platform are ignored.
PasswordStore keeps username/password credentials per server, using each platform's native
password storage. It is created the same way (Android uses the Context-taking overload) and
is independent of a CredentialKeychain with the same service and account names:
val passwords = PasswordStore.forCurrentPlatform(serviceName = "my-app", accountName = "user-123")
passwords.save(PasswordCredential(server = "api.example.com", username = "alice", password = "s3cret"))
val alice: PasswordCredential? = passwords.find(server = "api.example.com", username = "alice")
val accounts: List<String> = passwords.findAll(server = "api.example.com").map { it.username } // sorted
passwords.delete(server = "api.example.com", username = "alice")
passwords.clear() // removes every password for my-app/user-123, on every serverPasswordCredential.toString() never includes the password.
HardwareKeyStore generates non-exportable ECDSA P-256 keys inside secure hardware — StrongBox
or the trusted execution environment on Android, the Secure Enclave on Apple platforms — and
signs with them. Private keys never leave the hardware:
val keys = HardwareKeyStore.forCurrentPlatform(serviceName = "my-app", accountName = "user-123")
val key: HardwareKeyInfo = keys.generate("device-binding") // replaces an existing key
server.register(key.publicKeyDer, key.securityLevel) // X.509 SubjectPublicKeyInfo
val signature: ByteArray? = keys.sign("device-binding", challenge) // DER ECDSA-SHA256; null if missing
keys.delete("device-binding")Generation fails with reason Unsupported when no secure hardware is available (emulators,
simulators, unsigned macOS tools, desktop JVM). Pass HardwareKeySpec(allowSoftwareKeys = true)
to accept software-backed keys where the platform offers them; securityLevel always reports
what you actually got. Android needs no Context for this store.
CertificateStore keeps X.509 certificates and PKCS#12 identities. Private keys go to native key
storage; certificate chains are returned as DER, leaf first:
val certificates = CertificateStore.forCurrentPlatform(serviceName = "my-app", accountName = "user-123")
val client: CertificateInfo = certificates.importPkcs12("client", pkcs12Bytes, passphrase) // replaces "client"
certificates.importCertificate("pinned-ca", caCertificateDer)
val chain: List<ByteArray>? = certificates.info("client")?.certificateChainDer
val aliases: List<String> = certificates.aliases() // sorted
certificates.delete("pinned-ca")A malformed bundle or wrong passphrase throws IllegalArgumentException; the passphrase array is
not cleared for you. Desktop JVM stores identities in the macOS login keychain, the Windows
current-user certificate store, or Linux Secret Service; Android moves private keys into Android
Keystore (use the Context-taking overload); Apple platforms store identities in the
data-protection keychain, which needs an app with keychain entitlements.
To use a stored identity for signing or client authentication, get its platform handle. Each
returns null when the alias has no entry or holds only a certificate:
// androidMain and jvmMain: feeds Signature, KeyManagerFactory, or an SSLContext
val entry: KeyStore.PrivateKeyEntry? = certificates.privateKeyEntry("client")
// appleMain: a retained SecIdentityRef for URLSession client authentication; release with CFRelease
@OptIn(ExperimentalForeignApi::class)
val identity: SecIdentityRef? = certificates.secIdentity("client")Private keys stay in native storage: Android Keystore, the macOS login keychain, the Windows
certificate store (read through the JDK Windows-MY provider), or the Apple keychain.
ProtectedKeychain, in the separate credential-keychain-kotlin-biometric artifact, stores
secrets that need a strong biometric (Android Class 3, Face ID, or Touch ID) to read. Writing,
deleting, and clearing need no authentication; read suspends while the system prompt is shown:
import com.maniramezan.credentialkeychain.biometric.AuthenticationPrompt
import com.maniramezan.credentialkeychain.biometric.ProtectedKeychain
// iOS and macOS; Android uses the overload that also takes a Context and a FragmentActivity provider.
val protected = ProtectedKeychain.forCurrentPlatform(serviceName = "my-app", accountName = "user-123")
protected.write("refresh-token", token)
val prompt = AuthenticationPrompt(title = "Unlock your account", cancelLabel = "Cancel")
try {
val token: String? = protected.read("refresh-token", prompt) // null if never written
} catch (error: KeychainUnavailableException) {
when (error.reason) {
Reason.Canceled -> Unit // the user dismissed the prompt
Reason.AuthenticationInvalidated -> protected.delete("refresh-token") // enrollment changed; sign in again
else -> throw error
}
}Entries are invalidated when biometric enrollment changes. Android needs API 23+; iOS 15+ and
macOS 12+ apps need keychain entitlements, and iOS apps that use Face ID need
NSFaceIDUsageDescription. On tvOS, watchOS, and desktop JVM every operation throws
Reason.Unsupported. The iOS simulator does not enforce biometric access control, so validate
prompts and enrollment changes on a device.
Namespacing by accountName keeps one secure entry set per signed-in user without
encoding the user id into each key yourself:
fun keychainFor(userId: String): CredentialKeychain =
CredentialKeychain.forCurrentPlatform(serviceName = "com.example.myapp", accountName = userId)
fun saveTokens(userId: String, accessToken: String, refreshToken: String) {
val keychain = keychainFor(userId)
keychain.write("access-token", accessToken)
keychain.write("refresh-token", refreshToken)
}
fun signOut(userId: String) {
keychainFor(userId).clear()
}// commonMain
@Composable
fun ApiKeyScreen(keychain: CredentialKeychain) {
var apiKey by remember { mutableStateOf<String?>(null) }
LaunchedEffect(keychain) {
apiKey = withContext(Dispatchers.Default) { keychain.read("api-key") }
}
// render apiKey / a form that calls keychain.write("api-key", input) on submit
}
// androidMain composition root
val context = LocalContext.current.applicationContext
val keychain = remember(context) { CredentialKeychain.forCurrentPlatform(context, "my-app") }
ApiKeyScreen(keychain)
// iosMain composition root
val keychain = remember { CredentialKeychain.forCurrentPlatform(serviceName = "my-app") }
ApiKeyScreen(keychain)Consumed from Swift, a CredentialKeychain created through your KMP framework works
unchanged:
let keychain = try CredentialKeychainCompanion.shared.forCurrentPlatform(serviceName: "my-app", accountName: "user-123")
try keychain.write(key: "api-key", value: "secret-token")
let token = try keychain.read(key: "api-key")
try keychain.clear()
let passwords = try PasswordStoreCompanion.shared.forCurrentPlatform(serviceName: "my-app", accountName: "user-123")
try passwords.save(credential: PasswordCredential(server: "api.example.com", username: "alice", password: "s3cret"))
let alice = try passwords.find(server: "api.example.com", username: "alice")Export this dependency from your consuming Kotlin framework before importing it in
Swift; this package publishes KLIBs, not a standalone Swift framework. Generated names
can vary with your framework configuration. Every operation declares @Throws, so Swift
callers handle failures with do/catch.
On iOS, tvOS, and watchOS, entries are device-only, never iCloud-synchronized, and readable
according to appleAccessibility. The default, WhenUnlocked, makes reads fail with
reason Locked while the device is locked; use AfterFirstUnlock for background refresh.
Changing the option on a later write updates the existing entry.
On macOS, Kotlin/Native entries live in the file-based login keychain, which does not
support accessibility classes: appleAccessibility is ignored, and access is controlled by
the keychain's per-item access list, which trusts the application that created the item.
This works for unsigned tools; macOS may prompt when a differently signed build reads an
existing item.
The same forCurrentPlatform(serviceName, accountName) call is used; the OS the JVM runs
on selects the backend (see the platform table):
// jvmMain — works unmodified on macOS, Linux, or Windows
val keychain = CredentialKeychain.forCurrentPlatform("my-cli-tool")
keychain.write("github-token", token)null for absent entries. Unavailable backends and operational failures
throw KeychainUnavailableException; do not interpret them as missing credentials.
Unsupported — no usable backend in this platform or environment.Locked — the store is locked or access was denied; retrying later may succeed.Canceled — the user dismissed an access prompt; retry only on user action.AuthenticationInvalidated — the protecting key was permanently invalidated (for
example, biometric enrollment changed); delete the entry or clear().Corrupted — data exists but can't be decrypted or decoded; delete the entry or clear().Failed — any other failure, such as an I/O error or timeout.write stores values exactly, including surrounding whitespace. Blank values throw
IllegalArgumentException; call delete to remove an entry.security backend additionally rejects CR/LF in values.
Native Apple and Android backends accept multiline secrets.PasswordStore applies the same rules on every platform so credentials stay portable:
servers and usernames are nonblank without NUL, CR, or LF; usernames are at most 512
characters; passwords are nonblank, without NUL, CR, or LF, and at most 2,560 UTF-8 bytes
(the Windows Credential Manager limit). save replaces an existing password, and
findAll returns credentials sorted by username.findAll
lists usernames from security dump-keychain, which reads attributes but not passwords.HardwareKeyStore keys are ECDSA P-256; signatures are DER-encoded ECDSA with SHA-256 and
verify with SHA256withECDSA. Android prefers StrongBox (API 28+) and falls back to the TEE;
before API 31 it reports hardware keys as TrustedEnvironment even when StrongBox-backed.
Apple Secure Enclave keys require a signed app (the data-protection keychain); unsigned macOS
processes can only use opt-in software keys in the login keychain. Desktop JVM always throws
Unsupported.CertificateStore accepts PKCS#12 bundles with exactly one private key and DER certificates,
each at most 1 MiB. Chains and the alias index are kept in the platform's secret storage under
a separate "certificates" namespace; aliases() is not transactional across processes. On
desktop JVM, identities go to the macOS login keychain (JDK KeychainStore), the Windows
current-user My store with a non-exportable key (removed with its key container), or Linux
Secret Service as a re-encoded PKCS#12 bundle, where bundles over 8 KiB fail with Unsupported.
On Android, private keys are imported into Android Keystore as non-exportable keys: EC keys
may sign, RSA keys may sign and decrypt (PKCS#1, PSS, OAEP). Other key algorithms are rejected.
On Apple platforms, bundles are decoded in memory and the identity (certificate and private key)
is stored in the data-protection keychain under a namespaced label. Unsigned macOS processes
cannot use that keychain and get Unsupported, and macOS identities need macOS 15 or later.
One identity can back only one alias per keychain; importing it under a second alias fails.Corrupted
(existing ciphertext is never silently replaced) until you delete the affected entries
or clear() the store.secret-tool and an accessible Secret Service session (for example,
GNOME Keyring). Headless sessions may not have one. Credentials should stay below
8 KiB, the input limit of commonly deployed secret-tool versions.CryptProtectData, the
Credential Manager (Cred*W), and CryptoAPI in-process through JNA, without launching a
helper process. Ciphertext lives under %LOCALAPPDATA%\credential-keychain\ in hashed
service/account and key paths. DPAPI binds decryption to the Windows user, not to a
particular application. On JDK 24 and later, JNA's native access prints a warning unless the
application is started with --enable-native-access=ALL-UNNAMED (or =com.sun.jna on the
module path).desktopCommandTimeout (30 seconds by default).
Secrets are supplied through stdin, and backend error output is never included in exceptions.The library relies on each platform's secure storage and does not add protection beyond
it. In particular, on desktop JVM any process running as the same OS user can read the
stored credentials: macOS items created through /usr/bin/security trust that tool, so
security find-generic-password can read them without a prompt; unlocked Secret Service
collections are available to the whole session; and DPAPI and Credential Manager decrypt
for any process of the same Windows user. Service and account names prevent collisions — they are not an
authorization boundary. See SECURITY.md for the full model and for
reporting vulnerabilities.
Building requires JDK 21, Android SDK 36, and the Gradle wrapper; the published JVM artifacts run on Java 17+. A macOS host with a compatible Xcode is required to build the Apple artifacts.
./gradlew jvmTest
./gradlew assemble macosArm64Test
./gradlew publishToMavenLocalAfter local publication, a consuming KMP project can add mavenLocal() to its repositories
and depend on the same coordinates shown in Installation. The library
lives in core/, with shared build configuration in build-logic/. Each module creates
the KMP metadata publication and 10 platform publications; publish the complete set when
distributing the library.
IntelliJ IDEA and Android Studio load shared run configurations from .run/: Build All, JVM
Tests, Android Device Tests (pinned to emulator-5554 with ANDROID_SERIAL), desktop
integration tests (macOS uses a disposable keychain), and the verification consumer build.
./gradlew ktlintCheck jvmCoverageVerification
./gradlew checkKotlinAbi dokkaGeneratePublicationHtml
./gradlew connectedAndroidDeviceTestThe common/JVM coverage gate is 85% lines and 70% branches; reports are under
core/build/reports/jacoco/. These numbers do not measure native Apple or Android execution.
CI runs real-store tests on Windows, macOS, and Linux, Android emulator tests on API 23 and 35, native macOS Keychain tests, an iOS simulator app harness that exercises the Apple stores against the data-protection keychain, Kotlin lint, Apple compilation, API compatibility, documentation, publication-consumer, and Swift interop checks.
Run desktop integration tests against a disposable namespace using:
CREDENTIAL_KEYCHAIN_INTEGRATION=1 ./gradlew jvmTest --rerun-tasksDevice-only iOS, tvOS, and watchOS behavior (Secure Enclave, lock states, reinstall, access groups with real provisioning) requires device validation; the simulator harness does not verify it.
Kotlin Multiplatform storage for API keys, tokens, and passwords, backed by platform secure storage. There is no plaintext persistence fallback: every supported platform routes through its native secure-storage facility (Android Keystore, Apple Keychain, macOS Keychain, Linux Secret Service, or Windows DPAPI), or the call throws.
This exists for apps and libraries that need one interface for things like storing an
OAuth refresh token, a scoped API key, or a user's saved username and password across
Android, iOS, macOS, tvOS, watchOS, and desktop JVM — without writing a platform-specific
secure-storage adapter for each target. CredentialKeychain stores secrets by key, and
PasswordStore stores username/password credentials per server.
read/write/delete/clear behave the same
from commonMain; each platform target resolves to its own OS-backed secure store.Context), the
library throws KeychainUnavailableException instead of writing plaintext or an
in-memory stand-in you might mistake for durable storage.reason — Unsupported, Locked,
Canceled, AuthenticationInvalidated, Corrupted, or Failed — so you can retry
later, re-prompt, or reset the store.serviceName and accountName are
bound into the storage key rather than just a bare key string.| Platform | Kotlin targets | Backend |
|---|---|---|
| Android 6.0+ (API 23+) | android |
Android Keystore AES-256-GCM; ciphertext in app-private, non-backed-up files |
| iOS |
iosArm64, iosSimulatorArm64
|
Apple Keychain, device-only, configurable accessibility |
| tvOS |
tvosArm64, tvosSimulatorArm64
|
Apple Keychain, device-only, configurable accessibility |
| watchOS |
watchosArm64, watchosDeviceArm64, watchosSimulatorArm64
|
Apple Keychain, device-only, configurable accessibility |
| macOS | macosArm64 |
File-based login keychain through the Security framework |
| macOS desktop JVM | jvm |
Login keychain through /usr/bin/security
|
| Linux desktop JVM | jvm |
Secret Service through secret-tool
|
| Windows desktop JVM | jvm |
Current-user DPAPI (secrets), Credential Manager (passwords), and the current-user certificate store, called in-process through JNA |
JVM artifacts target Java 17. Intel Apple targets (iosX64, macosX64, tvosX64,
watchosX64) are not published; Intel Macs are supported through the JVM target. Windows
and Linux support requires a JVM — there are no mingwX64, linuxX64, or linuxArm64
native backends, and no web (js, wasmJs) targets.
// build.gradle.kts
kotlin {
sourceSets.commonMain.dependencies {
implementation("io.github.maniramezan:credential-keychain-kotlin:0.1.1") // x-release-please-version
// Optional: secrets that require biometric authentication to read.
implementation("io.github.maniramezan:credential-keychain-kotlin-biometric:0.1.1") // x-release-please-version
}
}Both artifacts share one version. The biometric artifact adds androidx.biometric and
kotlinx-coroutines-core. The core artifact's JVM variant depends on
JNA (net.java.dev.jna:jna) for the Windows
backends; its other variants have no dependencies.
No extra platform dependency, manifest entry, or entitlement is required to link the
library. On macOS and Linux the desktop JVM target shells out to an OS tool (security or
secret-tool) that must be present on the machine; on Windows it calls the Win32 APIs
directly — see
Contract and requirements.
In commonMain, obtain an instance through CredentialKeychain.forCurrentPlatform(...),
which resolves to the right backend for the target being compiled.
import com.maniramezan.credentialkeychain.CredentialKeychain
// Apple native or desktop JVM:
val keychain = CredentialKeychain.forCurrentPlatform(
serviceName = "my-app",
accountName = "user-123", // defaults to serviceName
)
keychain.write("api-key", "secret-token")
val token: String? = keychain.read("api-key") // null only if absent
keychain.delete("api-key")
keychain.clear() // removes every entry for my-app/user-123Call from a worker thread or coroutine dispatcher — every operation is synchronous and a
native backend may block or prompt the user. Use the failure reason to decide what to do:
suspend fun readApiKey(keychain: CredentialKeychain): String? = withContext(Dispatchers.IO) {
try {
keychain.read("api-key")
} catch (e: KeychainUnavailableException) {
when (e.reason) {
KeychainUnavailableException.Reason.Locked -> null // retry after the device unlocks
KeychainUnavailableException.Reason.Corrupted -> { keychain.clear(); null } // re-authenticate
else -> throw e
}
}
}Inject a single CredentialKeychain into shared application code (a repository, a
ViewModel, DI graph) rather than calling forCurrentPlatform at every call site — this
is also what lets Android supply its Context-based implementation without commonMain
needing to know about Context at all:
// In androidMain:
import com.maniramezan.credentialkeychain.CredentialKeychain
import com.maniramezan.credentialkeychain.forCurrentPlatform
val keychain: CredentialKeychain = CredentialKeychain.forCurrentPlatform(
context = applicationContext,
serviceName = "my-app",
accountName = "user-123",
)The Context-free factory on Android returns an unavailable store — every call throws
KeychainUnavailableException with reason Unsupported — rather than silently working
without one. This avoids retaining an Activity or requiring global initialization just so
commonMain can call a zero-argument factory.
val keychain = CredentialKeychain.forCurrentPlatform(
serviceName = "my-app",
accountName = "user-123",
options = KeychainOptions(
appleAccessibility = AppleAccessibility.AfterFirstUnlock, // iOS/tvOS/watchOS background access
desktopCommandTimeout = 60.seconds, // macOS/Linux JVM tool timeout, including access prompts
),
)Options that don't apply to the current platform are ignored.
PasswordStore keeps username/password credentials per server, using each platform's native
password storage. It is created the same way (Android uses the Context-taking overload) and
is independent of a CredentialKeychain with the same service and account names:
val passwords = PasswordStore.forCurrentPlatform(serviceName = "my-app", accountName = "user-123")
passwords.save(PasswordCredential(server = "api.example.com", username = "alice", password = "s3cret"))
val alice: PasswordCredential? = passwords.find(server = "api.example.com", username = "alice")
val accounts: List<String> = passwords.findAll(server = "api.example.com").map { it.username } // sorted
passwords.delete(server = "api.example.com", username = "alice")
passwords.clear() // removes every password for my-app/user-123, on every serverPasswordCredential.toString() never includes the password.
HardwareKeyStore generates non-exportable ECDSA P-256 keys inside secure hardware — StrongBox
or the trusted execution environment on Android, the Secure Enclave on Apple platforms — and
signs with them. Private keys never leave the hardware:
val keys = HardwareKeyStore.forCurrentPlatform(serviceName = "my-app", accountName = "user-123")
val key: HardwareKeyInfo = keys.generate("device-binding") // replaces an existing key
server.register(key.publicKeyDer, key.securityLevel) // X.509 SubjectPublicKeyInfo
val signature: ByteArray? = keys.sign("device-binding", challenge) // DER ECDSA-SHA256; null if missing
keys.delete("device-binding")Generation fails with reason Unsupported when no secure hardware is available (emulators,
simulators, unsigned macOS tools, desktop JVM). Pass HardwareKeySpec(allowSoftwareKeys = true)
to accept software-backed keys where the platform offers them; securityLevel always reports
what you actually got. Android needs no Context for this store.
CertificateStore keeps X.509 certificates and PKCS#12 identities. Private keys go to native key
storage; certificate chains are returned as DER, leaf first:
val certificates = CertificateStore.forCurrentPlatform(serviceName = "my-app", accountName = "user-123")
val client: CertificateInfo = certificates.importPkcs12("client", pkcs12Bytes, passphrase) // replaces "client"
certificates.importCertificate("pinned-ca", caCertificateDer)
val chain: List<ByteArray>? = certificates.info("client")?.certificateChainDer
val aliases: List<String> = certificates.aliases() // sorted
certificates.delete("pinned-ca")A malformed bundle or wrong passphrase throws IllegalArgumentException; the passphrase array is
not cleared for you. Desktop JVM stores identities in the macOS login keychain, the Windows
current-user certificate store, or Linux Secret Service; Android moves private keys into Android
Keystore (use the Context-taking overload); Apple platforms store identities in the
data-protection keychain, which needs an app with keychain entitlements.
To use a stored identity for signing or client authentication, get its platform handle. Each
returns null when the alias has no entry or holds only a certificate:
// androidMain and jvmMain: feeds Signature, KeyManagerFactory, or an SSLContext
val entry: KeyStore.PrivateKeyEntry? = certificates.privateKeyEntry("client")
// appleMain: a retained SecIdentityRef for URLSession client authentication; release with CFRelease
@OptIn(ExperimentalForeignApi::class)
val identity: SecIdentityRef? = certificates.secIdentity("client")Private keys stay in native storage: Android Keystore, the macOS login keychain, the Windows
certificate store (read through the JDK Windows-MY provider), or the Apple keychain.
ProtectedKeychain, in the separate credential-keychain-kotlin-biometric artifact, stores
secrets that need a strong biometric (Android Class 3, Face ID, or Touch ID) to read. Writing,
deleting, and clearing need no authentication; read suspends while the system prompt is shown:
import com.maniramezan.credentialkeychain.biometric.AuthenticationPrompt
import com.maniramezan.credentialkeychain.biometric.ProtectedKeychain
// iOS and macOS; Android uses the overload that also takes a Context and a FragmentActivity provider.
val protected = ProtectedKeychain.forCurrentPlatform(serviceName = "my-app", accountName = "user-123")
protected.write("refresh-token", token)
val prompt = AuthenticationPrompt(title = "Unlock your account", cancelLabel = "Cancel")
try {
val token: String? = protected.read("refresh-token", prompt) // null if never written
} catch (error: KeychainUnavailableException) {
when (error.reason) {
Reason.Canceled -> Unit // the user dismissed the prompt
Reason.AuthenticationInvalidated -> protected.delete("refresh-token") // enrollment changed; sign in again
else -> throw error
}
}Entries are invalidated when biometric enrollment changes. Android needs API 23+; iOS 15+ and
macOS 12+ apps need keychain entitlements, and iOS apps that use Face ID need
NSFaceIDUsageDescription. On tvOS, watchOS, and desktop JVM every operation throws
Reason.Unsupported. The iOS simulator does not enforce biometric access control, so validate
prompts and enrollment changes on a device.
Namespacing by accountName keeps one secure entry set per signed-in user without
encoding the user id into each key yourself:
fun keychainFor(userId: String): CredentialKeychain =
CredentialKeychain.forCurrentPlatform(serviceName = "com.example.myapp", accountName = userId)
fun saveTokens(userId: String, accessToken: String, refreshToken: String) {
val keychain = keychainFor(userId)
keychain.write("access-token", accessToken)
keychain.write("refresh-token", refreshToken)
}
fun signOut(userId: String) {
keychainFor(userId).clear()
}// commonMain
@Composable
fun ApiKeyScreen(keychain: CredentialKeychain) {
var apiKey by remember { mutableStateOf<String?>(null) }
LaunchedEffect(keychain) {
apiKey = withContext(Dispatchers.Default) { keychain.read("api-key") }
}
// render apiKey / a form that calls keychain.write("api-key", input) on submit
}
// androidMain composition root
val context = LocalContext.current.applicationContext
val keychain = remember(context) { CredentialKeychain.forCurrentPlatform(context, "my-app") }
ApiKeyScreen(keychain)
// iosMain composition root
val keychain = remember { CredentialKeychain.forCurrentPlatform(serviceName = "my-app") }
ApiKeyScreen(keychain)Consumed from Swift, a CredentialKeychain created through your KMP framework works
unchanged:
let keychain = try CredentialKeychainCompanion.shared.forCurrentPlatform(serviceName: "my-app", accountName: "user-123")
try keychain.write(key: "api-key", value: "secret-token")
let token = try keychain.read(key: "api-key")
try keychain.clear()
let passwords = try PasswordStoreCompanion.shared.forCurrentPlatform(serviceName: "my-app", accountName: "user-123")
try passwords.save(credential: PasswordCredential(server: "api.example.com", username: "alice", password: "s3cret"))
let alice = try passwords.find(server: "api.example.com", username: "alice")Export this dependency from your consuming Kotlin framework before importing it in
Swift; this package publishes KLIBs, not a standalone Swift framework. Generated names
can vary with your framework configuration. Every operation declares @Throws, so Swift
callers handle failures with do/catch.
On iOS, tvOS, and watchOS, entries are device-only, never iCloud-synchronized, and readable
according to appleAccessibility. The default, WhenUnlocked, makes reads fail with
reason Locked while the device is locked; use AfterFirstUnlock for background refresh.
Changing the option on a later write updates the existing entry.
On macOS, Kotlin/Native entries live in the file-based login keychain, which does not
support accessibility classes: appleAccessibility is ignored, and access is controlled by
the keychain's per-item access list, which trusts the application that created the item.
This works for unsigned tools; macOS may prompt when a differently signed build reads an
existing item.
The same forCurrentPlatform(serviceName, accountName) call is used; the OS the JVM runs
on selects the backend (see the platform table):
// jvmMain — works unmodified on macOS, Linux, or Windows
val keychain = CredentialKeychain.forCurrentPlatform("my-cli-tool")
keychain.write("github-token", token)null for absent entries. Unavailable backends and operational failures
throw KeychainUnavailableException; do not interpret them as missing credentials.
Unsupported — no usable backend in this platform or environment.Locked — the store is locked or access was denied; retrying later may succeed.Canceled — the user dismissed an access prompt; retry only on user action.AuthenticationInvalidated — the protecting key was permanently invalidated (for
example, biometric enrollment changed); delete the entry or clear().Corrupted — data exists but can't be decrypted or decoded; delete the entry or clear().Failed — any other failure, such as an I/O error or timeout.write stores values exactly, including surrounding whitespace. Blank values throw
IllegalArgumentException; call delete to remove an entry.security backend additionally rejects CR/LF in values.
Native Apple and Android backends accept multiline secrets.PasswordStore applies the same rules on every platform so credentials stay portable:
servers and usernames are nonblank without NUL, CR, or LF; usernames are at most 512
characters; passwords are nonblank, without NUL, CR, or LF, and at most 2,560 UTF-8 bytes
(the Windows Credential Manager limit). save replaces an existing password, and
findAll returns credentials sorted by username.findAll
lists usernames from security dump-keychain, which reads attributes but not passwords.HardwareKeyStore keys are ECDSA P-256; signatures are DER-encoded ECDSA with SHA-256 and
verify with SHA256withECDSA. Android prefers StrongBox (API 28+) and falls back to the TEE;
before API 31 it reports hardware keys as TrustedEnvironment even when StrongBox-backed.
Apple Secure Enclave keys require a signed app (the data-protection keychain); unsigned macOS
processes can only use opt-in software keys in the login keychain. Desktop JVM always throws
Unsupported.CertificateStore accepts PKCS#12 bundles with exactly one private key and DER certificates,
each at most 1 MiB. Chains and the alias index are kept in the platform's secret storage under
a separate "certificates" namespace; aliases() is not transactional across processes. On
desktop JVM, identities go to the macOS login keychain (JDK KeychainStore), the Windows
current-user My store with a non-exportable key (removed with its key container), or Linux
Secret Service as a re-encoded PKCS#12 bundle, where bundles over 8 KiB fail with Unsupported.
On Android, private keys are imported into Android Keystore as non-exportable keys: EC keys
may sign, RSA keys may sign and decrypt (PKCS#1, PSS, OAEP). Other key algorithms are rejected.
On Apple platforms, bundles are decoded in memory and the identity (certificate and private key)
is stored in the data-protection keychain under a namespaced label. Unsigned macOS processes
cannot use that keychain and get Unsupported, and macOS identities need macOS 15 or later.
One identity can back only one alias per keychain; importing it under a second alias fails.Corrupted
(existing ciphertext is never silently replaced) until you delete the affected entries
or clear() the store.secret-tool and an accessible Secret Service session (for example,
GNOME Keyring). Headless sessions may not have one. Credentials should stay below
8 KiB, the input limit of commonly deployed secret-tool versions.CryptProtectData, the
Credential Manager (Cred*W), and CryptoAPI in-process through JNA, without launching a
helper process. Ciphertext lives under %LOCALAPPDATA%\credential-keychain\ in hashed
service/account and key paths. DPAPI binds decryption to the Windows user, not to a
particular application. On JDK 24 and later, JNA's native access prints a warning unless the
application is started with --enable-native-access=ALL-UNNAMED (or =com.sun.jna on the
module path).desktopCommandTimeout (30 seconds by default).
Secrets are supplied through stdin, and backend error output is never included in exceptions.The library relies on each platform's secure storage and does not add protection beyond
it. In particular, on desktop JVM any process running as the same OS user can read the
stored credentials: macOS items created through /usr/bin/security trust that tool, so
security find-generic-password can read them without a prompt; unlocked Secret Service
collections are available to the whole session; and DPAPI and Credential Manager decrypt
for any process of the same Windows user. Service and account names prevent collisions — they are not an
authorization boundary. See SECURITY.md for the full model and for
reporting vulnerabilities.
Building requires JDK 21, Android SDK 36, and the Gradle wrapper; the published JVM artifacts run on Java 17+. A macOS host with a compatible Xcode is required to build the Apple artifacts.
./gradlew jvmTest
./gradlew assemble macosArm64Test
./gradlew publishToMavenLocalAfter local publication, a consuming KMP project can add mavenLocal() to its repositories
and depend on the same coordinates shown in Installation. The library
lives in core/, with shared build configuration in build-logic/. Each module creates
the KMP metadata publication and 10 platform publications; publish the complete set when
distributing the library.
IntelliJ IDEA and Android Studio load shared run configurations from .run/: Build All, JVM
Tests, Android Device Tests (pinned to emulator-5554 with ANDROID_SERIAL), desktop
integration tests (macOS uses a disposable keychain), and the verification consumer build.
./gradlew ktlintCheck jvmCoverageVerification
./gradlew checkKotlinAbi dokkaGeneratePublicationHtml
./gradlew connectedAndroidDeviceTestThe common/JVM coverage gate is 85% lines and 70% branches; reports are under
core/build/reports/jacoco/. These numbers do not measure native Apple or Android execution.
CI runs real-store tests on Windows, macOS, and Linux, Android emulator tests on API 23 and 35, native macOS Keychain tests, an iOS simulator app harness that exercises the Apple stores against the data-protection keychain, Kotlin lint, Apple compilation, API compatibility, documentation, publication-consumer, and Swift interop checks.
Run desktop integration tests against a disposable namespace using:
CREDENTIAL_KEYCHAIN_INTEGRATION=1 ./gradlew jvmTest --rerun-tasksDevice-only iOS, tvOS, and watchOS behavior (Secure Enclave, lock states, reinstall, access groups with real provisioning) requires device validation; the simulator harness does not verify it.