taler-android

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

pos-config-url-percent-encodes-the-separator.md (3683B)


      1 # The terminal asks for its configuration at `/private%2Fpos`
      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:** medium -- works against a bare merchant backend, and cannot work
      6 behind a reverse proxy that does not decode encoded slashes, which is the
      7 default for Apache and a common hardening setting for nginx. The terminal then
      8 cannot be configured at all, and says only "Error: Could not connect to
      9 configuration server".
     10 
     11 **Where:** `merchant-terminal/src/main/java/net/taler/merchantpos/config/ConfigManager.kt:340`
     12 
     13 **Found by:** `pos-simulator`, scenario `pos_config_url_encodes_the_separator`.
     14 
     15 ## What happens
     16 
     17 The request the terminal makes for its point-of-sale configuration arrives with
     18 the path separator percent-encoded. From the mock backend's request log, with
     19 the terminal configured for instance `mockshop`:
     20 
     21 ```
     22 POST /instances/mockshop/private/token        200
     23 GET  /instances/mockshop/private%2Fpos        <- the configuration request
     24 GET  /instances/mockshop/config               200
     25 GET  /instances/mockshop/private/products/pretzel  200
     26 ```
     27 
     28 Only that one request is affected. Every other call -- the token, the backend
     29 config, the products, the orders, the refunds -- goes through
     30 `MerchantConfig.urlFor`, which concatenates strings and so leaves the separator
     31 alone.
     32 
     33 ## Why
     34 
     35 ```kotlin
     36 val url = when (val c = config) {
     37     is Config.New -> c.merchantUrl.toUri()
     38         .buildUpon()
     39         .appendPath("private/pos")        // ConfigManager.kt:340
     40         .build()
     41         .toString()
     42 }
     43 ```
     44 
     45 `Uri.Builder.appendPath` appends **one path segment** and percent-encodes
     46 anything in it that is not legal inside a segment -- including `/`, because a
     47 segment may legitimately contain an encoded slash. The intent was two segments.
     48 
     49 ## Why nobody has noticed
     50 
     51 The GNU Taler merchant backend decodes the request path before routing, so it
     52 answers the encoded form identically:
     53 
     54 ```
     55 $ curl -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $TOK" \
     56     'https://backend.demo.taler.net/instances/sandbox/private%2Fpos'
     57 200
     58 $ curl -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $TOK" \
     59     'https://backend.demo.taler.net/instances/sandbox/private/pos'
     60 200
     61 ```
     62 
     63 A deployment that puts the backend behind a reverse proxy need not. Apache's
     64 `AllowEncodedSlashes` defaults to `Off` and answers 404 for such a request
     65 before it ever reaches the backend; nginx normalises or rejects depending on
     66 whether the location uses a rewrite. This is the mock backend's exact-match
     67 routing answering 404 that first surfaced it -- a mock is stricter than the
     68 real thing on purpose, and that is the value of having one.
     69 
     70 ## Reproducing it
     71 
     72 ```bash
     73 cd /tmp/taler-pos-sim/driver && . ../env.sh
     74 python3 ../findings/repro_encoded_path_separator.py
     75 ```
     76 
     77 It starts a mock backend that records the paths it is asked for, provisions the
     78 terminal against it through the login form, and prints every request that
     79 arrived with an encoded separator.
     80 
     81 ## The fix
     82 
     83 One line; `pos-config-url-percent-encodes-the-separator.diff` has it. Either
     84 append the two segments separately:
     85 
     86 ```kotlin
     87     .appendPath("private")
     88     .appendPath("pos")
     89 ```
     90 
     91 or, matching what the rest of the module does, use `MerchantConfig.urlFor` --
     92 but that needs a `MerchantConfig`, which does not exist yet at this point in
     93 `fetchConfig`, so the two `appendPath` calls are the smaller change.
     94 
     95 `appendEncodedPath("private/pos")` also works and is what the name suggests,
     96 but it is the riskier spelling: it would pass a merchant-supplied segment
     97 through unencoded if the string ever stopped being a literal.