diff --git a/README.md b/README.md index 395571e..ac42f49 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ wwWallet Android ================ An Android native application wrapping `https://demo.wwwallet.org`. It is intended as a research project for the -funke and sprintd competition. +Funke and Sprintd competition. Running @@ -31,14 +31,14 @@ Wrapping This Android application "wraps" the https://demo.wwwallet.org/ website, providing direct interaction with Yubikeys and an initial set of bluetooth communication with a verifier. The wrapping happens by loading the website inside an Android -native `WebView` and intercepting interesting js code calls and websides to be loaded. +native `WebView` and intercepting interesting js code calls and websites to be loaded. ### Wrapping JS in Kotlin / Android The aforementioned WebView is used to load the website and intercept not only a locally build version of the website, -but also to catch and wrap incoming javascript calls dealing with yubikeys and bluetooth communication. This is done, so +but also to catch and wrap incoming javascript calls dealing with Yubikeys and Bluetooth communication. This is done, so the website can be augmented with native kotlin code directly interacting with hardware: On the one hand for -communicating with Yubikeys, but also for communicating with bluetooth. +communicating with Yubikeys, but also for communicating with Bluetooth. ### Alternatives to wrapping @@ -52,7 +52,7 @@ that are running on several platforms. At the time of this writing, those platfo devices. Exploring this option to run our wallet on Android revealed, that the interoperability between React Native, the -javascript framework used to build the website, cannot be easily replicated inside Kotlin Multiplatform. To use this +Javascript framework used to build the website, cannot be easily replicated inside Kotlin Multiplatform. To use this alternative, we would need to either port our existing website or start from scratch. While that would open up the possibility to support more platforms (i.e. Desktops), the effort of translating and reeducation needed for that development was deemed to high. @@ -64,7 +64,7 @@ opportunity to use platform paradigms to confuse the user less about potential w inside a native app. But similar to the potential Kotlin Multiplatform approach, this has the downside of needing to rewrite the app -completely from scratch, reeducating our engineering team to add a new platform with new paradigms and ux to it, and in +completely from scratch, reeducating our engineering team to add a new platform with new paradigms and UX to it, and in the end was rejected because of these reasons. #### Other Solutions Not Considered @@ -77,18 +77,18 @@ seemed to have the right expertise onboard, and have explored similar options be Wallet Frontend and Hardware interactions ----------------------------------------- -After settling on an approach, let us explore the technical implementation of sad solution. The following chapters cover +After settling on an approach, let us explore the technical implementation of said solution. The following chapters cover the hardware details, libraries included and explored. ### Security Keys Making users phishing resistant is one of our goals, especially while interacting with private data as coming from a -state issued id. Therefore, we opted to build a secure layer on top, in which we are leveraging device bound passkeys -from yubico for registering and logging users in and to verify the presentation of digital documents by signing their +state issued ID. Therefore, we opted to build a secure layer on top, in which we are leveraging device bound passkeys +from Yubico for registering and logging users in and to verify the presentation of digital documents by signing their validity. -In order to use passkeys following the FIDO2 standard and some extensions, we needed to find a way to addresses this -hardware from the wwallet frontend website through the wrapper. +In order to use Passkeys following the FIDO2 standard and some extensions, we needed to find a way to address this +hardware from the wallet frontend website through the wrapper. ### Passkeys in Browsers @@ -102,13 +102,13 @@ will ask her to present her security key. This is done by calling `naviagtor.cre secure credentials inside the browser. This is where the interaction with the wrapper starts: After the wrapper is initialized, it overwrites the -`navibator.credentials.*` javascript API with it's implementations. +`navigator.credentials.*` javascript API with it's implementations. This is done by injecting an Android Native bridge, showing up as `nativeWrapper` for the javascript website, but also overwriting the aforementioned methods. Once the website calls those methods, the wrapper catches this call and redirects the creation options. These options are then sent to the native android -SDK [yubikit-android](https://github.com/Yubico/yubikit-android), which executes the request and ideally response with a -created credentials. Lastly the wrapped method will take the response from the SDK, and converts it into javascript +SDK [yubikit-android](https://github.com/Yubico/yubikit-android), which executes the request and ideally responds with the +created credentials. Lastly the wrapped method will take the response from the SDK, and convert it into javascript native objects in JSON. For the wallet website being wrapped, it looks like a normal call to the `navigator.credentials.create` function, but in @@ -123,24 +123,24 @@ wrapper also has to wrap those promises. This is achieved by creating an API for promises, but maps them to use callbacks to be able to call them from kotlin: Whenever a method is called that returns a promise to JS, a new object containing the `reject` and `resolve` function from a new Promise is created. Additionally, a new UUID is created as a reference to the Kotlin side for this Promise. A callback inside the native -bridge can take those promise uuids, execute the associated work, and respond back by finding the promise based on it's -uuid. Lastly the bridge calls the promise's reject or resolve functions, reporting back to JS. +bridge can take those promise UUIDs, execute the associated work, and respond back by finding the promise based on its +UUID. Lastly the bridge calls the promise's reject or resolve functions, reporting back to JS. ### Signing and PRF extensions Since we are augmenting the website with native communication, we can also add new functionality that is not currently -available on the Androids native web browser. For instance we can add the pseudo random function (PRF) FIDO2 extension -when creating a new token, and asserting it when loging in the user. This way we can enhance the users security by +available on the Android native web browser. For instance we can add the pseudo random function (PRF) FIDO2 extension +when creating a new token, and asserting it when logging in the user. This way we can enhance the users security by reinforcing the use of hardware authentication. Similar for the SIGN extension: Ths SIGN extension can be used to ask the authenticator (the security key) to take a -blob of data and sign it, so a receiver, maybe a verifier, knows who owns the data and can ensure temperproof +blob of data and sign it, so a receiver, maybe a verifier, knows who owns the data and can ensure tamperproof presentations. #### State of PRF in Web Luckily the extension mechanism of the FIDO2 standard are public and applications are able to implement them on their -own time. There are already a number of implementation of the FIDO2 / Webauthn that can make use of the PRF extension, +own terms. There are already a number of implementations of FIDO2 / Webauthn that can make use of the PRF extension, but sadly the number was not high enough to not exclude users without the needed software update. #### Signing online @@ -152,49 +152,49 @@ this app, the iOS wallet proposal and our custom build of Firefox. The Yubico SDK for Android [yubkit-android]((https://github.com/Yubico/yubikit-android) is used heavily for communicating, signing and verifying strong security when presenting documents or registering and signing into the -wwwwallet frontend. +wallet frontend. See [NavigatorCredentialsContainerYubico](src/main/java/io/yubicolabs/wwwwallet/credentials/NavigatorCredentialsContainerYubico.kt), how the sdk is integrated. Alternatives for using Yubico's SDK was to either use the Android Platform FIDO2/ Webauthn implementation, but sadly -this SDK was missing the required sing in extension and for convenience the NFC functionality to create a credential +this SDK was missing the required signing extension and for convenience the NFC functionality to create a credential with a PIN. Presentment ----------- Presentment is the process of presenting a document to a verifying party: Think of it as presenting your eID at a police -checkup, a bar tender verifying your age, or to show your university diploma to a potential new employer. The wwwwalet +checkup, a bar tender verifying your age, or to show your university diploma to a potential new employer. The wallet already contains the presentment for documents online and readers are encouraged to read up on the online presentment -there. The following chapters are dedicated to explaining how the in person presentment works: How two phones can share +there. The following chapters are dedicated to explaining how the in-person presentment works: How two phones can share parts of documents securely while being close to each other. ### Bluetooth Low Energy -A brought number of mobile phones support the Low Energy profile for Bluetooth, so we chose this, together with the -ISO-18013-5 this forms the basis of this communications. +A huge number of mobile phones support the Low Energy profile for Bluetooth, so we chose this, together with the +ISO-18013-5 standard, this forms the basis of the communication. ### WebBle and extensibility -ISO-18013-5 allows several way how two mobile device can communicate: The verifying app ('Verifier') as the Bluetooth LE +ISO-18013-5 allows several ways how two mobile device can communicate: The verifying app ('Verifier') as the Bluetooth LE server of the communication is called `MDoc Reader` and as contrast the `MDoc` mode establishes the Wallet as the server -of the Bluetooth LE server. Independently of the mode the communication is established in the server and the client -communicates through `Charactersitics` and `Services` in Bluetooth LE. +of the Bluetooth LE server. Independently of the mode, the communication is established at the server and the client +communicates through `Characteristics` and `Services` in Bluetooth LE. ### Existing solutions -In order to implement said communication, we elaborate existing solutions on the market, emphasizing opensource +In order to implement said communication, we elaborate existing solutions on the market, emphasizing open source solutions to support their development and for ease of integration. -Sadly especially for the Android Wrapper, the situation showed as more complicated as hoped: Either the exiting code -bases where not meeting basic requirements of code quality, where not extensible enough, or where to tightly integrated +Sadly especially for the Android Wrapper, the situation showed more complicated than hoped: Either the exiting code +bases were not meeting basic requirements of code quality, were not extensible enough, or were to tightly integrated into other existing systems. -Therefore, we decided to implement the ble communication from scratch and offer the wwwallet frontend a simple API for -interacting with ble: The idea being that the Android wrapper abstracts the ble communication, and lets the frontend -simply ask the wrapper to send binary data through it. This way the frontend doesn't need to know the integralities of BLE +Therefore, we decided to implement the BLE communication from scratch and offer the wwwallet frontend a simple API for +interacting with BLE: The idea being that the Android wrapper abstracts the BLE communication, and lets the frontend +simply ask the wrapper to send binary data through it. This way the frontend doesn't need to know the internalities of the BLE communication, but needs to be able to convert the wwwwallet contents into a binary representation and communicate -securely with the verifier. It resolves into a clear separation between transport (the ble wrapper implementation) and +securely with the verifier. It resolves into a clear separation between transport (the BLE wrapper implementation) and communication (the wwwwallet). An overview of the API offered to the JS frontend is this: @@ -202,17 +202,17 @@ An overview of the API offered to the JS frontend is this: | API | Description | Parameter | Return | |---------|-------------------------------|-------------------------|------------------------------------------------------------| | mode | set the mode of communication | "mdoc reader" or "mdoc" | (immediate) | -| create | create a server / client | uuid of ble service | A promise that gets resolved when server/client is created | -| send | send data to client / server | string to be send | A promise resolved when completed | -| receive | prepare to receive dataa | nothing | A promise resolving with a string | -| state | (debug) returns state info | nothin | A string with mode, server / client states | +| create | create a server / client | UUID of BLE service | A promise that gets resolved when server/client is created | +| send | send data to client / server | string to be sent | A promise resolved when completed | +| receive | prepare to receive data | nothing | A promise resolving with a string | +| state | (debug) returns state info | nothing | A string with mode, server / client states | #### Example -The following javascript sample, illustrates the usage of above's API description. +The following javascript sample illustrates the usage of above's API description. ```js -let uuid = // uuid from verifiyer to connect to +let uuid = // UUID from verifiyer to connect to nativeWrapper.createClient(uuid) .then(nativeWrapper.sendToServer([1, 3, 4, 5])) .then(nativeWrapper.receiveFromServer()) @@ -225,20 +225,20 @@ This code sample creates a BLE client ('mdoc reader' mode) in the wrapper, sends reader / verifier) and "waits" for the server to send data back. Once the data is received, they get printed on the console. -With that snippet we got the opportunity to implement the complete protocol on the wwallet, without needing to +With that snippet we got the opportunity to implement the complete protocol in wwallet, without needing to understand BLE. This also offers us the opportunity to replace the wrapper BLE communications with Web Bluetooth at a later point in time. Offline ------- -Another crucial point of communicating between mobiles is the ability to communicate while being not connected to the -internet. Imagine a police control outside bigger cities without any LTE / 5G in the area, or an age check deep +Another crucial point of communicating between mobile phones is the ability to communicate while not being connected to the +Internet. Imagine a police control outside bigger cities without any LTE / 5G in the area, or an age check deep inside a big bulky building, where no Wi-Fi or GSM signals can reach. For those situations, the wrapper needs to offer a minimum of functionality so that the presentments can still happen. -For obvious reasons the offline presentment requires that the user has logged in once before so that her data is -availble to the wrapper and frontend. +For obvious reasons, the offline presentment requires that the user has logged in once before so that her data is +available to the wrapper and frontend. Inside the wrapper we already intercept JS calls to `navigator.credentials.create` and our own custom `nativeWrapper.*`, and additionally it is easy to intercept calls to open / request assets and new websites. In order to make the wrapper @@ -251,8 +251,8 @@ own localhost version of the wwwwallet on Android, but without the actual webser Sadly the alternatives like `bubblewrap` or similar did not offer much more then a thin abstraction layer on the WebView without taking away the mapping from requested webpage to local files. -We also added minimal offline support to the wwwallet frontend js code itself, by using `Service Workers` and similar -JS functionality, readers are encouraged to read on the appropriate documentation overthrew. +We also added minimal offline support to the wwwallet frontend JS code itself, by using `Service Workers` and similar +JS functionality, readers are encouraged to read on the appropriate documentation over there. Learnings --------- diff --git a/wrapper/src/main/ic_launcher-playstore.png b/wrapper/src/main/ic_launcher-playstore.png index 127dfa0..ca1680f 100644 Binary files a/wrapper/src/main/ic_launcher-playstore.png and b/wrapper/src/main/ic_launcher-playstore.png differ diff --git a/wrapper/src/main/res/drawable/ic_launcher_background.xml b/wrapper/src/main/res/drawable/ic_launcher_background.xml deleted file mode 100644 index ca3826a..0000000 --- a/wrapper/src/main/res/drawable/ic_launcher_background.xml +++ /dev/null @@ -1,74 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/wrapper/src/main/res/drawable/ic_launcher_foreground.xml b/wrapper/src/main/res/drawable/ic_launcher_foreground.xml new file mode 100644 index 0000000..ba49b7b --- /dev/null +++ b/wrapper/src/main/res/drawable/ic_launcher_foreground.xml @@ -0,0 +1,19 @@ + + + + + + diff --git a/wrapper/src/main/res/drawable/ic_launcher_foreground_mono.xml b/wrapper/src/main/res/drawable/ic_launcher_foreground_mono.xml new file mode 100644 index 0000000..a172636 --- /dev/null +++ b/wrapper/src/main/res/drawable/ic_launcher_foreground_mono.xml @@ -0,0 +1,16 @@ + + + + + diff --git a/wrapper/src/main/res/mipmap-anydpi-v26/ic_launcher.xml b/wrapper/src/main/res/mipmap-anydpi-v26/ic_launcher.xml index c4a603d..b3d0bc5 100644 --- a/wrapper/src/main/res/mipmap-anydpi-v26/ic_launcher.xml +++ b/wrapper/src/main/res/mipmap-anydpi-v26/ic_launcher.xml @@ -1,5 +1,6 @@ - - + + + \ No newline at end of file diff --git a/wrapper/src/main/res/mipmap-anydpi-v26/ic_launcher_round.xml b/wrapper/src/main/res/mipmap-anydpi-v26/ic_launcher_round.xml new file mode 100644 index 0000000..b3d0bc5 --- /dev/null +++ b/wrapper/src/main/res/mipmap-anydpi-v26/ic_launcher_round.xml @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/wrapper/src/main/res/mipmap-hdpi/ic_launcher.webp b/wrapper/src/main/res/mipmap-hdpi/ic_launcher.webp new file mode 100644 index 0000000..4b11290 Binary files /dev/null and b/wrapper/src/main/res/mipmap-hdpi/ic_launcher.webp differ diff --git a/wrapper/src/main/res/mipmap-hdpi/ic_launcher_foreground.webp b/wrapper/src/main/res/mipmap-hdpi/ic_launcher_foreground.webp deleted file mode 100644 index af8f351..0000000 Binary files a/wrapper/src/main/res/mipmap-hdpi/ic_launcher_foreground.webp and /dev/null differ diff --git a/wrapper/src/main/res/mipmap-hdpi/ic_launcher_round.webp b/wrapper/src/main/res/mipmap-hdpi/ic_launcher_round.webp new file mode 100644 index 0000000..9ec39cd Binary files /dev/null and b/wrapper/src/main/res/mipmap-hdpi/ic_launcher_round.webp differ diff --git a/wrapper/src/main/res/mipmap-mdpi/ic_launcher.webp b/wrapper/src/main/res/mipmap-mdpi/ic_launcher.webp new file mode 100644 index 0000000..f6778ac Binary files /dev/null and b/wrapper/src/main/res/mipmap-mdpi/ic_launcher.webp differ diff --git a/wrapper/src/main/res/mipmap-mdpi/ic_launcher_foreground.webp b/wrapper/src/main/res/mipmap-mdpi/ic_launcher_foreground.webp deleted file mode 100644 index d89e00e..0000000 Binary files a/wrapper/src/main/res/mipmap-mdpi/ic_launcher_foreground.webp and /dev/null differ diff --git a/wrapper/src/main/res/mipmap-mdpi/ic_launcher_round.webp b/wrapper/src/main/res/mipmap-mdpi/ic_launcher_round.webp new file mode 100644 index 0000000..b5462cf Binary files /dev/null and b/wrapper/src/main/res/mipmap-mdpi/ic_launcher_round.webp differ diff --git a/wrapper/src/main/res/mipmap-xhdpi/ic_launcher.webp b/wrapper/src/main/res/mipmap-xhdpi/ic_launcher.webp new file mode 100644 index 0000000..ffd1ea5 Binary files /dev/null and b/wrapper/src/main/res/mipmap-xhdpi/ic_launcher.webp differ diff --git a/wrapper/src/main/res/mipmap-xhdpi/ic_launcher_foreground.webp b/wrapper/src/main/res/mipmap-xhdpi/ic_launcher_foreground.webp deleted file mode 100644 index 849ec21..0000000 Binary files a/wrapper/src/main/res/mipmap-xhdpi/ic_launcher_foreground.webp and /dev/null differ diff --git a/wrapper/src/main/res/mipmap-xhdpi/ic_launcher_round.webp b/wrapper/src/main/res/mipmap-xhdpi/ic_launcher_round.webp new file mode 100644 index 0000000..acb9380 Binary files /dev/null and b/wrapper/src/main/res/mipmap-xhdpi/ic_launcher_round.webp differ diff --git a/wrapper/src/main/res/mipmap-xxhdpi/ic_launcher.webp b/wrapper/src/main/res/mipmap-xxhdpi/ic_launcher.webp new file mode 100644 index 0000000..e2b4c9b Binary files /dev/null and b/wrapper/src/main/res/mipmap-xxhdpi/ic_launcher.webp differ diff --git a/wrapper/src/main/res/mipmap-xxhdpi/ic_launcher_foreground.webp b/wrapper/src/main/res/mipmap-xxhdpi/ic_launcher_foreground.webp deleted file mode 100644 index 7d84910..0000000 Binary files a/wrapper/src/main/res/mipmap-xxhdpi/ic_launcher_foreground.webp and /dev/null differ diff --git a/wrapper/src/main/res/mipmap-xxhdpi/ic_launcher_round.webp b/wrapper/src/main/res/mipmap-xxhdpi/ic_launcher_round.webp new file mode 100644 index 0000000..11e9d44 Binary files /dev/null and b/wrapper/src/main/res/mipmap-xxhdpi/ic_launcher_round.webp differ diff --git a/wrapper/src/main/res/mipmap-xxxhdpi/ic_launcher.webp b/wrapper/src/main/res/mipmap-xxxhdpi/ic_launcher.webp new file mode 100644 index 0000000..97c7e4c Binary files /dev/null and b/wrapper/src/main/res/mipmap-xxxhdpi/ic_launcher.webp differ diff --git a/wrapper/src/main/res/mipmap-xxxhdpi/ic_launcher_foreground.webp b/wrapper/src/main/res/mipmap-xxxhdpi/ic_launcher_foreground.webp deleted file mode 100644 index 1bfb8ae..0000000 Binary files a/wrapper/src/main/res/mipmap-xxxhdpi/ic_launcher_foreground.webp and /dev/null differ diff --git a/wrapper/src/main/res/mipmap-xxxhdpi/ic_launcher_round.webp b/wrapper/src/main/res/mipmap-xxxhdpi/ic_launcher_round.webp new file mode 100644 index 0000000..de3dcba Binary files /dev/null and b/wrapper/src/main/res/mipmap-xxxhdpi/ic_launcher_round.webp differ diff --git a/wrapper/src/main/res/values/ic_launcher_background.xml b/wrapper/src/main/res/values/ic_launcher_background.xml new file mode 100644 index 0000000..d96f494 --- /dev/null +++ b/wrapper/src/main/res/values/ic_launcher_background.xml @@ -0,0 +1,4 @@ + + + #00FF00 + \ No newline at end of file diff --git a/wrapper/src/main/res/xml/shortcuts.xml b/wrapper/src/main/res/xml/shortcuts.xml index d6d4fa8..bb3d947 100644 --- a/wrapper/src/main/res/xml/shortcuts.xml +++ b/wrapper/src/main/res/xml/shortcuts.xml @@ -1,7 +1,7 @@ - - - - - diff --git a/wrapper/src/release/res/values/ic_launcher_background.xml b/wrapper/src/release/res/values/ic_launcher_background.xml new file mode 100644 index 0000000..c5d5899 --- /dev/null +++ b/wrapper/src/release/res/values/ic_launcher_background.xml @@ -0,0 +1,4 @@ + + + #FFFFFF + \ No newline at end of file