taler-android

Android apps for GNU Taler (wallet, PoS, cashier)
Log | Files | Refs | README | LICENSE

README.md (4195B)


      1 <!--
      2   This file is part of GNU Taler
      3   (C) 2026 Taler Systems S.A.
      4 
      5   GNU Taler is free software; you can redistribute it and/or modify it under the
      6   terms of the GNU General Public License as published by the Free Software
      7   Foundation; either version 3, or (at your option) any later version.
      8 
      9   GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
     10   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
     11   A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
     12 
     13   You should have received a copy of the GNU General Public License along with
     14   GNU Taler; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
     15 -->
     16 
     17 # Answering for the names the app hard-codes
     18 
     19 Two service URLs are literals in the wallet:
     20 
     21 * `https://taldir.gnunet.org` — the Taler directory, in two files, with no way
     22   to change it (`findings/alias-registration-hardcodes-the-directory.md`);
     23 * `https://mailbox.gnunet.org` — the mailbox default, which the UI *can*
     24   override, so this only saves typing.
     25 
     26 To exercise those code paths as they ship, two separate things are needed: the
     27 device has to *resolve* the names to something local, and the app has to
     28 *trust* what answers. Neither one changes a URL the app under test uses.
     29 
     30 Trust is the easy half, and it belongs in the APK: the `sim` build type — which
     31 exists for the simulator and is never published — carries the CA as an extra
     32 trust anchor in `wallet/src/sim/res/xml/network_security_config.xml`, alongside
     33 the system store and with src/main's cleartext policy unchanged. The private
     34 key stays on the host running the stack, so the committed certificate on its
     35 own authorises nobody.
     36 
     37 ```bash
     38 # once, on the host
     39 openssl req -x509 -newkey rsa:2048 -nodes -keyout ca.key -out ca.crt -days 3650 \
     40   -subj "/CN=Taler wallet simulator CA" \
     41   -addext "basicConstraints=critical,CA:TRUE" -addext "keyUsage=critical,keyCertSign,cRLSign"
     42 openssl req -newkey rsa:2048 -nodes -keyout srv.key -out srv.csr -subj "/CN=taldir.gnunet.org"
     43 printf 'subjectAltName=DNS:taldir.gnunet.org,DNS:mailbox.gnunet.org\nextendedKeyUsage=serverAuth\n' > srv.ext
     44 openssl x509 -req -in srv.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out srv.crt -days 3650 -extfile srv.ext
     45 
     46 # regenerating the CA means rebuilding the APK that trusts it
     47 cp ca.crt ../../wallet/src/sim/res/raw/sim_ca.crt
     48 
     49 GOTOOLCHAIN=local go build -o tlsproxy .      # this directory
     50 ./tlsproxy &                                   # 127.0.0.1:8443, routes by Host
     51 
     52 # per emulator
     53 ../emu/tls-names.sh 4
     54 ```
     55 
     56 `tls-names.sh` does the resolving half: it roots that one emulator (a root adbd
     57 is what makes a privileged listening port possible), bind-mounts a hosts file
     58 carrying `127.0.0.1 taldir.gnunet.org mailbox.gnunet.org` over
     59 `/system/etc/hosts`, and forwards the device's port 443 to the host's 8443.
     60 
     61 It is undone by rebooting or wiping the emulator, so re-run it after one. The
     62 scenarios that need it (`alias_registration_real`) check for the port-443
     63 mapping and skip with a note when it is absent, rather than measuring the
     64 refusal.
     65 
     66 ## Why the trust anchor is not installed on the device
     67 
     68 That was tried first, and it is a trap worth recording.
     69 
     70 * There are **two** system stores on these images —
     71   `/apex/com.android.conscrypt/cacerts` and `/system/etc/security/cacerts`,
     72   which is a real directory and not a symlink into the APEX — and the app reads
     73   the second one.
     74 * Both are read-only, so each has to be replaced by a `tmpfs` holding a copy of
     75   the originals plus ours. A mount made from `adbd` is **invisible to app
     76   processes**, because APEX paths live in a mount namespace of their own; it has
     77   to be made inside init's namespace (`nsenter --mount=/proc/1/ns/mnt`).
     78 * Zygote has already forked by then, so the framework has to be restarted
     79   (`stop && start`) for apps to see the store at all. That leaves the network at
     80   `PARTIAL_CONNECTIVITY` for a while, and a wallet on such a network refuses
     81   everything with "This action requires internet connection" — which looks
     82   exactly like a wallet bug.
     83 
     84 All of that for a file the build system can simply put in the APK, in a build
     85 type that never ships.