credential-keychain-kotlin
Secure credential storage for Kotlin Multiplatform applications. com.maniramezan.credentialkeychain.CredentialKeychain stores secrets by key (read, write, delete, clear), and com.maniramezan.credentialkeychain.PasswordStore stores username/password credentials per server (save, find, findAll, delete, clear). Both are backed by each platform's native secure storage:
Android — Android Keystore, AES-256-GCM, ciphertext in an app-private, non-backed-up file.
iOS, tvOS, watchOS — the native Apple Keychain, device-only and never iCloud-synchronized, readable according to com.maniramezan.credentialkeychain.AppleAccessibility.
macOS (Kotlin/Native) — the file-based login keychain through the Security framework. macOS ignores the accessibility setting for this keychain.
macOS desktop JVM — the login keychain through
/usr/bin/security.Linux desktop JVM — Secret Service (for example GNOME Keyring) through
secret-tool.Windows desktop JVM — current-user DPAPI for secrets, Credential Manager for passwords, and the current-user certificate store, called in-process through JNA.
No platform falls back to plaintext persistence: an unavailable or failing backend always throws rather than silently writing to a less secure location.
Quick start
import com.maniramezan.credentialkeychain.CredentialKeychain
val credentials = CredentialKeychain.forCurrentPlatform("my-app", "user-123")
credentials.write("api-token", "secret")
val token = credentials.read("api-token") // null only if absent
credentials.delete("api-token")
credentials.clear() // removes every entry for my-app/user-123
val passwords = PasswordStore.forCurrentPlatform("my-app", "user-123")
passwords.save(PasswordCredential(server = "api.example.com", username = "alice", password = "s3cret"))
val alice = passwords.find(server = "api.example.com", username = "alice")
val accounts = passwords.findAll(server = "api.example.com").map { it.username }On Android, import com.maniramezan.credentialkeychain.forCurrentPlatform and use the overload that takes context = applicationContext — the Context-free overload on Android always returns a store that throws KeychainUnavailableException, by design. Inject the resulting CredentialKeychain into shared code (a repository, a ViewModel, your DI graph) rather than calling forCurrentPlatform at every call site.
Operations are synchronous and may block or prompt the user: call them from a worker thread or a background coroutine dispatcher, never the UI thread.
Semantics worth knowing before you integrate
nullfromreadmeans the entry is absent. Failures always throwKeychainUnavailableException, whosereasonisUnsupported,Locked,Canceled,AuthenticationInvalidated,Corrupted, orFailed.writestores values exactly, including surrounding whitespace. Blank values are rejected withIllegalArgumentException; calldeleteto remove an entry.Deleting a missing key, or clearing an empty store, succeeds when the backend is available.
Identifiers (
serviceName,accountName, and eachkey) must be nonblank and must not contain NUL, CR, or LF. Values must not contain NUL; macOS JVM additionally rejects CR/LF.Entries are namespaced by both
serviceNameandaccountName, so one process can keep separate stores per app, environment, or signed-in user. ACredentialKeychainand aPasswordStorewith the same names never see or clear each other's entries.Password credentials follow the same rules everywhere: 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.
PasswordCredential.toString()redacts the password.
Full usage and platform guide
See the usage and platform guide for installation, per-OS runtime requirements, worked examples, and the security model.
Secure credential storage for Kotlin Multiplatform applications. com.maniramezan.credentialkeychain.CredentialKeychain stores secrets by key (read, write, delete, clear), and com.maniramezan.credentialkeychain.PasswordStore stores username/password credentials per server (save, find, findAll, delete, clear). Both are backed by each platform's native secure storage:
Android — Android Keystore, AES-256-GCM, ciphertext in an app-private, non-backed-up file.
iOS, tvOS, watchOS — the native Apple Keychain, device-only and never iCloud-synchronized, readable according to com.maniramezan.credentialkeychain.AppleAccessibility.
macOS (Kotlin/Native) — the file-based login keychain through the Security framework. macOS ignores the accessibility setting for this keychain.
macOS desktop JVM — the login keychain through
/usr/bin/security.Linux desktop JVM — Secret Service (for example GNOME Keyring) through
secret-tool.Windows desktop JVM — current-user DPAPI for secrets, Credential Manager for passwords, and the current-user certificate store, called in-process through JNA.
No platform falls back to plaintext persistence: an unavailable or failing backend always throws rather than silently writing to a less secure location.
Quick start
import com.maniramezan.credentialkeychain.CredentialKeychain
val credentials = CredentialKeychain.forCurrentPlatform("my-app", "user-123")
credentials.write("api-token", "secret")
val token = credentials.read("api-token") // null only if absent
credentials.delete("api-token")
credentials.clear() // removes every entry for my-app/user-123
val passwords = PasswordStore.forCurrentPlatform("my-app", "user-123")
passwords.save(PasswordCredential(server = "api.example.com", username = "alice", password = "s3cret"))
val alice = passwords.find(server = "api.example.com", username = "alice")
val accounts = passwords.findAll(server = "api.example.com").map { it.username }On Android, import com.maniramezan.credentialkeychain.forCurrentPlatform and use the overload that takes context = applicationContext — the Context-free overload on Android always returns a store that throws KeychainUnavailableException, by design. Inject the resulting CredentialKeychain into shared code (a repository, a ViewModel, your DI graph) rather than calling forCurrentPlatform at every call site.
Operations are synchronous and may block or prompt the user: call them from a worker thread or a background coroutine dispatcher, never the UI thread.
Semantics worth knowing before you integrate
nullfromreadmeans the entry is absent. Failures always throwKeychainUnavailableException, whosereasonisUnsupported,Locked,Canceled,AuthenticationInvalidated,Corrupted, orFailed.writestores values exactly, including surrounding whitespace. Blank values are rejected withIllegalArgumentException; calldeleteto remove an entry.Deleting a missing key, or clearing an empty store, succeeds when the backend is available.
Identifiers (
serviceName,accountName, and eachkey) must be nonblank and must not contain NUL, CR, or LF. Values must not contain NUL; macOS JVM additionally rejects CR/LF.Entries are namespaced by both
serviceNameandaccountName, so one process can keep separate stores per app, environment, or signed-in user. ACredentialKeychainand aPasswordStorewith the same names never see or clear each other's entries.Password credentials follow the same rules everywhere: 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.
PasswordCredential.toString()redacts the password.
Full usage and platform guide
See the usage and platform guide for installation, per-OS runtime requirements, worked examples, and the security model.
Secure credential storage for Kotlin Multiplatform applications. com.maniramezan.credentialkeychain.CredentialKeychain stores secrets by key (read, write, delete, clear), and com.maniramezan.credentialkeychain.PasswordStore stores username/password credentials per server (save, find, findAll, delete, clear). Both are backed by each platform's native secure storage:
Android — Android Keystore, AES-256-GCM, ciphertext in an app-private, non-backed-up file.
iOS, tvOS, watchOS — the native Apple Keychain, device-only and never iCloud-synchronized, readable according to com.maniramezan.credentialkeychain.AppleAccessibility.
macOS (Kotlin/Native) — the file-based login keychain through the Security framework. macOS ignores the accessibility setting for this keychain.
macOS desktop JVM — the login keychain through
/usr/bin/security.Linux desktop JVM — Secret Service (for example GNOME Keyring) through
secret-tool.Windows desktop JVM — current-user DPAPI for secrets, Credential Manager for passwords, and the current-user certificate store, called in-process through JNA.
No platform falls back to plaintext persistence: an unavailable or failing backend always throws rather than silently writing to a less secure location.
Quick start
import com.maniramezan.credentialkeychain.CredentialKeychain
val credentials = CredentialKeychain.forCurrentPlatform("my-app", "user-123")
credentials.write("api-token", "secret")
val token = credentials.read("api-token") // null only if absent
credentials.delete("api-token")
credentials.clear() // removes every entry for my-app/user-123
val passwords = PasswordStore.forCurrentPlatform("my-app", "user-123")
passwords.save(PasswordCredential(server = "api.example.com", username = "alice", password = "s3cret"))
val alice = passwords.find(server = "api.example.com", username = "alice")
val accounts = passwords.findAll(server = "api.example.com").map { it.username }On Android, import com.maniramezan.credentialkeychain.forCurrentPlatform and use the overload that takes context = applicationContext — the Context-free overload on Android always returns a store that throws KeychainUnavailableException, by design. Inject the resulting CredentialKeychain into shared code (a repository, a ViewModel, your DI graph) rather than calling forCurrentPlatform at every call site.
Operations are synchronous and may block or prompt the user: call them from a worker thread or a background coroutine dispatcher, never the UI thread.
Semantics worth knowing before you integrate
nullfromreadmeans the entry is absent. Failures always throwKeychainUnavailableException, whosereasonisUnsupported,Locked,Canceled,AuthenticationInvalidated,Corrupted, orFailed.writestores values exactly, including surrounding whitespace. Blank values are rejected withIllegalArgumentException; calldeleteto remove an entry.Deleting a missing key, or clearing an empty store, succeeds when the backend is available.
Identifiers (
serviceName,accountName, and eachkey) must be nonblank and must not contain NUL, CR, or LF. Values must not contain NUL; macOS JVM additionally rejects CR/LF.Entries are namespaced by both
serviceNameandaccountName, so one process can keep separate stores per app, environment, or signed-in user. ACredentialKeychainand aPasswordStorewith the same names never see or clear each other's entries.Password credentials follow the same rules everywhere: 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.
PasswordCredential.toString()redacts the password.
Full usage and platform guide
See the usage and platform guide for installation, per-OS runtime requirements, worked examples, and the security model.
Secure credential storage for Kotlin Multiplatform applications. com.maniramezan.credentialkeychain.CredentialKeychain stores secrets by key (read, write, delete, clear), and com.maniramezan.credentialkeychain.PasswordStore stores username/password credentials per server (save, find, findAll, delete, clear). Both are backed by each platform's native secure storage:
Android — Android Keystore, AES-256-GCM, ciphertext in an app-private, non-backed-up file.
iOS, tvOS, watchOS — the native Apple Keychain, device-only and never iCloud-synchronized, readable according to com.maniramezan.credentialkeychain.AppleAccessibility.
macOS (Kotlin/Native) — the file-based login keychain through the Security framework. macOS ignores the accessibility setting for this keychain.
macOS desktop JVM — the login keychain through
/usr/bin/security.Linux desktop JVM — Secret Service (for example GNOME Keyring) through
secret-tool.Windows desktop JVM — current-user DPAPI for secrets, Credential Manager for passwords, and the current-user certificate store, called in-process through JNA.
No platform falls back to plaintext persistence: an unavailable or failing backend always throws rather than silently writing to a less secure location.
Quick start
import com.maniramezan.credentialkeychain.CredentialKeychain
val credentials = CredentialKeychain.forCurrentPlatform("my-app", "user-123")
credentials.write("api-token", "secret")
val token = credentials.read("api-token") // null only if absent
credentials.delete("api-token")
credentials.clear() // removes every entry for my-app/user-123
val passwords = PasswordStore.forCurrentPlatform("my-app", "user-123")
passwords.save(PasswordCredential(server = "api.example.com", username = "alice", password = "s3cret"))
val alice = passwords.find(server = "api.example.com", username = "alice")
val accounts = passwords.findAll(server = "api.example.com").map { it.username }On Android, import com.maniramezan.credentialkeychain.forCurrentPlatform and use the overload that takes context = applicationContext — the Context-free overload on Android always returns a store that throws KeychainUnavailableException, by design. Inject the resulting CredentialKeychain into shared code (a repository, a ViewModel, your DI graph) rather than calling forCurrentPlatform at every call site.
Operations are synchronous and may block or prompt the user: call them from a worker thread or a background coroutine dispatcher, never the UI thread.
Semantics worth knowing before you integrate
nullfromreadmeans the entry is absent. Failures always throwKeychainUnavailableException, whosereasonisUnsupported,Locked,Canceled,AuthenticationInvalidated,Corrupted, orFailed.writestores values exactly, including surrounding whitespace. Blank values are rejected withIllegalArgumentException; calldeleteto remove an entry.Deleting a missing key, or clearing an empty store, succeeds when the backend is available.
Identifiers (
serviceName,accountName, and eachkey) must be nonblank and must not contain NUL, CR, or LF. Values must not contain NUL; macOS JVM additionally rejects CR/LF.Entries are namespaced by both
serviceNameandaccountName, so one process can keep separate stores per app, environment, or signed-in user. ACredentialKeychainand aPasswordStorewith the same names never see or clear each other's entries.Password credentials follow the same rules everywhere: 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.
PasswordCredential.toString()redacts the password.
Full usage and platform guide
See the usage and platform guide for installation, per-OS runtime requirements, worked examples, and the security model.