taler-android

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

qr-config-tab-crashes-the-terminal.md (6312B)


      1 # The QR configuration tab crashes the terminal on the first camera frame
      2 
      3 > **Fixed on master** (checked 2026-11-08, commit `24f7b249`). See [STATUS.md](STATUS.md) for the fix and the test that pins it.
      4 
      5 **Severity:** high -- the documented way to provision a terminal kills the app,
      6 and keeps killing it, so the terminal cannot be set up that way at all.
      7 
      8 **Where:** `merchant-terminal/src/main/java/net/taler/merchantpos/config/ConfigFragment.kt:410`
      9 
     10 **Found by:** `pos-simulator`, scenario `config_qr_tab`.
     11 
     12 ## What happens
     13 
     14 On the login screen, select the **QR config** tab. The camera starts, the first
     15 frame arrives at the analyzer, and the process dies:
     16 
     17 ```
     18 FATAL EXCEPTION: main
     19 Process: net.taler.merchantpos, PID: 23777
     20 java.lang.UnsupportedOperationException: This luminance source does not support rotation by 90 degrees.
     21 	at com.google.zxing.LuminanceSource.rotateCounterClockwise(LuminanceSource.java:119)
     22 	at net.taler.merchantpos.config.ConfigFragment.startCamera$lambda$0$1$0(ConfigFragment.kt:410)
     23 	at androidx.camera.core.ImageAnalysisAbstractAnalyzer.lambda$analyzeImage$0(ImageAnalysisAbstractAnalyzer.java:310)
     24 	at android.os.Handler.handleCallback(Handler.java:995)
     25 	at android.os.Looper.loop(Looper.java:338)
     26 	at android.app.ActivityThread.main(ActivityThread.java:9067)
     27 ```
     28 
     29 The user is dropped on the launcher with "Taler POS keeps stopping". Reopening
     30 the app and selecting the tab again crashes it again.
     31 
     32 ## Why
     33 
     34 ```kotlin
     35 val source = PlanarYUVLuminanceSource(nv21, width, height, 0, 0, width, height, false)
     36 val rotated = when (proxy.imageInfo.rotationDegrees) {
     37     90, 270 -> source.rotateCounterClockwise()      // ConfigFragment.kt:410
     38     else -> source
     39 }
     40 ```
     41 
     42 `PlanarYUVLuminanceSource` does not support rotation. In zxing-core 3.5.4 it
     43 overrides `crop`, `renderThumbnail` and `isCropSupported`, and leaves
     44 `rotateCounterClockwise()` and `isRotateSupported()` to the base class --
     45 where the first throws unconditionally and the second returns `false`:
     46 
     47 ```
     48 $ javap -p -cp core-3.5.4.jar com.google.zxing.PlanarYUVLuminanceSource | grep -c rotate
     49 0
     50 $ javap -p -cp core-3.5.4.jar com.google.zxing.LuminanceSource | grep rotate
     51   public com.google.zxing.LuminanceSource rotateCounterClockwise();
     52 ```
     53 
     54 So the branch is a guaranteed crash whenever it is taken, and it is taken
     55 whenever `rotationDegrees` is 90 or 270 -- which is the *normal* case for this
     56 screen. `MainActivity` is declared `screenOrientation="landscape"`, the sensor
     57 on a phone or tablet is mounted for portrait, and CameraX reports the rotation
     58 needed to bring the two into line. The crash is not an edge case; a device
     59 whose sensor happens to agree with a landscape display is the edge case.
     60 
     61 `isRotateSupported()` is never consulted, which is what would have turned this
     62 into a no-op instead of a crash.
     63 
     64 ## A second defect in the same function
     65 
     66 `yuv420888ToNv21` copies each plane with `buffer.get(...)` and ignores
     67 `Image.Plane.getRowStride()` and `getPixelStride()`:
     68 
     69 ```kotlin
     70 val ySize = yPlane.remaining()
     71 ...
     72 yPlane.get(nv21, 0, ySize)
     73 vPlane.get(nv21, ySize, vSize)
     74 uPlane.get(nv21, ySize + vSize, uSize)
     75 ```
     76 
     77 A YUV_420_888 plane is only densely packed when `rowStride == width` and, for
     78 the chroma planes, `pixelStride == 1`. Neither is guaranteed: hardware commonly
     79 aligns rows to 16 or 32 bytes, and the chroma planes of this format are
     80 routinely semi-planar with `pixelStride == 2`. Where they differ, every row
     81 after the first is offset by the padding, the luminance image comes out sheared
     82 and no code decodes -- silently, because a `NotFoundException` is exactly what
     83 "no code in frame" looks like.
     84 
     85 The emulator's camera happens to deliver `rowStride == width`, which is why
     86 this one does not show up as a crash. It is the same defect the wallet
     87 simulator recorded for the wallet's scanner
     88 (`simulator/findings/qr-camera-ignores-the-plane-strides.md`); the two scanners
     89 are separate code.
     90 
     91 ## Reproducing it
     92 
     93 ```bash
     94 cd /tmp/taler-pos-sim/driver && . ../env.sh
     95 python3 ../findings/repro_qr_tab_crash.py
     96 ```
     97 
     98 or by hand: install the app, open it with no configuration, tap **QR config**.
     99 
    100 The emulator's virtual-scene camera reproduces it without a code to scan,
    101 because the crash is in the frame handler and does not depend on what the
    102 frame contains.
    103 
    104 ## The fix
    105 
    106 `qr-config-tab-crashes-the-terminal.diff` rotates the luminance bytes before
    107 building the source, instead of asking the source to rotate itself, and honours
    108 the plane strides while copying. Both changes are in `ConfigFragment`:
    109 
    110 * `luminanceFrom(image)` walks the Y plane row by row using `rowStride` and
    111   `pixelStride`, so a padded or interleaved plane copies correctly. Only the Y
    112   plane is needed -- `PlanarYUVLuminanceSource` reads luminance only, and the
    113   chroma bytes the old code appended were never looked at.
    114 * `rotate(bytes, width, height, degrees)` produces the rotated buffer, and the
    115   source is constructed with the dimensions that go with it.
    116 
    117 An alternative one-line fix is to drop the rotation altogether, since zxing's
    118 QR detector finds its finder patterns at any orientation. That is a smaller
    119 change but a worse one: it leaves the rotation handling in the code looking
    120 correct while never running, and it does nothing about the strides.
    121 
    122 ### What the patch was verified to do
    123 
    124 On one emulator (API 36, tablet profile, virtual-scene camera), with the same
    125 AVD and the same tap in both cases:
    126 
    127 * the unpatched APK dies with the stack trace above -- reproduced four times,
    128   including twice with a bare `adb shell input tap` rather than through the
    129   harness, so it is not an artefact of how the simulator taps;
    130 * the patched APK does not. The QR tab opens, the live camera preview renders
    131   and the "Scan the QR code from Merchant Backoffice" hint appears (confirmed
    132   by screenshot, because the view hierarchy is unreliable over a camera
    133   preview -- see the README's gotchas).
    134 
    135 What is **not** yet verified is that a code is decoded correctly: showing the
    136 camera a real QR code needs the emulator's virtual-scene poster, and no decode
    137 has succeeded yet on that path. So the stride fix is reasoned from the
    138 YUV_420_888 contract rather than demonstrated, and the rotation fix is
    139 demonstrated only to the extent that it no longer crashes. Finishing that
    140 verification is the first item for the next round.