{"id":13703223,"url":"https://github.com/WIOsense/rauth-android","last_synced_at":"2025-05-05T07:30:38.922Z","repository":{"id":219396338,"uuid":"280459845","full_name":"WIOsense/rauth-android","owner":"WIOsense","description":"FIDO2 roaming authenticator library for Android OS","archived":false,"fork":false,"pushed_at":"2020-07-24T13:51:05.000Z","size":132,"stargazers_count":17,"open_issues_count":1,"forks_count":8,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-11-13T10:37:53.111Z","etag":null,"topics":["android-library","android-security","authentication","ctap2","fido2","fido2-authenticator","u2f","webauthn"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WIOsense.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-07-17T15:26:56.000Z","updated_at":"2024-09-07T14:11:06.000Z","dependencies_parsed_at":null,"dependency_job_id":"5df9ad60-3487-4e7a-a0d6-895c1de45821","html_url":"https://github.com/WIOsense/rauth-android","commit_stats":null,"previous_names":["wiosense/rauth-android"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WIOsense%2Frauth-android","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WIOsense%2Frauth-android/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WIOsense%2Frauth-android/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WIOsense%2Frauth-android/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WIOsense","download_url":"https://codeload.github.com/WIOsense/rauth-android/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252458327,"owners_count":21751017,"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-library","android-security","authentication","ctap2","fido2","fido2-authenticator","u2f","webauthn"],"created_at":"2024-08-02T21:00:52.137Z","updated_at":"2025-05-05T07:30:38.916Z","avatar_url":"https://github.com/WIOsense.png","language":"Java","funding_links":[],"categories":["Client Libraries"],"sub_categories":[],"readme":"# WIOsense Android Roaming Authenticator\n\nThis library provides a FIDO2 roaming authenticator and CTAP1/2 implementation for Android devices. It leverages modern Android OS security concepts to provide easy support for resident keys with strong authentication via biometric user verification or clientPIN functionality compliant with the FIDO2 specification, and so, legacy U2F specification.\n\nThe library contains 2 main components, i.e. the `Authenticator` class and the `TransactionManager`. The `Authenticator` implements the authenticator main logic and functionality and can be used directly in any app via the utilities and auxiliary classes existent within the library.\n\nThe `TransactionManager` role is to provide an easy way to bind diverse transport layers to the `Authenticator` and handle the CTAP messages and handshakes between a remote client and the authenticator. Currently the `TransactionManager` is focused on handling well the HID CTAP protocol. The physical transport of this can be implemented either via USB connections or the Bluetooth HID device profile and this is up to the calling applications to decide, configure and setup.\n\nAn example in this sense is for instance the [WioKey application](https://github.com/wiosense/wiokey-android) which uses the [Bluetooth HID device profile](https://developer.android.com/reference/android/bluetooth/BluetoothHidDevice) available in Android 9.0+ for the communication. We recommend the latter version of implementing HID for an improved user experience and easy interaction support with major desktop platforms (Windows 10, macOS, Linux) out of the box.\n\nFor security, the resident keys are protected by default by the Android KeyStore and strong authentication via AndroidX [BiometricPrompt](https://developer.android.com/reference/androidx/biometric/BiometricPrompt) or clientPIN user verfication. Jump to [security](##Security) for more details.\n\n## Quickstart\n\nYou can use [JitPack](https://jitpack.io/) to include this module in your Android project, or you can include the source code.\n\n### Using JitPack\n\nAdd this in your root build.gradle:\n\n```groovy\n    allprojects {\n        repositories {\n            ...\n            maven { url 'https://jitpack.io' }\n        }\n    }\n```\nAdd this to your dependencies list:\n\n```groovy\n    dependencies {\n        implementation 'com.github.wiosense:rauth-android:master-SNAPSHOT'\n    }\n```\n\n### Using Source\n\n#### Pull the source\n\n```\n$ cd ~/your/project/src/directory\n$ git clone https://github.com/wiosense/rauth-android.git\n```\n\n#### Add the module to your Android project\n\nIn Android Studio: `File -\u003e New -\u003e Import Module` and then point it at the `rauth-android` directory.\n\n#### Add the module as a dependency\n\nIn Android Studio: `File -\u003e Project Structure -\u003e App -\u003e Dependencies -\u003e + -\u003e Module Dependency`\n\nSelect the `roaming-authenticator` module. After a Gradle sync, you should be able to use the `de.wiosense.webauthn` package.\n\n## Authenticator.java usage\nThe `Authenticator` class implements the operations described in the Authenticator API section of Client To Authenticator Protocol [(CTAP)](https://fidoalliance.org/specs/fido-v2.0-ps-20190130/fido-client-to-authenticator-protocol-v2.0-ps-20190130.html#authenticator-api), and also provides APIs to manage the credentials that are contained in the Android Keystore.\n\nYou must first instantiate an authenticator object, which is safe to instantiate multiple times.\n\n```java\n    //Authenticator(Context ctx, boolean strongboxRequired)\n    Authenticator roamingAuthenticator = new Authenticator(appContext, true);\n```\n\nHere the strongboxRequired flag chooses whether to enforce the usage of a [StrongBox Keymaster](https://developer.android.com/training/articles/keystore#HardwareSecurityModule) HSM. Not all phones support this, but you can easily check at runtime by calling:\n\n```java\n    boolean hasStrongbox = currentContext.getPackageManager()\n                                .hasSystemFeature(PackageManager.FEATURE_STRONGBOX_KEYSTORE);\n```\n\nIt's important to note that all the following calls are blocking unless stated and shouldn't be executed in the UI thread of the app. Also, from this point on, all mentions to CBOR objects are related to **[this CBOR implementation](https://github.com/c-rack/cbor-java)**.\n\n### GetInfo\nYou can poll the internal state and capabilities of the authenticator by calling the `Authenticator.getInfo()` method. This returns a `GetInfoResult` object that can be put into CBOR formatted byte array by calling `GetInfoResult.asCBOR`.\n\n### MakeCredential (WebAuthn Registration)\nYou can create a new credential by passing a `MakeCredentialOptions` object to the `Authenticator.makeCredential` method. Or alternatively, you can also pass a `Map` CBOR object that is formatted according to the CTAP spec, this is usually handled by the internals of the `TransactionManager`.\n\nThis will return an `AttestationObject` which you can inspect and retrieve a byte array formatter CBOR like so:\n\n```java\n    byte[] attestation = attestationObject.asCBOR();\n```\n\nThe returned object can be of any of three subclasses depending on the options that were passed to `Authenticator.makeCredentials`:\n * `NoneAttestation`\n * `PackedBasicAttestation`\n * `PackedSelfAttestation`\n\n### GetAssertion (WebAuthn Authentication)\nYou can make an authentication request by passing a `GetAssertionOptions` object to the `Authenticator.getAssertion` method. Or alternatively, you can also pass a `Map` CBOR object that is formatted according to the CTAP spec, this is usually handleded by the internals of the `TransactionManager`.\n\nThis will return an `AssertionObject` which you can inspect and retrieve a byte array formatter CBOR like so:\n\n```java\n    byte[] assertion = assertionObject.asCBOR();\n```\n\n### GetPinResult (WebAuthn PIN management for higher security requirements)\nThe `Authenticator.getPinResult` method can be called with a `ClientPINOptions` object. However, it is important to point out that this particular method has a series of subcommands that [internally are handled differently](https://fidoalliance.org/specs/fido-v2.0-ps-20190130/fido-client-to-authenticator-protocol-v2.0-ps-20190130.html#authenticatorClientPIN), but all return the same `ClientPINResult` object that can be serialized like the previous results objects. This command is usually used as a [handshake](https://fidoalliance.org/specs/fido-v2.0-ps-20190130/fido-client-to-authenticator-protocol-v2.0-ps-20190130.html#without-pinToken-in-authenticatorGetAssertion), which needs to be handled by the user of the authenticator.\n\nApart from using the CTAP2 method to manage the PIN, the following APIs are provided for internal management:\n* `Authenticator.selfSetPin` which can set a PIN or override a previously set one after user verification\n* `Authenticator.resetPin` which gracefully removes a previously set PIN after user verification\n* `Authenticator.isPinSet` which returns a boolean specifying whether a PIN is currently set or not.\n\n### Credential Management \n`Authenticator.getAllCredentials` returns a list of all the credentials that are currently stored in the authenticator, as well as their relying parties and other relevant information.  \n`Authenticator.deleteCredential` deletes the credential object `PublicKeyCredentialSource` that is passed to it, after user verification.  \n`Authenticator.deleteAllCredentials` deletes the credential database after user verification.  \n`Authenticator.resetAuthenticator` can be called to completely wipe the credential database as well as the pin, after user verification.  \n\n## TransactionManager.java usage\nThe `TransactionManager` class oversees all communications going over the Bluetooth connection and is in charge of translating and formatting incoming/outgoing messages in the CTAP1/2 protocols so they can be interpreted by the `Authenticator` class.\n\nThe transaction manager needs to be instantiated with a valid `Authenticator` object and a valid activity to pass events like biometric requests to the UI:\n\n```java\n    //TransactionManager(FragmentActivity activity, Authenticator authenticator)\n    TransactionManager transactionManager = new TransactionManager(currentActivity,\n                                                    roamingAuthenticator);\n```\n\nTo service the messages coming from the Bluetooth connection, the transanction manager needs to be called from the `BluetoothHidDevice.Callback` that is registered to the `inputHost`, which can be done in the following manner:\n\n```java\n    BluetoothHidDevice inputHost;\n    /* \n     * Perform application registration and initialization\n     */\n    BluetoothHidDevice.Callback callback = new BluetoothHidDevice.Callback() {\n        /*\n         * Override other methods\n         */\n        @Override\n        public void onInterruptData(BluetoothDevice device , byte reportId, byte[] data) {\n            super.onInterruptData(device, reportId, data);\n            transactionManager.handleReport(data, (rawReports) -\u003e {\n                for (byte[] report : rawReports) {\n                    inputHost.sendReport(device, reportId, report);\n                }\n            })\n        }\n    }\n```\n\n**NOTE**: In cases where the current activity is recreated, you _must_ update the internal TransactionManager activity by calling `transactionManager.updateActivity(newActivity)`.\n\n## License\nThe application is open source is released under the terms of [BSD3 license](LICENSE).\n\nSome parts of the code were modified from other open source projects (see [INFO](INFO)), being marked with their original license terms and copyright information.\n\n## Privacy\nThis library aims to provide a software replacement of hardware security keys by leveraging the modern hardware and security components of Android OS and phones. To this extent all sensitive data is stored on the phone in dedicated secured components and no sensitive information (private keys, user account information) is exchanged with any 3rd parties. It is meant to provide a core authenticator component for FIDO2 strong authentication via roaming authenticators on Android.\n\n## Security\nIf you identify any security problems or vulnerabilities within this library, please contact vulnerability@wiosense.de with a security disclosure and report of the identified issues.\n\nWe practice a fortnight (2 weeks) security disclosure policy, time in which we will try to address the problems and provide a fix. Therefore we kindly ask you to delay any planned public vulnerability disclosure either until 2 weeks have passed or a fix has been issued to allow for this process to take place.\n\nContributions are of course welcome!\n\nThe authenticator operations described earlier handled within the `TransactionManager` are by default protected by strong authentication enforced via screen lock mechanisms (e.g. PIN, pattern, Fingerprint, Face Unlock). It is the responsibility of the caller to make sure such settings exist to enable the authenticator functionality. The credentials database and the client PIN locker are authenticator resident by default and leverage the modern Android OS security hardware capabilities storing the sensitive key materials by default either within a Trusted Execution Environment (TEE) or a dedicated hardware Secure Element (SE) which Android OS asserts to harden and prevent the extraction of the key materials. For a quick distinction between the two check this [article](https://proandroiddev.com/android-keystore-what-is-the-difference-between-strongbox-and-hardware-backed-keys-4c276ea78fd0) out.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWIOsense%2Frauth-android","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FWIOsense%2Frauth-android","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWIOsense%2Frauth-android/lists"}