{"id":17210955,"url":"https://github.com/mauin/rxfingerprint","last_synced_at":"2025-04-06T00:09:21.783Z","repository":{"id":47260250,"uuid":"47502698","full_name":"Mauin/RxFingerprint","owner":"Mauin","description":"Android Fingerprint authentication and encryption with RxJava","archived":false,"fork":false,"pushed_at":"2021-09-06T09:14:01.000Z","size":515,"stargazers_count":379,"open_issues_count":29,"forks_count":82,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-03-29T23:09:14.849Z","etag":null,"topics":["android","encryption","fingerprint","fingerprint-authentication","fingerprint-sensor","rxjava","rxjava2"],"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/Mauin.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":"2015-12-06T15:41:10.000Z","updated_at":"2024-11-23T07:51:41.000Z","dependencies_parsed_at":"2022-09-07T07:40:47.652Z","dependency_job_id":null,"html_url":"https://github.com/Mauin/RxFingerprint","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mauin%2FRxFingerprint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mauin%2FRxFingerprint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mauin%2FRxFingerprint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mauin%2FRxFingerprint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mauin","download_url":"https://codeload.github.com/Mauin/RxFingerprint/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247415967,"owners_count":20935387,"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","encryption","fingerprint","fingerprint-authentication","fingerprint-sensor","rxjava","rxjava2"],"created_at":"2024-10-15T02:55:53.219Z","updated_at":"2025-04-06T00:09:21.766Z","avatar_url":"https://github.com/Mauin.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RxFingerprint: Android Fingerprint Authentication and Encryption in RxJava2\n\nRxFingerprint wraps the Android Fingerprint APIs (introduced in Android Marshmallow) and makes it easy to:\n- Authenticate your users with their fingerprint\n- Encrypt and decrypt their data with fingerprint authentication\n\nLearn more about the Android Fingerprint APIs at \u003ca href=\"https://developer.android.com/about/versions/marshmallow/android-6.0.html#fingerprint-authentication\"\u003edeveloper.android.com\u003c/a\u003e.\n\nThis library has a minSdkVersion of `15`, but will only really work on API level `23`. Below that it will provide no functionality due to the missing APIs.\n\n## Usage\n\nTo use RxFingerprint in your project, add the library as a dependency in your `build.gradle` file:\n```groovy\ndependencies {\n    compile 'com.mtramin:rxfingerprint:2.2.1'\n}\n```\n\nFurthermore, you have to declare the Fingerprint permission in your `AndroidManifest.xml`:\n```xml\n\u003cuses-permission android:name=\"android.permission.USE_FINGERPRINT\" /\u003e\n```\n\n### Checking for availability\n\nBefore using any fingerprint related operations it should be verified that `RxFingerprint` can be used by calling:\n\n``` java\nif (RxFingerprint.isAvailable(this)) {\n    // proceed with fingerprint operation\n} else {\n    // fingerprint is not available\n}\n```\n\nReasons for `RxFingerprint` to report that it is not available include:\n- The current device doesn't have a fingerprint sensor\n- The user is not using the fingerprint sensor of the device\n- The device is running an Android version that doesn't support the Android Fingerprint APIs\n\n### Authenticating a user with their fingerprint\n\nTo authenticate the user with their fingerprint, call the following:\n\n``` java\nDisposable disposable = RxFingerprint.authenticate(this)\n                .subscribe(fingerprintAuthenticationResult -\u003e {\n                    switch (fingerprintAuthenticationResult.getResult()) {\n                        case FAILED:\n                            setStatusText(\"Fingerprint not recognized, try again!\");\n                            break;\n                        case HELP:\n                            setStatusText(fingerprintAuthenticationResult.getMessage());\n                            break;\n                        case AUTHENTICATED:\n                            setStatusText(\"Successfully authenticated!\");\n                            break;\n                    }\n                }, throwable -\u003e {\n                    Log.e(\"ERROR\", \"authenticate\", throwable);\n                });\n```\n\nBy subscribing to `RxFingerprint.authenticate(Context)` the fingerprint sensor of the device will be activated and it will wait for the user to touch it with one of their registered fingerprints.\nShould the device not contain a fingerprint sensor or the user has not enrolled any fingerprints, `onError` will be called.\n\nAfter successful authentication or a recoverable error (e.g. the sensor could not read the fingerprint clearly) `onNext` will be called. You should check the result to see if the authentication was successful.\nIn the case of a recoverable error the value provded to `onNext` contains a helpful message that can be shown to the user and the user can try again.\n\nBy disposing the `Disposable`, the fingerprint sensor will be disabled again with no result.\n\n### Encryption-and-decryption\n\nUsage of the Encryption and decryption features of RxFingerprint are very similar to simple authentication calls.\n\n`RxFingerprint` supports encryption with both the AES and RSA encryption standards. They differ in the way the user needs to interact with their fingerprint sensor.\nFor encryption and decryption the same `EncryptionMethod` should be used. Otherwise the encrypted data cannot be decrypted.\n\nEncryption and Decryption in RxFingerprint is backed by the [Android KeyStore System](https://developer.android.com/training/articles/keystore.html).\n\nAfter the encryption step all results will be Base64 encoded for easier transportation and storage.\n \n#### AES\n\nWhen choosing AES for encryption and decryption the user will have to approve both actions by authentication with their fingerprint by touching the fingerprint sensor.\nThe encryption then relies on the [Advanced Encryption Standard](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) with a 256-bit keysize.\n\nThe usage flow for AES is as follows:\n- Call `RxFingerprint.encrypt(EncryptionMethod.AES, ...)` to initialize the encryption flow\n- User authenticates by touching the fingerprint sensor\n- Store the encrypted data returned in the `onNext` callback\n\n- Call `RxFingerprint.decrypt(EncryptionMethod.AES, ...)` to initialize the decryption flow\n- User authenticates by touching the fingerprint sensor\n- Receive the decrypted data in the `onNext` callback\n\n#### RSA\n\n[RSA](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) encryption allows you to encrypt a value without any user action. The data to encrypt can be encrypted and a user won't need to authenticate oneself by touching the fingerprint sensor.\nThe encrypted data can only be decrypted again when the user authenticates by using the fingerprint sensor on their device.\n\n\nThe usage flow for AES is as follows:\n- Call `RxFingerprint.encrypt(EncryptionMethod.RSA, ...)` to initialize the encryption flow\n- Store the encrypted data returned in the `onNext` callback\n\n- Call `RxFingerprint.decrypt(EncryptionMethod.RSA, ...)` to initialize the decryption flow\n- User authenticates by touching the fingerprint sensor\n- Receive the decrypted data in the `onNext` callback\n\n\n#### Encrypting and decrypting values\n\n``` java\nDisposable disposable = RxFingerprint.encrypt(EncryptionMethod.RSA, this, keyName, stringToEncrypt)\n                   .subscribe(encryptionResult -\u003e {\n                       switch (encryptionResult.getResult()) {\n                           case FAILED:\n                               setStatusText(\"Fingerprint not recognized, try again!\");\n                               break;\n                           case HELP:\n                               setStatusText(encryptionResult.getMessage());\n                               break;\n                           case AUTHENTICATED:\n                               setStatusText(\"Successfully authenticated!\");\n                               break;\n                       }\n                   }, throwable -\u003e {\n                       Log.e(\"ERROR\", \"authenticate\", throwable);\n                       setStatusText(throwable.getMessage());\n                   });\n```\n\n`RxFingerprint.encrypt(EncryptionMethod, Context, String, String)` takes the String you want to encrypt (which might be a token, user password, or any other String) and a key name.\nThe given String will be encrypted with a key in the Android KeyStore and returns an encrypted String. The key used in the encryption is only accessible from your own app.\nStore the encrypted String anywhere and use it later to decrypt the original value by calling:\n\n``` java\nDisposable disposable = RxFingerprint.decrypt(EncryptionMethod.RSA, this, keyName, encryptedValue)\n                    .subscribe(decryptionResult -\u003e {\n                        switch (decryptionResult.getResult()) {\n                            case FAILED:\n                                setStatusText(\"Fingerprint not recognized, try again!\");\n                                break;\n                            case HELP:\n                                setStatusText(decryptionResult.getMessage());\n                                break;\n                            case AUTHENTICATED:\n                                setStatusText(\"decrypted:\\n\" + decryptionResult.getDecrypted());\n                                break;\n                        }\n                    }, throwable -\u003e {\n                        //noinspection StatementWithEmptyBody\n                        if (RxFingerprint.keyInvalidated(throwable)) {\n                            // The keys you wanted to use are invalidated because the user has turned off his\n                            // secure lock screen or changed the fingerprints stored on the device\n                            // You have to re-encrypt the data to access it\n                        }\n                        Log.e(\"ERROR\", \"decrypt\", throwable);\n                        setStatusText(throwable.getMessage());\n                    });\n```\n\nBe aware that all encryption keys will be invalidated once the user changes their lockscreen or changes any of their enrolled fingerprints. If you receive an `onError` event\nduring decryption check if the keys were invalidated with `RxFingerprint.keyInvalidated(Throwable)` and prompt the user to encrypt their data again.\n\nOnce the encryption keys are invalidated RxFingerprint will delete and renew the keys in the Android Keystore on the next call to `RxFingerprint.encrypt(...)`. \n\n### Best-practices\n\nTo prevent errors and ensure a good user experience, make sure to think of these cases:\n\n- Before calling any RxFingerprint authentication, check if the user can use fingerprint authentication by calling: `RxFingerprint.isAvailable(Context)` or `RxFingerprint.isUnavailable(Context)`\n- Always check for recoverable errors in any `onNext` events and provide the user with the given Error message in the result.\n- If keys were invalidated due to the user changing their lockscreen or enrolled fingerprints provide them with a way to encrypt their data again.\n\n## Dependencies\n\nRxFingerprint brings the following dependencies:\n\n- RxJava2\n- Android Support Annotations\n\n## Bugs and Feedback\n\nFor bugs, questions and discussions please use the [Github Issues](https://github.com/mauin/RxFingerprint/issues).\n \n## LICENSE\n\nCopyright 2015-2017 Marvin Ramin.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n\u003chttp://www.apache.org/licenses/LICENSE-2.0\u003e\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmauin%2Frxfingerprint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmauin%2Frxfingerprint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmauin%2Frxfingerprint/lists"}