NFC: Add support for Gallagher access control (MIFARE Classic only) (#3306)

* Merge remote-tracking branch 'origin/dev' into dev
* Add basic API interface (inspired by advanced plugins example), modify NfcSupportedCardsLoadContext to contain a pointer to a resolver
* WIP: API resolver implemented / passed to plugin via context, still having resolution issues
* Attempt to add constants to the nfc_app_api_table list
* WIP: We're defining the constants directly in nfc_app_api.c to see if this fixes our woes, which it does not.
* WIP: Remove furi_assert(false) (lmao)
* Working implementation of Gallagher decoding via exposed plugin API
* lib: api_hashtable: change log level for symbol not found message
* nfc app: alloc composite resolver along with supported cards
* nfc app: rework nfc api structure
* nfc app: fix memory leakage in supported cards

Co-authored-by: gornekich <n.gorbadey@gmail.com>

applications/main/nfc/api/gallagher/gallagher_util.c

@@ -0,0 +1,59 @@
+/* gallagher_util.c - Utilities for parsing Gallagher cards (New Zealand).
+ * Author: Nick Mooney (nick@mooney.nz)
+ * 
+ * Reference: https://github.com/megabug/gallagher-research
+*/
+
+#include "gallagher_util.h"
+
+#define GALLAGHER_CREDENTIAL_SECTOR 15
+
+/* The Gallagher obfuscation algorithm is a 256-byte substitution table. The below array is generated from
+ * https://github.com/megabug/gallagher-research/blob/master/formats/cardholder/substitution-table.bin.
+*/
+const uint8_t GALLAGHER_DECODE_TABLE[256] = {
+    0x2f, 0x6e, 0xdd, 0xdf, 0x1d, 0xf,  0xb0, 0x76, 0xad, 0xaf, 0x7f, 0xbb, 0x77, 0x85, 0x11,
+    0x6d, 0xf4, 0xd2, 0x84, 0x42, 0xeb, 0xf7, 0x34, 0x55, 0x4a, 0x3a, 0x10, 0x71, 0xe7, 0xa1,
+    0x62, 0x1a, 0x3e, 0x4c, 0x14, 0xd3, 0x5e, 0xb2, 0x7d, 0x56, 0xbc, 0x27, 0x82, 0x60, 0xe3,
+    0xae, 0x1f, 0x9b, 0xaa, 0x2b, 0x95, 0x49, 0x73, 0xe1, 0x92, 0x79, 0x91, 0x38, 0x6c, 0x19,
+    0xe,  0xa9, 0xe2, 0x8d, 0x66, 0xc7, 0x5a, 0xf5, 0x1c, 0x80, 0x99, 0xbe, 0x4e, 0x41, 0xf0,
+    0xe8, 0xa6, 0x20, 0xab, 0x87, 0xc8, 0x1e, 0xa0, 0x59, 0x7b, 0xc,  0xc3, 0x3c, 0x61, 0xcc,
+    0x40, 0x9e, 0x6,  0x52, 0x1b, 0x32, 0x8c, 0x12, 0x93, 0xbf, 0xef, 0x3b, 0x25, 0xd,  0xc2,
+    0x88, 0xd1, 0xe0, 0x7,  0x2d, 0x70, 0xc6, 0x29, 0x6a, 0x4d, 0x47, 0x26, 0xa3, 0xe4, 0x8b,
+    0xf6, 0x97, 0x2c, 0x5d, 0x3d, 0xd7, 0x96, 0x28, 0x2,  0x8,  0x30, 0xa7, 0x22, 0xc9, 0x65,
+    0xf8, 0xb7, 0xb4, 0x8a, 0xca, 0xb9, 0xf2, 0xd0, 0x17, 0xff, 0x46, 0xfb, 0x9a, 0xba, 0x8f,
+    0xb6, 0x69, 0x68, 0x8e, 0x21, 0x6f, 0xc4, 0xcb, 0xb3, 0xce, 0x51, 0xd4, 0x81, 0x0,  0x2e,
+    0x9c, 0x74, 0x63, 0x45, 0xd9, 0x16, 0x35, 0x5f, 0xed, 0x78, 0x9f, 0x1,  0x48, 0x4,  0xc1,
+    0x33, 0xd6, 0x4f, 0x94, 0xde, 0x31, 0x9d, 0xa,  0xac, 0x18, 0x4b, 0xcd, 0x98, 0xb8, 0x37,
+    0xa2, 0x83, 0xec, 0x3,  0xd8, 0xda, 0xe5, 0x7a, 0x6b, 0x53, 0xd5, 0x15, 0xa4, 0x43, 0xe9,
+    0x90, 0x67, 0x58, 0xc0, 0xa5, 0xfa, 0x2a, 0xb1, 0x75, 0x50, 0x39, 0x5c, 0xe6, 0xdc, 0x89,
+    0xfc, 0xcf, 0xfe, 0xf9, 0x57, 0x54, 0x64, 0xa8, 0xee, 0x23, 0xb,  0xf1, 0xea, 0xfd, 0xdb,
+    0xbd, 0x9,  0xb5, 0x5b, 0x5,  0x86, 0x13, 0xf3, 0x24, 0xc5, 0x3f, 0x44, 0x72, 0x7c, 0x7e,
+    0x36};
+
+// The second block of a Gallagher credential sector is the literal
+// "www.cardax.com  " (note two padding spaces)
+const uint8_t GALLAGHER_CARDAX_ASCII[MF_CLASSIC_BLOCK_SIZE] =
+    {'w', 'w', 'w', '.', 'c', 'a', 'r', 'd', 'a', 'x', '.', 'c', 'o', 'm', ' ', ' '};
+
+/* Precondition: cardholder_data_obfuscated points to at least 8 safe-to-read bytes of memory.
+*/
+void gallagher_deobfuscate_and_parse_credential(
+    GallagherCredential* credential,
+    const uint8_t* cardholder_data_obfuscated) {
+    uint8_t cardholder_data_deobfuscated[8];
+    for(int i = 0; i < 8; i++) {
+        cardholder_data_deobfuscated[i] = GALLAGHER_DECODE_TABLE[cardholder_data_obfuscated[i]];
+    }
+
+    // Pull out values from the deobfuscated data
+    credential->region = (cardholder_data_deobfuscated[3] >> 1) & 0x0F;
+    credential->facility = ((uint16_t)(cardholder_data_deobfuscated[5] & 0x0F) << 12) +
+                           ((uint16_t)cardholder_data_deobfuscated[1] << 4) +
+                           (((uint16_t)cardholder_data_deobfuscated[7] >> 4) & 0x0F);
+    credential->card = ((uint32_t)cardholder_data_deobfuscated[0] << 16) +
+                       ((uint32_t)(cardholder_data_deobfuscated[4] & 0x1F) << 11) +
+                       ((uint32_t)cardholder_data_deobfuscated[2] << 3) +
+                       (((uint32_t)cardholder_data_deobfuscated[3] >> 5) & 0x07);
+    credential->issue = cardholder_data_deobfuscated[7] & 0x0F;
+}

applications/main/nfc/api/gallagher/gallagher_util.h

@@ -0,0 +1,33 @@
+/* gallagher_util.h - Utilities for parsing Gallagher cards (New Zealand).
+ * Author: Nick Mooney (nick@mooney.nz)
+ * 
+ * Reference: https://github.com/megabug/gallagher-research
+*/
+
+#pragma once
+
+#include <lib/nfc/protocols/mf_classic/mf_classic.h>
+
+#define GALLAGHER_CREDENTIAL_SECTOR 15
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+extern const uint8_t GALLAGHER_DECODE_TABLE[256];
+extern const uint8_t GALLAGHER_CARDAX_ASCII[MF_CLASSIC_BLOCK_SIZE];
+
+typedef struct GallagherCredential {
+    uint8_t region;
+    uint8_t issue;
+    uint16_t facility;
+    uint32_t card;
+} GallagherCredential;
+
+void gallagher_deobfuscate_and_parse_credential(
+    GallagherCredential* credential,
+    const uint8_t* cardholder_data_obfuscated);
+
+#ifdef __cplusplus
+}
+#endif

applications/main/nfc/api/nfc_app_api_interface.h

@@ -0,0 +1,9 @@
+#pragma once
+
+#include <flipper_application/api_hashtable/api_hashtable.h>
+
+/* 
+ * Resolver interface with private application's symbols. 
+ * Implementation is contained in app_api_table.c
+ */
+extern const ElfApiInterface* const nfc_application_api_interface;

applications/main/nfc/api/nfc_app_api_table.cpp

@@ -0,0 +1,27 @@
+#include <flipper_application/api_hashtable/api_hashtable.h>
+#include <flipper_application/api_hashtable/compilesort.hpp>
+
+/* 
+ * This file contains an implementation of a symbol table 
+ * with private app's symbols. It is used by composite API resolver
+ * to load plugins that use internal application's APIs.
+ */
+#include "nfc_app_api_table_i.h"
+
+static_assert(!has_hash_collisions(nfc_app_api_table), "Detected API method hash collision!");
+
+constexpr HashtableApiInterface nfc_application_hashtable_api_interface{
+    {
+        .api_version_major = 0,
+        .api_version_minor = 0,
+        /* generic resolver using pre-sorted array */
+        .resolver_callback = &elf_resolve_from_hashtable,
+    },
+    /* pointers to application's API table boundaries */
+    .table_cbegin = nfc_app_api_table.cbegin(),
+    .table_cend = nfc_app_api_table.cend(),
+};
+
+/* Casting to generic resolver to use in Composite API resolver */
+extern "C" const ElfApiInterface* const nfc_application_api_interface =
+    &nfc_application_hashtable_api_interface;

applications/main/nfc/api/nfc_app_api_table_i.h

@@ -0,0 +1,13 @@
+#include "gallagher/gallagher_util.h"
+
+/* 
+ * A list of app's private functions and objects to expose for plugins.
+ * It is used to generate a table of symbols for import resolver to use.
+ * TBD: automatically generate this table from app's header files
+ */
+static constexpr auto nfc_app_api_table = sort(create_array_t<sym_entry>(
+    API_METHOD(
+        gallagher_deobfuscate_and_parse_credential,
+        void,
+        (GallagherCredential * credential, const uint8_t* cardholder_data_obfuscated)),
+    API_VARIABLE(GALLAGHER_CARDAX_ASCII, const uint8_t*)));

applications/main/nfc/application.fam

@@ -9,7 +9,7 @@ App(
     order=30,
     resources="resources",
     sources=[
-        "*.c",
+        "*.c*",
         "!plugins",
         "!nfc_cli.c",
     ],
@@ -110,6 +110,15 @@ App(
     sources=["plugins/supported_cards/umarsh.c"],
 )
 
+App(
+    appid="gallagher_parser",
+    apptype=FlipperAppType.PLUGIN,
+    entry_point="gallagher_plugin_ep",
+    targets=["f7"],
+    requires=["nfc"],
+    sources=["plugins/supported_cards/gallagher.c"],
+)
+
 App(
     appid="clipper_parser",
     apptype=FlipperAppType.PLUGIN,

applications/main/nfc/helpers/nfc_supported_cards.c

@@ -1,9 +1,11 @@
 #include "nfc_supported_cards.h"
+#include "../api/nfc_app_api_interface.h"
 
 #include "../plugins/supported_cards/nfc_supported_card_plugin.h"
 
 #include <flipper_application/flipper_application.h>
 #include <flipper_application/plugins/plugin_manager.h>
+#include <flipper_application/plugins/composite_resolver.h>
 #include <loader/firmware_api/firmware_api.h>
 
 #include <furi.h>
@@ -45,6 +47,7 @@ typedef struct {
 } NfcSupportedCardsLoadContext;
 
 struct NfcSupportedCards {
+    CompositeApiResolver* api_resolver;
     NfcSupportedCardsPluginCache_t plugins_cache_arr;
     NfcSupportedCardsLoadState load_state;
     NfcSupportedCardsLoadContext* load_context;
@@ -52,6 +55,11 @@ struct NfcSupportedCards {
 
 NfcSupportedCards* nfc_supported_cards_alloc() {
     NfcSupportedCards* instance = malloc(sizeof(NfcSupportedCards));
+
+    instance->api_resolver = composite_api_resolver_alloc();
+    composite_api_resolver_add(instance->api_resolver, firmware_api_interface);
+    composite_api_resolver_add(instance->api_resolver, nfc_application_api_interface);
+
     NfcSupportedCardsPluginCache_init(instance->plugins_cache_arr);
 
     return instance;
@@ -67,8 +75,9 @@ void nfc_supported_cards_free(NfcSupportedCards* instance) {
         NfcSupportedCardsPluginCache* plugin_cache = NfcSupportedCardsPluginCache_ref(iter);
         furi_string_free(plugin_cache->path);
     }
-
     NfcSupportedCardsPluginCache_clear(instance->plugins_cache_arr);
+
+    composite_api_resolver_free(instance->api_resolver);
     free(instance);
 }
 
@@ -100,15 +109,17 @@ static void nfc_supported_cards_load_context_free(NfcSupportedCardsLoadContext*
     free(instance);
 }
 
-static const NfcSupportedCardsPlugin*
+static const NfcSupportedCardsPlugin* nfc_supported_cards_get_plugin(
-    nfc_supported_cards_get_plugin(NfcSupportedCardsLoadContext* instance, FuriString* path) {
+    NfcSupportedCardsLoadContext* instance,
+    const FuriString* path,
+    const ElfApiInterface* api_interface) {
     furi_assert(instance);
     furi_assert(path);
 
     const NfcSupportedCardsPlugin* plugin = NULL;
     do {
         if(instance->app) flipper_application_free(instance->app);
-        instance->app = flipper_application_alloc(instance->storage, firmware_api_interface);
+        instance->app = flipper_application_alloc(instance->storage, api_interface);
         if(flipper_application_preload(instance->app, furi_string_get_cstr(path)) !=
            FlipperApplicationPreloadStatusSuccess)
             break;
@@ -129,8 +140,9 @@ static const NfcSupportedCardsPlugin*
     return plugin;
 }
 
-static const NfcSupportedCardsPlugin*
+static const NfcSupportedCardsPlugin* nfc_supported_cards_get_next_plugin(
-    nfc_supported_cards_get_next_plugin(NfcSupportedCardsLoadContext* instance) {
+    NfcSupportedCardsLoadContext* instance,
+    const ElfApiInterface* api_interface) {
     const NfcSupportedCardsPlugin* plugin = NULL;
 
     do {
@@ -145,7 +157,7 @@ static const NfcSupportedCardsPlugin*
 
         path_concat(NFC_SUPPORTED_CARDS_PLUGINS_PATH, instance->file_name, instance->file_path);
 
-        plugin = nfc_supported_cards_get_plugin(instance, instance->file_path);
+        plugin = nfc_supported_cards_get_plugin(instance, instance->file_path, api_interface);
     } while(plugin == NULL); //-V654
 
     return plugin;
@@ -162,8 +174,10 @@ void nfc_supported_cards_load_cache(NfcSupportedCards* instance) {
         instance->load_context = nfc_supported_cards_load_context_alloc();
 
         while(true) {
+            const ElfApiInterface* api_interface =
+                composite_api_resolver_get(instance->api_resolver);
             const NfcSupportedCardsPlugin* plugin =
-                nfc_supported_cards_get_next_plugin(instance->load_context);
+                nfc_supported_cards_get_next_plugin(instance->load_context, api_interface);
             if(plugin == NULL) break; //-V547
 
             NfcSupportedCardsPluginCache plugin_cache = {}; //-V779
@@ -216,8 +230,10 @@ bool nfc_supported_cards_read(NfcSupportedCards* instance, NfcDevice* device, Nf
             if(plugin_cache->protocol != protocol) continue;
             if((plugin_cache->feature & NfcSupportedCardsPluginFeatureHasRead) == 0) continue;
 
-            const NfcSupportedCardsPlugin* plugin =
+            const ElfApiInterface* api_interface =
-                nfc_supported_cards_get_plugin(instance->load_context, plugin_cache->path);
+                composite_api_resolver_get(instance->api_resolver);
+            const NfcSupportedCardsPlugin* plugin = nfc_supported_cards_get_plugin(
+                instance->load_context, plugin_cache->path, api_interface);
             if(plugin == NULL) continue;
 
             if(plugin->verify) {
@@ -262,8 +278,10 @@ bool nfc_supported_cards_parse(
             if(plugin_cache->protocol != protocol) continue;
             if((plugin_cache->feature & NfcSupportedCardsPluginFeatureHasParse) == 0) continue;
 
-            const NfcSupportedCardsPlugin* plugin =
+            const ElfApiInterface* api_interface =
-                nfc_supported_cards_get_plugin(instance->load_context, plugin_cache->path);
+                composite_api_resolver_get(instance->api_resolver);
+            const NfcSupportedCardsPlugin* plugin = nfc_supported_cards_get_plugin(
+                instance->load_context, plugin_cache->path, api_interface);
             if(plugin == NULL) continue;
 
             if(plugin->parse) {

applications/main/nfc/plugins/supported_cards/gallagher.c

@@ -0,0 +1,87 @@
+/* gallagher.c - NFC supported cards plugin for Gallagher access control cards (New Zealand).
+ * Author: Nick Mooney (nick@mooney.nz)
+ * 
+ * Reference: https://github.com/megabug/gallagher-research
+*/
+
+#include "nfc_supported_card_plugin.h"
+#include "../../api/gallagher/gallagher_util.h"
+
+#include <flipper_application/flipper_application.h>
+#include <nfc/protocols/mf_classic/mf_classic.h>
+#include <nfc/protocols/mf_classic/mf_classic_poller_sync.h>
+#include <nfc/helpers/nfc_util.h>
+
+static bool gallagher_parse(const NfcDevice* device, FuriString* parsed_data) {
+    furi_assert(device);
+    furi_assert(parsed_data);
+
+    const MfClassicData* data = nfc_device_get_data(device, NfcProtocolMfClassic);
+
+    if(!(data->type == MfClassicType1k || data->type == MfClassicType4k)) {
+        return false;
+    }
+
+    // It's possible for a single tag to contain multiple credentials,
+    // but this is currently unimplementecd.
+    const uint8_t credential_sector_start_block_number =
+        mf_classic_get_first_block_num_of_sector(GALLAGHER_CREDENTIAL_SECTOR);
+
+    // Test 1: The first 8 bytes and the second 8 bytes should be bitwise inverses.
+    const uint8_t* credential_block_start_ptr =
+        &data->block[credential_sector_start_block_number].data[0];
+    uint64_t cardholder_credential = nfc_util_bytes2num(credential_block_start_ptr, 8);
+    uint64_t cardholder_credential_inverse = nfc_util_bytes2num(credential_block_start_ptr + 8, 8);
+    // Due to endianness, this is testing the bytes in the wrong order,
+    // but the result still should be correct.
+    if(cardholder_credential != ~cardholder_credential_inverse) {
+        return false;
+    }
+
+    // Test 2: The contents of the second block should be equal to the GALLAGHER_CARDAX_ASCII constant.
+    const uint8_t* cardax_block_start_ptr =
+        &data->block[credential_sector_start_block_number + 1].data[0];
+    if(memcmp(cardax_block_start_ptr, GALLAGHER_CARDAX_ASCII, MF_CLASSIC_BLOCK_SIZE) != 0) {
+        return false;
+    }
+
+    // Deobfuscate the credential data
+    GallagherCredential credential;
+    gallagher_deobfuscate_and_parse_credential(&credential, credential_block_start_ptr);
+
+    char display_region = 'A';
+    // Per https://github.com/megabug/gallagher-research/blob/master/formats/cardholder/cardholder.md,
+    // regions are generally A-P.
+    if(credential.region < 16) {
+        display_region = display_region + (char)credential.region;
+    } else {
+        display_region = '?';
+    }
+
+    furi_string_cat_printf(
+        parsed_data,
+        "\e#Gallagher NZ\nFacility %c%u\nCard %lu (IL %u)",
+        display_region,
+        credential.facility,
+        credential.card,
+        credential.issue);
+    return true;
+}
+
+static const NfcSupportedCardsPlugin gallagher_plugin = {
+    .protocol = NfcProtocolMfClassic,
+    .verify = NULL,
+    .read = NULL,
+    .parse = gallagher_parse,
+};
+
+static const FlipperAppPluginDescriptor gallagher_plugin_descriptor = {
+    .appid = NFC_SUPPORTED_CARD_PLUGIN_APP_ID,
+    .ep_api_version = NFC_SUPPORTED_CARD_PLUGIN_API_VERSION,
+    .entry_point = &gallagher_plugin,
+};
+
+/* Plugin entry point */
+const FlipperAppPluginDescriptor* gallagher_plugin_ep() {
+    return &gallagher_plugin_descriptor;
+}

lib/flipper_application/api_hashtable/api_hashtable.cpp

@@ -21,7 +21,7 @@ bool elf_resolve_from_hashtable(
     auto find_res =
         std::lower_bound(hashtable_interface->table_cbegin, hashtable_interface->table_cend, key);
     if((find_res == hashtable_interface->table_cend || (find_res->hash != hash))) {
-        FURI_LOG_W(
+        FURI_LOG_T(
             TAG, "Can't find symbol with hash %lx @ %p!", hash, hashtable_interface->table_cbegin);
         result = false;
     } else {