Add more details on phase 1 and 2 for purchase/credit/overdraft

This commit is contained in:
klks committed 2026-05-25 15:05:16 +08:00
1 parent 57234ba459
commit 1fea325d6f
1 file changed
+169 -32
+169 -32
View File
@@ -114,11 +114,44 @@ hf fmcos createdir --id 3f01 --space 1500 --cperm f0 --eperm f0 --appid 95 --nam
|------|-------------|
| `--id <hex>` | 2-byte file ID for the new DF |
| `--space <hex>` | Total byte space to reserve (hex, e.g. `1500` = 5376 bytes) |
| `--cperm <hex>` | Create-permission byte (e.g. `f0` = always allowed) |
| `--eperm <hex>` | Erase-permission byte |
| `--appid <hex>` | 1-byte application SID / AID tag |
| `--cperm <hex>` | Create-permission byte - who may create files inside this DF |
| `--eperm <hex>` | Erase-permission byte - who may erase this DF |
| `--appid <hex>` | 1-byte application file ID (DF type + short identifier) |
| `--name <hex>` | Optional DF name bytes as hex (up to 16 bytes, enables select-by-name) |
**`--cperm` (create permission):**
Controls the minimum security state required to create new EFs or sub-DFs inside this DF.
Uses the same XY nibble encoding as `--rperm` / `--wperm` in `createfile` (see the permission byte table there).
After `erase` clears the DF, the create-permission check is suspended and any file may be created freely.
The restriction is reinstated the next time the DF is re-entered once a KEY file has been established inside it.
**`--eperm` (erase permission):**
Controls the minimum security state required to run `erase` on this DF.
Uses the same XY nibble encoding.
Erasing a DF destroys all EFs and sub-DFs inside it; the DF record, its permissions, and its allocated space
are preserved.
Set to `ef` to prohibit erasing entirely: since E (14) < F (15), the range E..F is impossible and the condition
can never be satisfied.
**`--appid` (application file ID):**
A 1-byte value stored in the DF control block that encodes both the DF type and a short numeric identifier.
| Bits 7-5 | Meaning |
|----------|---------|
| `000` | Dedicated Directory File (DDF) - a plain directory, no application context |
| `100` | Application Dedicated File (ADF) - holds a PBOC / EMV application |
Bits 4-0 are the short file identifier (0-31) used by the card to link this DF to its keyfile.
This value must equal the `--dfsid` argument when creating the keyfile for this DF with `createkeyfile`.
Example: `--appid 95` = binary `10010101` - bits 7-5 are `100` (ADF), bits 4-0 are `10101` = 21 = `0x15`,
so the FCI returned on SELECT FILE references short identifier `0x15` and the matching keyfile uses `--dfsid 95`.
Standard PBOC wallet DFs conventionally use `0x95`.
### createfile
CREATE EF (elementary file) in the currently selected DF.
@@ -616,16 +649,43 @@ Example output:
### credit
ADD CREDIT -- two-phase credit transaction.
ADD CREDIT -- two-phase credit (load) transaction (PBOC INITIALIZE FOR LOAD + CREDIT FOR LOAD).
**Phase 1** (`INS 50`, P1=00): send key ID, amount, terminal ID. Card returns old balance,
transaction serial, key version, algo ID, random seed, and MAC1. The implementation:
- Derives the process key: `encrypt(random[4] | serial[2], credit_key)` -> first 8 bytes
- Verifies MAC1: `DES-CBC-MAC(old_bal[4] | amount[4] | type[1] | terminal[6], process_key)`
**Phase 1 -- INITIALIZE FOR LOAD** (`INS 50`, P1=00):
**Phase 2** (`INS 52`, P1=00): send date, time, MAC2. Card returns TAC. The implementation:
- Computes MAC2: `DES-CBC-MAC(amount[4] | type[1] | terminal[6] | date[4] | time[3], process_key)`
- Verifies TAC: `DES-CBC-MAC(new_bal[4] | serial[2] | MAC2_buf[18], tac_key)`
Initiates the credit transaction and authenticates the card to the terminal.
The terminal sends the credit key slot ID, the load amount (4 bytes), and the terminal ID (6 bytes).
The card responds with 16 bytes:
| Field | Length | Description |
|-------|--------|-------------|
| Old balance | 4 bytes | Current balance before loading |
| Online serial number | 2 bytes | Incremented by the card after each successful load |
| Key version | 1 byte | Version of the credit key identified by the key slot ID |
| Algorithm ID | 1 byte | Algorithm of that credit key |
| Random seed | 4 bytes | Card-generated pseudorandom number for session key derivation |
| MAC1 | 4 bytes | Card-computed MAC proving it holds the credit key |
The session key (process key) is derived as: `encrypt(random[4] | serial[2] | 0x8000, credit_key)`, first 8 bytes.
MAC1 is: `DES-CBC-MAC(old_bal[4] | amount[4] | type[1] | terminal[6], process_key)`.
The terminal verifies MAC1 to confirm the card holds the correct key before proceeding.
If MAC1 does not match, the transaction is aborted and the balance is unchanged.
**Phase 2 -- CREDIT FOR LOAD** (`INS 52`, P1=00):
Authorizes and commits the balance update.
The terminal sends the host transaction date (4 bytes), time (3 bytes), and MAC2 (4 bytes).
MAC2 is: `DES-CBC-MAC(amount[4] | type[1] | terminal[6] | date[4] | time[3], process_key)`.
On success the card:
- Adds the loaded amount to the balance.
- Increments the online serial number by 1.
- Appends a 23-byte transaction record (serial, overdraft limit, amount, type, terminal, date, time) to the linked loop EF for auditing.
The card responds with the TAC (Transaction Authentication Code, 4 bytes):
`DES-CBC-MAC(new_bal[4] | serial[2] | amount[4] | type[1] | terminal[6] | date[4] | time[3], dtk_xor)`,
where `dtk_xor` is the left 8 bytes XOR right 8 bytes of the internal key (DTK).
The terminal verifies the TAC to confirm the card committed the transaction.
```
hf fmcos credit --type wallet --id 01 --amount 1000 \
@@ -662,17 +722,56 @@ Example output:
### purchase
PURCHASE -- two-phase debit transaction from wallet or passbook.
PURCHASE -- two-phase offline debit transaction from wallet or passbook
(PBOC INITIALIZE FOR PURCHASE + DEBIT FOR PURCHASE).
**Phase 1** (`INS 50`, P1=01): send key ID, amount, terminal. Card returns old balance,
offline serial, overdraft limit, key version, algo, random seed (15 bytes total).
- Derives process key: `encrypt(random[4] | offline_serial[2] | tx_serial[2], purchase_key)[:8]`
- Computes MAC1: `DES-CBC-MAC(amount[4] | tx_type[1] | terminal[6] | date[4] | time[3], process_key)`
Passbook purchase requires a successful PIN verify beforehand; wallet purchase does not.
**Phase 2** (`INS 54`, P1=01, P2=00): send tx serial, date, time, MAC1. Card returns TAC[4]+MAC2[4].
- Verifies TAC: `DES-CBC-MAC(amount[4] | tx_type[1] | terminal[6] | serial[4] | date[4] | time[3], tac_key)`
**Phase 1 -- INITIALIZE FOR PURCHASE** (`INS 50`, P1=01):
Transaction type byte: 0x05 for passbook purchase, 0x06 for wallet purchase.
Initiates the purchase transaction and returns the card state needed for the terminal to derive
the session key and compute the authorization MAC.
The terminal sends the purchase key slot ID, the debit amount (4 bytes), and the terminal ID (6 bytes).
The card responds with 15 bytes:
| Field | Length | Description |
|-------|--------|-------------|
| Old balance | 4 bytes | Current balance before the debit |
| Offline serial number | 2 bytes | Incremented by the card after each successful purchase |
| Overdraft limit | 3 bytes | Maximum permitted overdraft on this file |
| Key version | 1 byte | Version of the purchase key identified by the key slot ID |
| Algorithm ID | 1 byte | Algorithm of that purchase key |
| Random seed | 4 bytes | Card-generated pseudorandom number for session key derivation |
Unlike the credit transaction, the card does not return a MAC1 in this phase.
Instead, the terminal uses the card's response to derive the session key and compute MAC1 locally:
- Session key (process key): `encrypt(random[4] | offline_serial[2] | tx_serial_low2[2], purchase_key)[:8]`,
where `tx_serial_low2` is the rightmost 2 bytes of the terminal transaction serial number.
- MAC1 (computed by terminal): `DES-CBC-MAC(amount[4] | type[1] | terminal[6] | date[4] | time[3], process_key)`.
If the card returns a non-9000 status the transaction is aborted and the balance is unchanged.
**Phase 2 -- DEBIT FOR PURCHASE** (`INS 54`, P1=01, P2=00):
Authorizes and commits the balance deduction.
The terminal sends the terminal transaction serial (4 bytes), date (4 bytes), time (3 bytes), and MAC1 (4 bytes).
The card verifies MAC1, then deducts the amount and returns 8 bytes:
| Field | Length | Description |
|-------|--------|-------------|
| TAC | 4 bytes | Transaction Authentication Code for terminal verification |
| MAC2 | 4 bytes | Card-computed MAC over the debit amount |
TAC is: `DES-CBC-MAC(amount[4] | type[1] | terminal[6] | tx_serial[4] | date[4] | time[3], dtk_xor)`,
where `dtk_xor` is the left 8 bytes XOR right 8 bytes of the internal key (DTK).
MAC2 is: `DES-CBC-MAC(amount[4], process_key)`.
On success the card:
- Deducts the purchase amount from the balance.
- Increments the offline serial number by 1.
Transaction type byte: `0x05` for passbook purchase, `0x06` for wallet purchase.
```
# Wallet purchase of 50 units
@@ -710,20 +809,58 @@ Example output:
### overdraft
UPDATE OVERDRAFT LIMIT -- two-phase overdraft-limit update on the passbook.
UPDATE OVERDRAFT LIMIT -- two-phase online overdraft-limit update on the passbook
(PBOC INITIALIZE FOR UPDATE + UPDATE OVERDRAW LIMIT).
**Phase 1** (`INS 50`, P1=04, P2=01): send key ID and terminal. Card returns old balance,
online serial, old limit, key version, algo, random seed, and MAC1 (19 bytes total).
- Derives process key: `encrypt(random[4] | serial[2], overdraft_key)[:8]`
- Verifies MAC1: `DES-CBC-MAC(old_bal[4] | old_limit[3] | 0x07[1] | terminal[6], process_key)`
The overdraft limit allows transactions to continue when the actual passbook funds are
insufficient, up to the issuer-permitted limit.
This transaction must be performed online at a financial terminal and requires a successful
PIN verify beforehand. It applies to passbook only; wallet files do not carry an overdraft limit.
**Phase 2** (`INS 58`, P1=00, P2=00): send new limit (3 bytes), date, time, MAC2.
- Computes MAC2: `DES-CBC-MAC(new_limit[3] | 0x07[1] | terminal[6] | date[4] | time[3], process_key)`
- Card returns TAC[4]. When `--ikey` is provided the TAC is verified:
`DES-CBC-MAC(XOR(ikey[0:8], ikey[8:16]), tac_bal[4] | online_serial[2] | new_limit[3] | 0x07[1] | terminal[6] | date[4] | time[3])`
where `tac_bal = old_balance + new_limit - old_od_limit`. The card stores
`actual_funds + overdraft_limit` as its balance field, so when the limit changes the new
stored balance shifts by the limit delta.
**Phase 1 -- INITIALIZE FOR UPDATE** (`INS 50`, P1=04, P2=01):
Initiates the overdraft-limit update and authenticates the card to the terminal.
The terminal sends the overdraft key slot ID (1 byte) and the terminal ID (6 bytes).
Note that no amount is sent in this phase; the new limit is supplied in Phase 2.
The card responds with 19 bytes:
| Field | Length | Description |
|-------|--------|-------------|
| Old balance | 4 bytes | Current stored balance (actual funds + current overdraft limit) |
| Online serial number | 2 bytes | Incremented by the card after each successful online transaction |
| Old overdraft limit | 3 bytes | Current overdraft limit before the update |
| Key version | 1 byte | Version of the overdraft key identified by the key slot ID |
| Algorithm ID | 1 byte | Algorithm of that overdraft key |
| Random seed | 4 bytes | Card-generated pseudorandom number for session key derivation |
| MAC1 | 4 bytes | Card-computed MAC proving it holds the overdraft key |
Session key (process key): `encrypt(random[4] | serial[2] | 0x8000, overdraft_key)[:8]`.
MAC1 is: `DES-CBC-MAC(old_bal[4] | old_limit[3] | 0x07[1] | terminal[6], process_key)`,
where `0x07` is the fixed transaction type identifier for overdraft limit updates.
The terminal verifies MAC1 to confirm the card holds the correct key before proceeding.
If MAC1 does not match, the transaction is aborted and the limit is unchanged.
**Phase 2 -- UPDATE OVERDRAW LIMIT** (`INS 58`, P1=00, P2=00):
Authorizes and commits the new overdraft limit.
The terminal sends the new limit (3 bytes), host transaction date (4 bytes), time (3 bytes),
and MAC2 (4 bytes).
MAC2 is: `DES-CBC-MAC(new_limit[3] | 0x07[1] | terminal[6] | date[4] | time[3], process_key)`.
The card responds with TAC (4 bytes).
TAC is: `DES-CBC-MAC(tac_bal[4] | serial[2] | new_limit[3] | 0x07[1] | terminal[6] | date[4] | time[3], dtk_xor)`,
where `dtk_xor` is the left 8 bytes XOR right 8 bytes of the internal key (DTK), and
`tac_bal = old_balance + new_limit - old_overdraft_limit` (the new stored balance after the limit shift).
The card stores `actual_funds + overdraft_limit` as its balance field, so changing the limit
by a delta shifts the stored balance value by the same delta without altering actual funds.
On success the card:
- Updates the overdraft limit to the new value.
- Adjusts the stored balance to `actual_funds + new_limit`.
- Increments the online serial number by 1.
- Appends a 23-byte transaction record (serial, new limit, amount, type `0x07`, terminal, date, time)
to the linked loop EF for auditing.
```
hf fmcos overdraft --id 01 --limit 1000 \
@@ -746,9 +883,9 @@ Example output:
```
[=] Old balance: 1000 old overdraft limit: 0
[=] MAC1 OK
[+] SW: 9000 - Success
[+] Overdraft limit updated to 1000
[+] TAC OK aabbccdd
[+] SW: 9000 - Success
```
### history