wirabasalamah/Brizzi-HCE
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9994823fb34bdab04d006532b2cd739d0860c9e8
Brizzi-HCE/README.md

12 KiB
Raw Blame History

BRIZZI HCE (Android NFC Host Card Emulation)

Dokumen ini menjelaskan struktur project, alur eksekusi, dan cara membacanya supaya kamu bisa langsung maintance/debug proyek ini.

1) Gambaran Umum

Project ini adalah aplikasi Android HCE (Host Card Emulation) yang memproses APDU dari reader NFC (misalnya terminal).
Komponen utamanya:

2) Bagaimana alur request APDU

  1. APDU masuk ke processCommandApdu(...) di BrizziHostApduService.
  2. Service melakukan:
    • validasi basic (null/size/rate limit),
    • log/track metrik event,
    • dispatch ke BrizziApduRouter.handle().
  3. Router:
    • parse APDU via ApduParser,
    • cek timeout sesi,
    • cek replay untuk command sensitif,
    • validasi state session (AID/auth/transaction),
    • memetakan hasil ke SW response.
  4. Response SW/konten dikirim ke terminal.

3) State machine yang penting

BrizziSession menyimpan dua level state:

  • SessionPhase
    • NONE
    • AID1_SELECTED
    • AID3_SELECTED
    • AID3_AUTHENTICATED
  • TransactionPhase
    • NONE
    • DEBIT_PENDING
    • CREDIT_PENDING
    • LOG_PENDING
    • LAST_TXN_PENDING

hasPendingTransactionState() dipakai untuk mencegah abuse:

  • command debit/credit tidak boleh overlapping,
  • commit/abort (C7/A7) harus disinkron.

4) Security hardening yang sudah diterapkan

  • Parsing APDU tidak lagi pakai regex string mentah sepenuhnya; gunakan ApduParser untuk parse CLA/INS/P1/P2/Lc/Data/Le.
  • Validasi panjang dan malformed handling lebih ketat (wrongLength, unsupportedInstruction, rateLimitExceeded, dll.).
  • Replay protection untuk command sensitif dalam window pendek.
  • Rate limit:
    • max 80 command / 1000ms,
    • minimum gap antar command 30ms.
  • Session timeout 120 detik.
  • FLAG_SECURE di UI supaya tidak mudah di-screenshot.
  • usesCleartextTraffic=false dan networkSecurityConfig.
  • Logging produksi diarahkan ke metadata minimal (tidak menyimpan raw APDU).

5) Penyimpanan data (yang dipilih)

Sebelum ini data ada di RAM. Sekarang:

  • BrizziSecureStorage menyimpan data kartu ke EncryptedSharedPreferences:
    • card_number, balance, logs, lastTransactionDate, dsb.
  • Kunci enkripsi berasal dari Android Keystore (MasterKey).
  • Data dipersisten saat commit transaksi (C7) via callback onCardUpdated.
  • Bila loading gagal, sistem fallback ke nilai default (BrizziCard()).

Catatan: ini aman untuk tingkat aplikasi, namun bukan secure element hardware.

6) Monitoring & Incident readiness (point 5 yang kamu minta)

BrizziSecurityMetrics menyimpan counter event:

  • command total/sukses/gagal,
  • timeout, rate limit, replay,
  • auth denied, parse fail, dan lain-lain.

Mechanism:

  • service memanggil track(event) untuk setiap event penting,
  • bila ambang incident terlampaui (mis. COMMAND_RATE_LIMIT, REPLAY_DETECTED, AUTH_DENIED, dll), service log security incidents (throttled per menit),
  • snapshot juga diekspor ke file internal:
    • app/files/security_metrics_report.txt.

Debug actions dari MainActivity

  • Dump metrics (debug only):
    • adb shell am start -n com.korancrew.brizzi/.MainActivity -a com.korancrew.brizzi.ACTION_DUMP_METRICS
  • Reset metrics (debug only):
    • adb shell am start -n com.korancrew.brizzi/.MainActivity -a com.korancrew.brizzi.ACTION_RESET_METRICS
  • Lihat file log:
    • /data/data/com.korancrew.brizzi/files/security_metrics_report.txt

7) Command support (high level)

Di router, mapping didasarkan pada helper:

  • AID selector (1/3): 905A...0100..., 905A...0300...
  • AID 1 info/status
  • AID 3 auth & read balance/log/transaction
  • debit/credit
  • write log + update last transaction + commit/abort
  • fallback: unsupportedInstruction (6D00)

Untuk daftar lengkap command literal, lihat:

8) Cara memahami kode (urutan baca yang disarankan)

  1. BrizziHostApduService.kt – masuknya data APDU, rate limit, metrik.
  2. BrizziApduRouter.kt – policy/routing per command.
  3. BrizziSession.kt – state session/transaction.
  4. ApduParser.kt – struktur parser.
  5. BrizziCard.kt + BrizziSecureStorage.kt.
  6. BrizziSecurityMetrics.kt – event/incident.
  7. BrizziResponse.kt + Hex.kt.

9) Build & release yang dipakai sekarang

  • debug: non-minify (mudah debug).
  • release: minify + shrink + ProGuard:
  • Signing release hanya aktif jika property gradle diisi (via CI keystore properties):
    • RELEASE_STORE_FILE, RELEASE_STORE_PASSWORD, RELEASE_KEY_ALIAS, RELEASE_KEY_PASSWORD.

10) Known caveat (buat pembacaan objektif)

  • Banyak SW command belum sepenuhnya di-convert ke parser berbasis field; saat ini tetap berbasis string matching untuk backward compatibility.
  • Jika ini akan dipakai di production nyata (bukan simulasi/prototype), perlu hardening tambahan:
    • enkripsi/rotasi kunci lebih ketat,
    • secure policy distribusi dan integrity update,
    • backend attestation/monitoring terpusat.

11) Ringkas: arsitektur dalam satu kalimat

Ini adalah stateful HCE emulator: APDU masuk → rate-limit & parser → aturan fase sesi → update card/metrics → response status dengan persistensi terenkripsi + audit event.

12) Cara membaca kode (bisa dijadikan panduan debugging)

12.1 Alur end-to-end dalam 1 request

  1. Terminal mengirim APDU ke BrizziHostApduService.
  2. processCommandApdu(...) memvalidasi ukuran, null, dan rate-limit di service.
  3. BrizziHostApduService menyerahkan APDU ke BrizziApduRouter.handle(...).
  4. Router memanggil ApduParser.parse(...) untuk decode field CLA/INS/P1/P2/Lc/Data/Le.
  5. Router memvalidasi:
    • sesi timeout (SESSION_TIMEOUT_MS),
    • replay untuk perintah sensitif (REPLAY_WINDOW_MS),
    • state/phase yang valid (BrizziSession),
    • format payload (contoh: debit/credit/write log/last transaction).
  6. Jika valid, router memproses rule per command dan memodifikasi pending* pada session serta card jika commit.
  7. Response dibentuk dari BrizziResponse (6700, 6985, 6FFF, 9100, dll).
  8. Service mencatat event ke BrizziSecurityMetrics, menilai health, dan menulis snapshot ke security_metrics_report.txt.

12.2 Urutan file untuk dibaca dari atas ke bawah

  1. BrizziHostApduService.kt
    • Titik masuk APDU dari HCE.
    • Juga memegang rate-limit, incident throttle log, dan ekpor metrik.
  2. BrizziApduRouter.kt
    • Aturan stateful command routing.
    • Core logic transaksi debit/credit/log/last transaction/commit-abort.
  3. BrizziSession.kt
    • Menjaga state sesi, fase autentikasi, fase transaksi, anti-replay, dan pending state.
  4. ApduParser.kt
    • Parsing protokol APDU (case-1..case-4).
  5. BrizziCard.kt + BrizziSecureStorage.kt
    • Struktur data card dan log transaksi; bagaimana data bertahan di penyimpanan terenkripsi.
  6. BrizziSecurityMetrics.kt
    • Event tracking, incident threshold, snapshot/report.

12.3 Kontrak keamanan yang harus dipahami

  • Syarat autentikasi: akses area saldo/log/last transaction hanya setelah fase AID3_AUTHENTICATED.
  • Syarat transaksi: debit/credit harus dalam state siap transaksi, tidak boleh ada pending transaction lain.
  • Commit/Abort: C7/A7 adalah pembatas akhir lifecycle transaksi. Tanpa pending state, kedua command itu ditolak.
  • Logika rollback: pending update hanya masuk ke state final saat COMMIT; ABORT membersihkan pending.
  • Replay guard: command sensitif (debit/credit/commit/abort/write log/last tx) tidak boleh diulang dalam window pendek.

12.4 Checklist membaca log saat debugging

  • Jika terjadi CONDITIONS_NOT_SATISFIED berulang: cek urutan select-aid-auth-send command.
  • Jika rateLimitExceeded sering:
    • periksa apakah device reader terlalu cepat kirim command (<30ms antar command).
    • pastikan transaksi tidak melebihi 80 command/s.
  • Jika COMMAND_PARSE_FAILED naik: cek command malformed (Lc/Le mismatch, trailing bytes, payload aneh).
  • Ambil snapshot metrik:
    • adb shell am start -n com.korancrew.brizzi/.MainActivity -a com.korancrew.brizzi.ACTION_DUMP_METRICS
  • Hapus metrik jika perlu test ulang:
    • adb shell am start -n com.korancrew.brizzi/.MainActivity -a com.korancrew.brizzi.ACTION_RESET_METRICS

13) Peta ancaman & mitigasi singkat (ringkas)

  • Replay → dibatasi window 800ms di router + deteksi command sensitif.
  • Flood → dibatasi 80 cmd/1000ms + minimum 30ms antar command di service.
  • Session theft/continuity → timeout 120 detik, reset state saat deactivated.
  • Data disclosure → FLAG_SECURE, cleartext dimatikan, keystore-backed storage untuk card state.
  • Silent fail di prod → metrik tidak menyimpan APDU mentah, hanya metadata event.

14) Paket uji cepat (smoke test) untuk koneksi reader

  • Gunakan HCE_BRIZZI_SMOKE_TEST.md untuk menjalankan alur verifikasi:
    • build/install,
    • cek service + logcat,
    • validasi interaksi AID/auth/transaksi ke reader.