Security Whitepaper
+How to Securely Process Festival Payments Using Standard €0.10 NFC Tags
+ ++ +
1. Executive Summary
++ CatLab Drinks is a cashless point-of-sale (POS) system designed for events, festivals, and bars. It uses + NFC-enabled cards (NTAG213) as physical payment tokens that store a digital balance. Multiple POS terminals + operate concurrently, with support for offline operation when internet connectivity is unreliable. +
++ This whitepaper describes the security architecture and measures taken to protect the integrity of the + cashless payment ecosystem against fraud, replay attacks, and unauthorized modifications. +
+ ++ +
2. Threat Model
+ +2.1 Primary Threats
+| Threat | Description | Risk Level |
|---|---|---|
| Balance forgery | An attacker writes arbitrary credit to their NFC card | Critical |
| Replay attack | Copying signed data from one card to another | High |
| Key interception | An authenticated user extracts the signing key from the browser | High |
| Rogue terminal | An unauthorized device enters the ecosystem and signs cards | High |
| Offline tampering | Exploiting offline POS terminals to manipulate balances | Medium |
| Write interruption | Power loss during NFC write corrupts card data | Medium |
2.2 Previous Vulnerability (Version 0)
++ The original system used a single shared symmetric HMAC-SHA256 key across all POS terminals. This key + was loaded client-side whenever any user logged into the management website, creating a critical vulnerability: + any authenticated user could intercept the key and forge card balances. +
+ ++ +
3. Cryptographic Architecture (Version 1)
+ +3.1 Asymmetric Key Model
++ Version 1 replaces the shared symmetric key with per-device ECDSA P-192 key pairs: +
+-
+
- Each POS terminal generates and stores its own unique private key +
- Public keys are managed centrally at the organisation (tenant) level +
- Terminals sign card data with their private key +
- Other terminals verify signatures using approved public keys downloaded from the server +
+ This eliminates the shared-secret vulnerability: no single key compromise affects the entire system. +
+ +3.2 Why ECDSA P-192?
+| Criteria | ECDSA P-192 | ECDSA P-256 | HMAC-SHA256 |
|---|---|---|---|
| Signature size | 48 bytes | 64 bytes | 32 bytes |
| Security level | 96-bit | 128-bit | 256-bit |
| Key type | Asymmetric | Asymmetric | Symmetric |
| Client-side exposure | Private key per-device | Private key per-device | Shared secret |
+ P-192 was chosen over P-256 to minimize signature size (48 vs 64 bytes), which is important given + NTAG213's 144-byte memory constraint. The 96-bit security level is more than adequate for a drinks + credit system where the economic incentive for attacks is low. +
+ +3.3 Key Storage
+
+ The private key is AES-encrypted using the device secret (provided by the server via the
+ GET /pos-api/v1/devices/current API call) and stored in the browser's localStorage. This means:
+
-
+
- The private key can only be decrypted after successful device authentication +
- The device secret never leaves the server unencrypted in the management API +
- If localStorage is cleared, the key pair is lost and a new one must be generated and approved +
- When a new public key is submitted, the server automatically resets the approval status — an administrator must re-approve the new key +
- On approval, the device's own public key is registered in its local verification map so it can immediately read cards it signs +
+ +
4. Card Data Integrity
+ +4.1 Signature Scheme
+The ECDSA P-192 signature covers:
+signature = ECDSA_SIGN(
+ SHA-256(version_byte + device_id + card_data + card_hardware_uid),
+ device_private_key
+)Fields included in the signature:
+-
+
version_byte(1 byte): Prevents version downgrade attacks
+ device_id(3 bytes): Identifies the signing terminal
+ card_data(33 bytes): Balance, transaction count, timestamp, previous transactions, discount
+ card_hardware_uid(variable): The card's unique hardware identifier
+
4.2 Replay Attack Prevention
++ The card hardware UID is included in the signed data but not stored on the card (it's read from + the NFC hardware). This prevents an attacker from copying signed data from a high-balance card to a + low-balance card — the signature verification will fail because the hardware UIDs differ. +
+ +4.3 Version Detection
+Card data version is determined by the first byte of the payload:
+-
+
0x01→ Version 1 (ECDSA asymmetric)
+ - Any other value → Version 0 (legacy HMAC-SHA256) +
+ +
5. Key Management & Admin Workflow
+ +5.1 Key Generation
++ Key generation is an explicit manual action — it is never automatic. The POS terminal shows a modal + requiring the user to press "Generate Credentials". This ensures operators are aware that a new key pair will + be created and requires administrator approval. +
+ +5.2 Key Approval Flow
+-
+
- POS terminal generates key pair locally +
- Public key is uploaded to the server +
- Key enters "Pending" state — card operations blocked +
- Administrator approves the key via the admin dashboard +
- Terminal downloads approved keys — card operations now allowed +
5.3 Key Revocation
++ Administrators can instantly revoke a key if a terminal is compromised. The admin dashboard warns + that revocation is a destructive action because all cards last signed by that device will fail signature verification + and must be re-scanned at an approved terminal. +
+ +5.4 Device Soft-Delete
++ Deleting a POS device soft-deletes it, preserving the public key record and signed card tracking. This ensures + cards signed by the deleted device can still be verified, and the admin can still manage the device's key. +
+ ++ +
6. Offline Operation
+ +6.1 Transaction Splitting
++ Cards store the last 5 previous transaction amounts. When a POS terminal goes offline, these stored + transactions allow the system to reconstruct missing transaction history when connectivity is restored. +
+ +6.2 Transaction Merger
+
+ The TransactionMerger handles reconciliation of transactions received from different terminals
+ in potentially different order. It uses database-level locking to prevent race conditions and maintains an
+ "overflow" transaction to absorb balance discrepancies.
+
+ +
7. Physical Security
+ +7.1 NFC Write Protection
++ The nfc-socketio service applies a write password + to the NFC tags, derived from the organisation secret and card UID. While NTAG213's 4-byte password is + insufficient for cryptographic security, it prevents accidental overwrites. +
+ +7.2 NTAG213 Memory Layout
+| Component | Size |
|---|---|
| NTAG213 user memory | 144 bytes |
| TLV overhead | 3 bytes |
| Max NDEF message | 141 bytes |
| URI record (topup URL) | ~37 bytes |
| External record (v1 data) | ~104 bytes |
+ +
8. Defence in Depth
++ The system employs multiple layers of security that must all be defeated for a successful attack: +
+-
+
- NFC write password — prevents casual overwrites (low security, 4 bytes) +
- ECDSA signature — prevents balance forgery without the private key (high security, 96-bit) +
- Hardware UID binding — prevents cross-card replay attacks +
- Admin key approval — prevents rogue terminal injection +
- Server reconciliation — detects anomalies after the fact +
- Monotonic counter — detects rollback/replay of stale card states +
+ +
9. Summary of Security Measures
+| Measure | Protection Against |
|---|---|
| Per-device ECDSA key pairs | Key interception, shared secret compromise |
| Card hardware UID in signature | Replay attacks across cards |
| Admin key approval | Rogue terminals |
| Key revocation with impact tracking | Compromised terminals |
| Monotonic transaction counter | Card state rollback/replay |
| Server-side balance reconciliation | Undetected balance manipulation |
| Maximum balance enforcement | Unrealistic balance forgery |
| Version byte in signature | Version downgrade attacks |
| NFC write password | Accidental overwrites |
| Offline transaction recovery | Data loss from connectivity issues |
+ +