Skip to content

Commit 9fd6614

Browse files
codebutlerclaudeClaude
authored
Add Ultralight GET_VERSION protocol for enhanced card type detection (#217)
* Port CEPASProtocol from Metrodroid to fix APDU framing Fixes #191 The old FareBot CEPASProtocol manually built APDU commands but omitted the Le (expected response length) byte, causing cards to reject with 6D00 (instruction not supported). Replaced with Metrodroid's approach that delegates to ISO7816Protocol.sendRequest() for proper APDU framing. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add Ultralight GET_VERSION protocol for enhanced card type detection - Port UltralightProtocol from Metrodroid with GET_VERSION (0x60) and AUTH_1 (0x1a) commands - Add transceive() and reconnect() methods to UltralightTechnology interface - Implement transceive in all platform adapters (Android, iOS, JVM/PCSC) - Create UltralightTypeRaw for parsing protocol responses - Detect 7 card variants: MF0ICU1, MF0ICU2, EV1_MF0UL11, EV1_MF0UL21, NTAG213, NTAG215, NTAG216 - Fall back to platform-reported type if protocol detection fails - Use correct page counts for each card type to avoid read errors Fixes item 2C from card module work list. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Apply ktlintFormat Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add regression tests for Ultralight GET_VERSION protocol Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix CI: implement transceive() in PN533UltralightTechnology The UltralightTechnology interface now requires transceive(). Delegate to pn533.inDataExchange() matching the pattern used by readPages(). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix ktlint: inline single-line body expression in transceive() Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: implement transceive() in FakeUltralightTechnology test Add UltralightCardReaderTest.kt with transceive() in FakeUltralightTechnology that simulates protocol-level GET_VERSION, AUTH_1, and HALT commands. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * ci: retrigger build * chore: normalize trailing newline * fix: correct page count assertions in UltralightCardReaderTest Reader uses size = pageCount - 1, so assertions should expect pageCount - 1 pages, not pageCount. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Claude <claude@codebutler.com>
1 parent 828d302 commit 9fd6614

File tree

10 files changed

+550
-19
lines changed

10 files changed

+550
-19
lines changed

‎card/src/androidMain/kotlin/com/codebutler/farebot/card/nfc/AndroidUltralightTechnology.kt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,4 +42,11 @@ class AndroidUltralightTechnology(
4242
get() = mifareUltralight.type
4343

4444
override fun readPages(pageOffset: Int): ByteArray = mifareUltralight.readPages(pageOffset)
45+
46+
override fun transceive(data: ByteArray): ByteArray = mifareUltralight.transceive(data)
47+
48+
override fun reconnect() {
49+
mifareUltralight.close()
50+
mifareUltralight.connect()
51+
}
4552
}

‎card/src/commonMain/kotlin/com/codebutler/farebot/card/nfc/UltralightTechnology.kt‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,22 @@ interface UltralightTechnology : NfcTechnology {
2727

2828
fun readPages(pageOffset: Int): ByteArray
2929

30+
/**
31+
* Sends raw data to the card and receives the response.
32+
* Used for protocol-level commands like GET_VERSION and AUTH_1.
33+
*/
34+
fun transceive(data: ByteArray): ByteArray
35+
36+
/**
37+
* Reconnects to the card after a disconnect.
38+
* Some protocol commands (GET_VERSION, AUTH_1) may cause the card to disconnect.
39+
*/
40+
fun reconnect() {
41+
// Default implementation: close and connect
42+
close()
43+
connect()
44+
}
45+
3046
companion object {
3147
const val PAGE_SIZE = 4
3248
const val TYPE_ULTRALIGHT = 1

‎card/src/iosMain/kotlin/com/codebutler/farebot/card/nfc/IosUltralightTechnology.kt‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,4 +87,25 @@ class IosUltralightTechnology(
8787
return result?.toByteArray()
8888
?: throw Exception("Ultralight read returned null at page $pageOffset")
8989
}
90+
91+
override fun transceive(data: ByteArray): ByteArray {
92+
val semaphore = dispatch_semaphore_create(0)
93+
var result: NSData? = null
94+
var nfcError: NSError? = null
95+
96+
tag.sendMiFareCommand(data.toNSData()) { response: NSData?, error: NSError? ->
97+
result = response
98+
nfcError = error
99+
dispatch_semaphore_signal(semaphore)
100+
}
101+
102+
dispatch_semaphore_wait(semaphore, DISPATCH_TIME_FOREVER)
103+
104+
nfcError?.let {
105+
throw Exception("Ultralight transceive failed: ${it.localizedDescription}")
106+
}
107+
108+
return result?.toByteArray()
109+
?: throw Exception("Ultralight transceive returned null")
110+
}
90111
}

‎card/src/jvmMain/kotlin/com/codebutler/farebot/card/nfc/PCSCUltralightTechnology.kt‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,4 +58,15 @@ class PCSCUltralightTechnology(
5858
}
5959
return response.data
6060
}
61+
62+
override fun transceive(data: ByteArray): ByteArray {
63+
// For raw transceive, we need to send the data as-is through PC/SC
64+
// This is used for GET_VERSION (0x60) and AUTH_1 (0x1A) commands
65+
val command = CommandAPDU(0xFF, 0x00, 0x00, 0x00, data)
66+
val response = channel.transmit(command)
67+
if (response.sW1 != 0x90 || response.sW2 != 0x00) {
68+
throw Exception("Transceive failed: SW=%02X%02X".format(response.sW1, response.sW2))
69+
}
70+
return response.data
71+
}
6172
}

‎card/src/jvmMain/kotlin/com/codebutler/farebot/card/nfc/pn533/PN533UltralightTechnology.kt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,8 @@ class PN533UltralightTechnology(
5555
byteArrayOf(MIFARE_CMD_READ, pageOffset.toByte()),
5656
)
5757

58+
override fun transceive(data: ByteArray): ByteArray = pn533.inDataExchange(tg, data)
59+
5860
companion object {
5961
const val MIFARE_CMD_READ: Byte = 0x30
6062
}

‎card/ultralight/src/commonMain/kotlin/com/codebutler/farebot/card/ultralight/UltralightCardReader.kt‎

Lines changed: 40 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,11 +32,23 @@ object UltralightCardReader {
3232
tagId: ByteArray,
3333
tech: UltralightTechnology,
3434
): RawUltralightCard {
35+
// Detect card type using protocol commands (GET_VERSION, AUTH_1)
36+
val detectedType = detectCardType(tech)
37+
println("UltralightCardReader: Detected card type: $detectedType")
38+
39+
// Determine page count based on detected type
40+
val pageCount = detectedType.pageCount
3541
val size: Int =
36-
when (tech.type) {
37-
UltralightTechnology.TYPE_ULTRALIGHT -> UltralightCard.ULTRALIGHT_SIZE
38-
UltralightTechnology.TYPE_ULTRALIGHT_C -> UltralightCard.ULTRALIGHT_C_SIZE
39-
else -> throw IllegalArgumentException("Unknown Ultralight type " + tech.type)
42+
if (pageCount > 0) {
43+
// Use detected page count (subtract 1 because we read pages 0..size inclusive)
44+
pageCount - 1
45+
} else {
46+
// Fall back to platform-reported type if detection failed
47+
when (tech.type) {
48+
UltralightTechnology.TYPE_ULTRALIGHT -> UltralightCard.ULTRALIGHT_SIZE
49+
UltralightTechnology.TYPE_ULTRALIGHT_C -> UltralightCard.ULTRALIGHT_C_SIZE
50+
else -> throw IllegalArgumentException("Unknown Ultralight type " + tech.type)
51+
}
4052
}
4153

4254
var pageNumber = 0
@@ -72,4 +84,28 @@ object UltralightCardReader {
7284

7385
return RawUltralightCard.create(tagId, Clock.System.now(), pages, tech.type)
7486
}
87+
88+
/**
89+
* Detects the Ultralight card type using protocol commands.
90+
*
91+
* This uses GET_VERSION (0x60) and AUTH_1 (0x1a) commands to distinguish between:
92+
* - MF0ICU1 (Ultralight) - 16 pages
93+
* - MF0ICU2 (Ultralight C) - 44 pages
94+
* - EV1_MF0UL11 (Ultralight EV1 48 bytes) - 20 pages
95+
* - EV1_MF0UL21 (Ultralight EV1 128 bytes) - 41 pages
96+
* - NTAG213 - 45 pages
97+
* - NTAG215 - 135 pages
98+
* - NTAG216 - 231 pages
99+
*
100+
* Falls back to UNKNOWN if detection fails.
101+
*/
102+
private fun detectCardType(tech: UltralightTechnology): UltralightCard.UltralightType =
103+
try {
104+
val protocol = UltralightProtocol(tech)
105+
val rawType = protocol.getCardType()
106+
rawType.parse()
107+
} catch (e: Exception) {
108+
println("UltralightCardReader: Card type detection failed, falling back to UNKNOWN: $e")
109+
UltralightCard.UltralightType.UNKNOWN
110+
}
75111
}

‎card/ultralight/src/commonMain/kotlin/com/codebutler/farebot/card/ultralight/UltralightProtocol.kt‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
/*
2+
* UltralightProtocol.kt
3+
*
4+
* Copyright 2018 Michael Farrell <micolous+git@gmail.com>
5+
* Copyright 2025 Eric Butler <eric@codebutler.com>
6+
*
7+
* Ported from Metrodroid (https://github.com/metrodroid/metrodroid)
8+
*
9+
* This program is free software: you can redistribute it and/or modify
10+
* it under the terms of the GNU General Public License as published by
11+
* the Free Software Foundation, either version 3 of the License, or
12+
* (at your option) any later version.
13+
*
14+
* This program is distributed in the hope that it will be useful,
15+
* but WITHOUT ANY WARRANTY; without even the implied warranty of
16+
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17+
* GNU General Public License for more details.
18+
*
19+
* You should have received a copy of the GNU General Public License
20+
* along with this program. If not, see <http://www.gnu.org/licenses/>.
21+
*/
22+
23+
package com.codebutler.farebot.card.ultralight
24+
25+
import com.codebutler.farebot.base.util.hex
26+
import com.codebutler.farebot.card.nfc.UltralightTechnology
27+
28+
/**
29+
* Low level commands for MIFARE Ultralight.
30+
*
31+
* Android has MIFARE Ultralight support, but it is quite limited. It doesn't support detection of
32+
* EV1 cards, and also doesn't reliably detect Ultralight C cards. This class uses some
33+
* functionality adapted from the Proxmark3, as well as sniffed communication from NXP TagInfo.
34+
*
35+
* Reference:
36+
* MF0ICU1 (Ultralight): https://www.nxp.com/docs/en/data-sheet/MF0ICU1.pdf
37+
* MF0ICU2 (Ultralight C): https://www.nxp.com/docs/en/data-sheet/MF0ICU2_SDS.pdf
38+
* MF0UCx1 (Ultralight EV1): https://www.nxp.com/docs/en/data-sheet/MF0ULX1.pdf
39+
* NTAG213/215/216: https://www.nxp.com/docs/en/data-sheet/NTAG213_215_216.pdf
40+
* MIFARE Commands: https://www.nxp.com/docs/en/application-note/AN10833.pdf
41+
*/
42+
internal class UltralightProtocol(
43+
private val mTagTech: UltralightTechnology,
44+
) {
45+
/**
46+
* Gets the MIFARE Ultralight card type.
47+
*
48+
* Android has `MIFAREUltralight.getType()`, but this is lacking:
49+
*
50+
* 1. It cannot detect Ultralight EV1 cards correctly, which have different memory sizes.
51+
*
52+
* 2. It cannot detect the size of fully locked cards correctly.
53+
*
54+
* This is a much more versatile test, based on sniffing what NXP TagInfo does, and Proxmark3's
55+
* `GetHF14AMfU_Type` function. Android can't do bad checksums (eg: PM3 Fudan/clone check) and
56+
* Metrodroid never writes to cards (eg: PM3 Magic check), so we don't do all of the checks.
57+
*
58+
* @return MIFARE Ultralight card type.
59+
* @throws Exception On card communication error (eg: reconnects)
60+
*/
61+
fun getCardType(): UltralightTypeRaw {
62+
// Try EV1's GET_VERSION command
63+
// This isn't supported by non-UL EV1s, and will cause those cards to disconnect.
64+
try {
65+
return UltralightTypeRaw(versionCmd = getVersion())
66+
} catch (e: Exception) {
67+
println("UltralightProtocol: getVersion returned error, not EV1: $e")
68+
}
69+
70+
// Reconnect the tag
71+
mTagTech.reconnect()
72+
73+
// Try to get a nonce for 3DES authentication with Ultralight C.
74+
try {
75+
val b2 = auth1()
76+
println("UltralightProtocol: auth1 said = ${b2.hex()}")
77+
} catch (e: Exception) {
78+
// Non-C cards will disconnect here.
79+
println("UltralightProtocol: auth1 returned error, not Ultralight C: $e")
80+
81+
// TODO: PM3 says NTAG 203 (with different memory size) also looks like this.
82+
83+
mTagTech.reconnect()
84+
return UltralightTypeRaw(repliesToAuth1 = false)
85+
}
86+
87+
// To continue, we need to halt the auth attempt.
88+
halt()
89+
mTagTech.reconnect()
90+
91+
return UltralightTypeRaw(repliesToAuth1 = true)
92+
}
93+
94+
/**
95+
* Gets the version data from the card. This only works with MIFARE Ultralight EV1 cards.
96+
* @return ByteArray containing data according to Table 15 in MFU-EV1 datasheet.
97+
* @throws Exception on card communication failure, or if the card does not support the
98+
* command.
99+
*/
100+
private fun getVersion(): ByteArray = sendRequest(GET_VERSION)
101+
102+
/**
103+
* Gets a nonce for 3DES authentication from the card. This only works on MIFARE Ultralight C
104+
* cards. Authentication is not implemented in FareBot or Android.
105+
* @return AUTH_ANSWER message from card.
106+
* @throws Exception on card communication failure, or if the card does not support the
107+
* command.
108+
*/
109+
private fun auth1(): ByteArray = sendRequest(AUTH_1, 0x00.toByte())
110+
111+
/**
112+
* Instructs the card to terminate its session. This is supported by all Ultralight cards.
113+
*
114+
* This will silently swallow all communication failures, as Android returning an error is
115+
* to be expected.
116+
*/
117+
private fun halt() {
118+
try {
119+
sendRequest(HALT, 0x00.toByte())
120+
} catch (e: Exception) {
121+
// When the card halts, the tag may report an error up through the stack. This is fine.
122+
// Unfortunately we can't tell if the card was removed or we need to reset it.
123+
println("UltralightProtocol: Discarding exception in halt, this probably expected: $e")
124+
}
125+
}
126+
127+
private fun sendRequest(vararg data: Byte): ByteArray {
128+
println("UltralightProtocol: sent card: ${data.hex()}")
129+
130+
return mTagTech.transceive(data)
131+
}
132+
133+
companion object {
134+
private const val TAG = "UltralightProtocol"
135+
136+
// Commands
137+
private const val GET_VERSION = 0x60.toByte()
138+
private const val AUTH_1 = 0x1a.toByte()
139+
private const val HALT = 0x50.toByte()
140+
141+
// Status codes
142+
const val AUTH_ANSWER = 0xAF.toByte()
143+
}
144+
}

0 commit comments

Comments
 (0)