desfire_file_system.hpp

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
 *
 * SPDX-License-Identifier: MIT
 */
#ifndef M5_UNIT_UNIFIED_NFC_NFC_ISODEP_DESFIRE_FILE_SYSTEM_HPP
#define M5_UNIT_UNIFIED_NFC_NFC_ISODEP_DESFIRE_FILE_SYSTEM_HPP
#include "file_system.hpp"
#include "nfc/a/mifare.hpp"
#include "nfc/ndef/ndef.hpp"
#include <m5_utility/stl/expected.hpp>
#include <array>
#include <algorithm>
#include <limits>
 
namespace m5 {
namespace nfc {
class NFCLayerA;
namespace a {
namespace mifare {
namespace desfire {
 
constexpr uint8_t DESFIRE_APDU_CLA{0x90};
constexpr uint8_t DESFIRE_LIGHT_INS_READ_DATA{0xAD};
constexpr uint8_t DESFIRE_LIGHT_INS_WRITE_DATA{0x8D};
 
using file_no_t = uint8_t;                
constexpr file_no_t MINIMUM_FILE_NO{0};   
constexpr file_no_t MAXIMUM_FILE_NO{31};  
 
constexpr uint8_t MAXIMUM_FILES{MAXIMUM_FILE_NO - MINIMUM_FILE_NO + 1};  
 
namespace detail {
 
inline uint16_t clamp_u16_size(const size_t size)
{
    constexpr size_t max_u16 = std::numeric_limits<uint16_t>::max();
    return static_cast<uint16_t>(size > max_u16 ? max_u16 : size);
}
 
inline uint16_t default_rx_capacity(const m5::nfc::isodep::IsoDEP& dep)
{
    const uint16_t cfg_rx = dep.config().max_frame_size_rx();
    const uint16_t base   = cfg_rx ? cfg_rx : 256;
    return std::max<uint16_t>(256, base);
}
 
inline void pack_le24(uint8_t out[3], const uint32_t value)
{
    out[0] = static_cast<uint8_t>(value & 0xFF);
    out[1] = static_cast<uint8_t>((value >> 8) & 0xFF);
    out[2] = static_cast<uint8_t>((value >> 16) & 0xFF);
}
 
inline void pack_be24(uint8_t out[3], const uint32_t value)
{
    out[0] = static_cast<uint8_t>((value >> 16) & 0xFF);
    out[1] = static_cast<uint8_t>((value >> 8) & 0xFF);
    out[2] = static_cast<uint8_t>(value & 0xFF);
}
 
inline uint32_t unpack_le24(const uint8_t in[3])
{
    return static_cast<uint32_t>(in[0]) | (static_cast<uint32_t>(in[1]) << 8) | (static_cast<uint32_t>(in[2]) << 16);
}
 
}  // namespace detail
 
struct FileSettings {
    uint8_t file_type{};
    uint8_t comm_mode{};
    uint16_t access_rights{};
    uint32_t file_size{};
};
 
struct desfire_aid_t {
    uint8_t aid[3]{};  // BE
    uint8_t _pad{};
    inline constexpr uint32_t aid24() const noexcept
    {
        // Big-endian
        return ((uint32_t)aid[0] << 16) | ((uint32_t)aid[1] << 8) | aid[2];
    }
    inline constexpr const uint8_t* data() const noexcept
    {
        return aid;
    }
    inline explicit operator uint32_t() const noexcept
    {
        return aid24();
    }
};
inline bool operator==(const desfire_aid_t& a, const desfire_aid_t& b) noexcept
{
    return a.aid[0] == b.aid[0] && a.aid[1] == b.aid[1] && a.aid[2] == b.aid[2];
}
inline bool operator!=(const desfire_aid_t& a, const desfire_aid_t& b) noexcept
{
    return !(a == b);
}
inline bool operator<(const desfire_aid_t& a, const desfire_aid_t& b) noexcept
{
    return a.aid24() < b.aid24();
}
 
enum class AuthMode : uint8_t {
    Auto,  
    DES,   
    AES,   
};
 
struct NdefFormatOptions {
    m5::nfc::ndef::type4::CapabilityContainer cc;  
    uint8_t aid[3]{m5::nfc::a::mifare::desfire::DESFIRE_NDEF_AID[0], m5::nfc::a::mifare::desfire::DESFIRE_NDEF_AID[1],
                   m5::nfc::a::mifare::desfire::DESFIRE_NDEF_AID[2]};         
    uint8_t cc_file_no{m5::nfc::a::mifare::desfire::DESFIRE_CC_FILE_NO};      
    uint8_t ndef_file_no{m5::nfc::a::mifare::desfire::DESFIRE_NDEF_FILE_NO};  
    uint16_t cc_file_size{0x000F};                                            
    uint16_t ndef_file_size{2048};                                            
    uint8_t comm_mode{0x00};                                                  
    uint16_t access_rights{0xEEEE};                                           
    uint8_t key_settings1{0x09};              
    uint8_t key_settings2{0x21};              
    const uint8_t* picc_master_key{nullptr};  
    const uint8_t* app_master_key{nullptr};   
    AuthMode auth_mode{AuthMode::Auto};       
};
 
struct FileRename {
    uint8_t old_file_no{};   
    uint8_t new_file_no{};   
    uint16_t new_file_id{};  
};
 
struct Ev2Context {
    uint8_t ti[4]{};            
    uint16_t cmd_ctr{};         
    uint8_t ses_enc_key[16]{};  
    uint8_t ses_mac_key[16]{};  
};
std::vector<uint8_t> make_native_wrap_command(const uint8_t ins, const uint8_t* data = nullptr,
                                              const uint16_t data_len = 0);
 
inline uint8_t status_code(const uint8_t* rx, const uint16_t rx_len)
{
    return (rx && rx_len >= 2 && rx[rx_len - 2] == 0x91) ? rx[rx_len - 1] : 0xFF;
}
 
inline bool is_successful(const uint8_t* rx, const uint16_t rx_len)
{
    return status_code(rx, rx_len) == 0x00;
}
 
inline bool is_more(const uint8_t* rx, const uint16_t rx_len)
{
    return status_code(rx, rx_len) == 0xAF;
}
 
inline bool is_duplicate(const uint8_t* rx, const uint16_t rx_len)
{
    return status_code(rx, rx_len) == 0xDE;
}
 
class DESFireFileSystem : public FileSystem {
public:
    explicit DESFireFileSystem(m5::nfc::NFCLayerA& layer);
    explicit DESFireFileSystem(m5::nfc::isodep::IsoDEP& isoDEP) : FileSystem{isoDEP}
    {
    }
 
    m5::stl::expected<void, uint8_t> createApplication(const uint8_t aid[3], const uint8_t key_settings1,
                                                       const uint8_t key_settings2, const uint16_t iso_fid = 0,
                                                       const uint8_t* df_name = nullptr, const uint8_t df_name_len = 0);
    inline bool selectApplication(const desfire_aid_t& aid)
    {
        return selectApplication(aid.data());
    }
    bool selectApplication(const uint8_t aid[3]);
    bool selectApplication(const uint32_t aid24 = 0u);
    bool deleteApplication(const uint8_t aid[3]);
 
    bool getApplicationIDs(std::vector<desfire_aid_t>& out);
    // NOTE: getFreeMemory is intended to be used before authentication (no secure messaging).
    bool getFreeMemory(uint32_t& out);
    bool getKeySettings(uint8_t& key_settings, uint8_t& key_count);
    bool getFileIDs(std::vector<uint8_t>& out);
    bool getISOFileIDs(std::vector<uint8_t>& out);
    bool getFileSettings(FileSettings& out, const uint8_t file_no);
    bool getFileSettingsEV2(FileSettings& out, const uint8_t file_no, Ev2Context& ctx);
    bool getFileSettingsEV2Full(FileSettings& out, const uint8_t file_no, Ev2Context& ctx);
 
    bool changeFileSettings(const uint8_t file_no, const uint8_t file_option, const uint16_t access_rights);
    bool changeFileSettingsEV2(const uint8_t file_no, const uint8_t file_option, const uint16_t access_rights,
                               Ev2Context& ctx);
    bool changeFileSettingsEV2Full(const uint8_t file_no, const uint8_t file_option, const uint16_t access_rights,
                                   Ev2Context& ctx);
 
    bool formatPICC(const uint8_t* picc_master_key, const AuthMode mode = AuthMode::Auto);
 
    bool createStdDataFile(const uint8_t file_no, const uint16_t iso_fid, const uint8_t comm_mode,
                           const uint16_t access_rights, const uint32_t file_size);
 
    // DESFire Light: requires AppMasterKey authentication and CommMode.Full.
    bool setConfigurationFileRenaming(const FileRename& first, const FileRename* second = nullptr);
    bool setConfigurationFileRenamingEV2Full(const FileRename& first, const FileRename* second, Ev2Context& ctx);
 
    bool deleteTransactionMACFileEV2Full(const uint8_t file_no, Ev2Context& ctx);
 
    bool createTransactionMACFileEV2Full(const uint8_t file_no, const uint8_t comm_mode, const uint16_t access_rights,
                                         const uint8_t tmac_key[16], const uint8_t tmac_key_ver, Ev2Context& ctx);
    bool setConfigurationAppNameEV2Full(const uint8_t* df_name, uint8_t df_name_len, uint16_t iso_fid, Ev2Context& ctx);
 
    bool readData(std::vector<uint8_t>& out, const uint8_t file_no, const uint32_t offset, const uint32_t length);
    bool readDataLight(std::vector<uint8_t>& out, const uint8_t file_no, const uint32_t offset, const uint32_t length);
    bool readDataLightEV2Full(std::vector<uint8_t>& out, const uint8_t file_no, const uint32_t offset,
                              const uint32_t length, Ev2Context& ctx);
    bool readDataLightEV2(std::vector<uint8_t>& out, const uint8_t file_no, const uint32_t offset,
                          const uint32_t length, Ev2Context& ctx);
    bool writeData(const uint8_t file_no, const uint32_t offset, const uint8_t* data, const uint32_t data_len);
    bool writeDataLight(const uint8_t file_no, const uint32_t offset, const uint8_t* data, const uint32_t data_len);
    bool writeDataLightEV2(const uint8_t file_no, const uint32_t offset, const uint8_t* data, const uint32_t data_len,
                           Ev2Context& ctx);
    bool writeDataLightEV2Full(const uint8_t file_no, const uint32_t offset, const uint8_t* data,
                               const uint32_t data_len, Ev2Context& ctx);
 
    bool authenticateDES(const uint8_t key_no, const uint8_t key[16]);
    bool authenticateISO(const uint8_t key_no, const uint8_t key[16]);
    bool authenticateAES(const uint8_t key_no, const uint8_t key[16]);
    bool authenticateEV2First(const uint8_t key_no, const uint8_t key[16], Ev2Context& ctx);
 
protected:
    bool transceive(uint8_t* rx, uint16_t& rx_len, const uint8_t* tx, const uint16_t tx_len);
};
 
}  // namespace desfire
}  // namespace mifare
}  // namespace a
}  // namespace nfc
}  // namespace m5
#endif