{"id":13773134,"url":"https://github.com/adorsys/secure-storage-android","last_synced_at":"2025-04-05T00:04:25.883Z","repository":{"id":50455196,"uuid":"86683720","full_name":"adorsys/secure-storage-android","owner":"adorsys","description":"Store strings \u0026 credentials securely encrypted on your device","archived":false,"fork":false,"pushed_at":"2021-01-14T11:29:26.000Z","size":4248,"stargazers_count":361,"open_issues_count":15,"forks_count":58,"subscribers_count":14,"default_branch":"master","last_synced_at":"2024-04-28T23:03:54.963Z","etag":null,"topics":["android","android-keystore","android-storage","encryption","library","securepreferences","securestorage"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adorsys.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-30T09:20:56.000Z","updated_at":"2024-04-27T12:05:27.000Z","dependencies_parsed_at":"2022-08-31T03:01:17.260Z","dependency_job_id":null,"html_url":"https://github.com/adorsys/secure-storage-android","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adorsys%2Fsecure-storage-android","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adorsys%2Fsecure-storage-android/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adorsys%2Fsecure-storage-android/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adorsys%2Fsecure-storage-android/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adorsys","download_url":"https://codeload.github.com/adorsys/secure-storage-android/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247266563,"owners_count":20910836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","android-keystore","android-storage","encryption","library","securepreferences","securestorage"],"created_at":"2024-08-03T17:01:11.850Z","updated_at":"2025-04-05T00:04:25.850Z","avatar_url":"https://github.com/adorsys.png","language":"Java","readme":"# Secure Device Storage - Android\n\n## Storing Credentials Securely on Android Devices\n\n[![Actions Status](https://github.com/adorsys/secure-storage-android/workflows/SecureStorage%20Pull%20Request%20Workflow/badge.svg)](https://github.com/adorsys/secure-storage-android/actions)\n[![Download](https://api.bintray.com/packages/andev/adorsys/securestoragelibrary/images/download.svg) ](https://bintray.com/andev/adorsys/securestoragelibrary/_latestVersion) \n[![Android Arsenal](https://img.shields.io/badge/Android%20Arsenal-Secure%20Storage%20Android-blue.svg?style=flat)](https://android-arsenal.com/details/1/5648)\n[![API](https://img.shields.io/badge/API-18%2B-blue.svg?style=flat)](https://android-arsenal.com/api?level=18)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) \n[![Open Source Love](https://badges.frapsoft.com/os/v1/open-source.svg?v=103)](https://github.com/ellerbrock/open-source-badges/)\n\n\n\n### Introduction\n\nStoring credentials securely on a device is in many occasions necessary. You probably don't want to rely only on the separation of processes of the Android OS but make sure the stored values are also encrypted.\nTo make that possible we have combined the Android Keystore and the SharedPreferences. The keystore is used for generating cryptographic keys, the values are then encrypted with these keys and subsequently securely stored in the SharedPreferences.\n\nThe secure part about this solution is that those generated keys are never exposed to the kernel when the device is equipped with a “Trusted Execution Environment”. A so called TEE is a secure area inside the main processor of a smartphone which runs code isolated from other processes. That means even if the device gets compromised or hacked those keys can’t be extracted. Already a lot of modern Android phones out there are equipped with a TEE (mostly because it’s often used to play DRM protected material) and it even is a requirement for Google’s Android Nougat certification — so every phone running Android Nougat and later will come with a TEE installed.\n\nSecureStorage uses its own dedicated private SharedPreferences to prevent conflicts with other possible SharedPreference instances and ensure that the content of the SecureStorage can only be accessed from the app which uses this library.\n\n### Supported API's\n\n__Symmetric__ key generation and storage in the Android KeyStore is supported from __Android 6.0 (API Level 23) onwards.__\n__Asymmetric__ key generation and storage in the Android KeyStore is supported from __Android 4.3 (API Level 18) onwards.__\n\nTo support more devices SecureStorage uses for now the asymmetric key generation, which in the case of storing simple credentials is very secure and the potential lack of speed in contrast to symmetric key generation, is not noticeable. Nevertheless, make sure to move the execution into a background thread as encryption does take a little time.\n\n### Usage\n\nAdd the library to your apps build.gradle:\n\n```groovy\nimplementation \"de.adorsys.android:securestoragelibrary:${latestSecureStorageVersion}\"\n```\n\nTo store a string value in your __SecureStorage__ you have to call:\n```kotlin\nSecurePreferences.setValue(context, \"KEY\", \"PLAIN_MESSAGE\")\n```\n\nThis works for every other primitive data type. So for storing a boolean value:\n```kotlin\nSecurePreferences.setValue(context, \"KEY\", true/false)\n```\n\nfor int\n```kotlin\nSecurePreferences.setValue(context, \"KEY\", 100)\n```\n\nfor float and long\n```kotlin\nSecurePreferences.setValue(context, \"KEY\", 100.12345)\n```\n\nTo retrieve a string value:\n```kotlin\nSecurePreferences.getStringValue(context, \"KEY\", \"\"/null)\n```\n\nAnd respectively for the other types\n```kotlin\nSecurePreferences.getBooleanValue(context, \"KEY\", false/true)\n```\n```kotlin\nSecurePreferences.getIntValue(context, \"KEY\", 0)\n```\n```kotlin\nSecurePreferences.getFloatValue(context, \"KEY\", 0F)\n```\n```kotlin\nSecurePreferences.getLongValue(context, \"KEY\", 0L)\n```\n\nSee if an entry exists in the SecurePreferences. Also returns `false` if the key pair does not exist:\n```kotlin\nSecurePreferences.contains(context, \"KEY\")\n```\n\nYou can also remove an entry from the SecurePreferences:\n```kotlin\nSecurePreferences.removeValue(context, \"KEY\")\n```\n\nClearing the SecurePreferences and deleting the KeyPair:\n```kotlin\nSecurePreferences.clearAllValues(context)\n```\n\nEverything about the cryptographic keys such as generating, maintaining and usage is handled internally by the module, so you do not need to worry about it.\n\nIf you want to keep track of changes in your SecureStorage you can register an OnSharedPreferencesChangeListener as follows:\n\n``` kotlin\nval listener = SharedPreferences.OnSharedPreferenceChangeListener { _, key -\u003e\n    // check if the key is the one you are listening for and react\n}\nSecurePreferences.registerOnSharedPreferenceChangeListener(this, listener)\n```\nUnregister the listener as soon as you don't need it any more with\n``` kotlin\nSecurePreferences.unregisterOnSharedPreferenceChangeListener(context, listener)\n```\n\n\n### Error handling\nThe library throws for everything a SecureStorageException. Within the SecureStorageException you can find a exception type. You can handle the error which occurred with the help of this type as follows:\n\n```kotlin\ntry {\n    SecurePreferences.setValue(context, KEY, \"Secret\")\n    // or\n    val decryptedMessage = SecurePreferences.getStringValue(context, KEY, \"\")\n} catch (e: SecureStorageException) {\n    handleException(e)\n}\n//\nprivate fun handleException(e: SecureStorageException) {\n    Log.e(TAG, e.message)\n    when (e.type) {\n        KEYSTORE_NOT_SUPPORTED_EXCEPTION -\u003e Toast.makeText(this, \"Oh\", Toast.LENGTH_LONG).show()\n        KEYSTORE_EXCEPTION -\u003e Toast.makeText(this, \"Fatal - YARK\", Toast.LENGTH_LONG).show()\n        CRYPTO_EXCEPTION -\u003e Toast.makeText(this, \"2h\u0026$==0j\", Toast.LENGTH_LONG).show()\n        INTERNAL_LIBRARY_EXCEPTION -\u003e Toast.makeText(this, \"Blame it all on us\", Toast.LENGTH_LONG).show()\n        else -\u003e return\n    }\n}\n```\n\n### Contributors:\n[@drilonrecica](https://github.com/drilonrecica)\n\n[@luckyhandler](https://github.com/luckyhandler)\n\n### Want to know more:\n\nThese links cover security aspect of the android keystore:\n\u003chttps://developer.android.com/training/articles/keystore.html#SecurityFeatures\u003e\n\u003chttps://source.android.com/security/keystore/\u003e\n\u003chttps://codingquestion.blogspot.de/2016/09/how-to-use-android-keystore-api-with.html\u003e\n\u003chttp://nelenkov.blogspot.de/2012/05/storing-application-secrets-in-androids.html\u003e\n\u003chttp://nelenkov.blogspot.de/2015/06/keystore-redesign-in-android-m.html\u003e\n\u003chttp://www.androidauthority.com/use-android-keystore-store-passwords-sensitive-information-623779/\u003e  \n\nThis link covers security aspect of the android storage:\n\u003chttps://developer.android.com/guide/topics/data/data-storage.html\u003e\n\u003chttp://stackoverflow.com/a/26077852/3392276\u003e","funding_links":[],"categories":["Android"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadorsys%2Fsecure-storage-android","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadorsys%2Fsecure-storage-android","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadorsys%2Fsecure-storage-android/lists"}