nfca.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_A_NFCA_HPP
#define M5_UNIT_UNIFIED_NFC_NFC_A_NFCA_HPP
 
#include "nfc/nfc.hpp"
#include "mifare.hpp"
#include <cstdint>
#include <string>
#include <cstring>
 
namespace m5 {
namespace nfc {
namespace a {
 
enum class Type : uint8_t {
    Unknown,  
 
    MIFARE_Classic_Mini,  
    MIFARE_Classic_1K,    
    MIFARE_Classic_2K,    
    MIFARE_Classic_4K,    
 
    MIFARE_Ultralight,        
    MIFARE_Ultralight_EV1_1,  
    MIFARE_Ultralight_EV1_2,  
    MIFARE_Ultralight_Nano,   
    MIFARE_UltralightC,       
 
    NTAG_203,   
    NTAG_210u,  
    NTAG_210,   
    NTAG_212,   
    NTAG_213,   
    NTAG_215,   
    NTAG_216,   
 
    ST25TA_512B,  
    ST25TA_2K,    
    ST25TA_16K,   
    ST25TA_64K,   
 
    ISO_14443_4,  
 
    MIFARE_Plus_2K,  
    MIFARE_Plus_4K,  
    MIFARE_Plus_SE,  
 
    MIFARE_DESFire_2K,     
    MIFARE_DESFire_4K,     
    MIFARE_DESFire_8K,     
    MIFARE_DESFire_Light,  
 
    NTAG_4XX,  
 
    ISO_18092,  
 
    //    NotCompleted = 0xFF,  //!< SAK indicates UID is not complete
};
 
enum class SubTypePlus : uint8_t {
    None,
    EV1,
    EV2,
    S,
    X,
    X_OR_EV,
};
 
enum SubTypeDESFire : uint8_t {
    None,
    EV1,
    EV2,
    EV3,
};
 
m5::nfc::NFCForumTag get_nfc_forum_tag_type(const Type t);
 
inline bool is_mifare_classic(const Type t)
{
    return t >= Type::MIFARE_Classic_Mini && t <= Type::MIFARE_Classic_4K;
}
 
inline bool is_mifare_ultralight(const Type t)
{
    return t >= Type::MIFARE_Ultralight && t <= Type::MIFARE_UltralightC;
}
 
inline bool is_ntag2(const Type t)
{
    return t >= Type::NTAG_203 && t <= Type::NTAG_216;
}
 
inline bool is_ntag4(const Type t)
{
    return t == Type::NTAG_4XX;
}
 
inline bool is_mifare_plus(const Type t)
{
    return t >= Type::MIFARE_Plus_2K && t <= Type::MIFARE_Plus_SE;
}
 
inline bool is_mifare_classic_compatible(const Type t, const uint8_t sl)
{
    return is_mifare_plus(t) && (sl == 1);
}
 
inline bool is_mifare_desfire(const Type t)
{
    return t >= Type::MIFARE_DESFire_2K && t <= Type::MIFARE_DESFire_Light;
}
 
inline bool is_mifare(const Type t)
{
    return is_mifare_classic(t) || is_mifare_ultralight(t) || is_mifare_plus(t) || is_mifare_desfire(t);
}
 
inline bool is_st25ta(const Type t)
{
    return t >= Type::ST25TA_2K && t <= Type::ST25TA_64K;
}
 
inline bool is_iso14443_4(const Type t)
{
    return is_mifare_plus(t) || is_mifare_desfire(t) || is_st25ta(t) || (t == Type::ISO_14443_4);
}
 
inline bool is_iso14443_3(const Type t)
{
    return !is_iso14443_4(t);
}
 
inline bool supports_NFC(const Type t)
{
    return (t >= Type::MIFARE_Ultralight && t <= Type::MIFARE_UltralightC) || is_ntag2(t);
}
 
inline bool has_fast_read(const Type t)
{
    return t >= Type::NTAG_210 && t <= Type::NTAG_216;
}
 
inline bool has_sak_dependent_bit(const uint8_t sak)
{
    return (sak & 0x04);
}
 
inline bool is_sak_completed_14443_4(const uint8_t sak)
{
    return ((sak & 0x24) == 0x20);
}
inline bool is_sak_completed(const uint8_t sak)
{
    return ((sak & 0x24) == 0x00);
}
 
Type sak_to_type(const uint8_t sak);
Type version3_to_type(const uint8_t info[8]);
Type version4_to_type(uint8_t& sub, const uint8_t info[8]);
Type historical_bytes_to_type(uint8_t& sub, const uint16_t atqa, const uint8_t sak, const uint8_t* bytes,
                              const uint8_t len);
 
uint16_t get_number_of_blocks(const Type t);
uint16_t get_number_of_user_blocks(const Type t);
uint16_t get_user_area_size(const Type t);
uint16_t get_unit_size(const Type t);
uint16_t get_number_of_sectors(const Type t);
uint16_t get_first_user_block(const Type t);
uint16_t get_last_user_block(const Type t);
bool is_user_block(const Type t, const uint16_t block);
 
file_system_feature_t get_file_system_feature(const Type t);
inline bool is_file_system_memory(const Type t)
{
    return (get_file_system_feature(t) & FILE_SYSTEM_FLAT_MEMORY);
}
inline bool is_file_system_file(const Type t)
{
    return get_file_system_feature(t) & (FILE_SYSTEM_ISO7816_4 | FILE_SYSTEM_DESFIRE);
}
 
uint8_t calculate_bcc8(const uint8_t* data, const uint32_t len);
 
const uint8_t* get_version3_response(const Type t);
 
struct ATS {
    union {
        uint8_t header[5]{};
        struct {
            uint8_t TL;  
            uint8_t T0;  
            uint8_t TA;  
            uint8_t TB;  
            uint8_t TC;  
        };
    };
    std::array<uint8_t, 32> historical{};  
    uint8_t historical_len{};              
 
    inline bool validTA() const
    {
        return T0 & 0x10;
    }
    inline bool validTB() const
    {
        return T0 & 0x20;
    }
    inline bool validTC() const
    {
        return T0 & 0x40;
    }
    inline uint8_t fsci() const
    {
        return T0 & 0x0F;
    }
    inline Bitrate maximumBitrateDR() const
    {
        return validTA() ? static_cast<Bitrate>(TA & 0x07) : Bitrate::Invalid;
    }
    inline Bitrate maximumBitrateDS() const
    {
        return validTA() ? static_cast<Bitrate>((TA >> 4) & 0x07) : Bitrate::Invalid;
    }
    inline bool supportsAsymmetricSpeed() const
    {
        return validTA() && (TA & 0x80);
    }
    inline uint8_t fwi() const
    {
        return validTB() ? (TB >> 4) : 0x00;
    }
    inline uint8_t sfgi() const
    {
        return validTB() ? (TB & 0x0F) : 0x00;
    }
    inline uint32_t sfgt_fc() const
    {
        const uint8_t v = sfgi();
        return (v == 0 || v == 15) ? 0u : (256u * 16u * (1u << v));
    }
    inline uint32_t sfgt_ms(const float fc) const
    {
        const uint32_t sfgt = sfgt_fc();
        if (!sfgt || fc <= 0.0f) {
            return 0;
        }
        const float us = (static_cast<float>(sfgt) / fc) * 1e6f;
        uint32_t ms    = static_cast<uint32_t>(us / 1000.f);
        return ms ? ms : 1;
    }
    inline bool supportsNAD() const
    {
        return validTC() && (TC & 0x01);
    }
    inline bool supportsCID() const
    {
        return validTC() && (TC & 0x02);
    }
};
 
struct PICC {
    uint8_t _pad{};
    Type type{};        
    uint8_t sak{};      
    uint8_t size{};     
    uint8_t uid[10]{};  
    uint16_t atqa{};    
    uint16_t blocks{};  
    ATS ats{};          
    union {
        uint8_t sub_type{};               
        SubTypePlus sub_type_plus;        
        SubTypeDESFire sub_type_desfire;  
    };
    union {
        uint8_t security_level{};  
    };
 
    inline bool valid() const
    {
        return (size == 4 || size == 7 || size == 10) && (type != Type::Unknown) &&
               (is_file_system_file(type) || blocks);
    }
    void tail4(uint8_t buf[4]) const
    {
        if (buf) {
            memcpy(buf, uid + size - 4, 4);
        }
    }
    std::string uidAsString() const;   
    std::string typeAsString() const;  
 
    bool emulate(const Type t, const uint8_t* uid, const uint8_t uid_len);
 
    inline bool isMifare() const
    {
        return is_mifare(type);
    }
    inline bool isMifareClassic() const
    {
        return is_mifare_classic(type) || isMifareClassicCompatible();
    }
    inline bool isMifareUltralight() const
    {
        return is_mifare_ultralight(type);
    }
    inline bool isMifarePlus() const
    {
        return is_mifare_plus(type);
    }
    inline bool isMifarePlusX() const
    {
        return is_mifare_plus(type) && sub_type_plus == SubTypePlus::X;
    }
    inline bool isMifarePlusS() const
    {
        return is_mifare_plus(type) && sub_type_plus == SubTypePlus::S;
    }
    inline bool isMifarePlusSE() const
    {
        return type == Type::MIFARE_Plus_SE;
    }
    inline bool requiresPlusSL3PlainRead() const
    {
        return isMifarePlusS() || isMifarePlusSE();
    }
    inline bool isMifareClassicCompatible() const
    {
        return is_mifare_classic_compatible(type, security_level);
    }
    inline bool isMifareDESFire() const
    {
        return is_mifare_desfire(type);
    }
    inline bool isNTAG2() const
    {
        return is_ntag2(type);
    }
    inline bool isISO14443_4() const
    {
        return is_iso14443_4(type);
    }
    inline bool isST25TA() const
    {
        return is_st25ta(type);
    }
 
    inline uint16_t totalSize() const
    {
        return valid()
                   ? (get_unit_size(type) ? get_number_of_blocks(type) * get_unit_size(type) : get_user_area_size(type))
                   : 0;
    }
    inline uint16_t userAreaSize() const
    {
        return valid() ? get_user_area_size(type) : 0;
    }
    inline uint16_t unitSize() const
    {
        return valid() ? get_unit_size(type) : 0;
    }
 
    inline uint16_t firstUserBlock() const
    {
        return valid() ? get_first_user_block(type) : 0xFFFF;
    }
    inline uint16_t lastUserBlock() const
    {
        return valid() ? get_last_user_block(type) : 0xFFFF;
    }
    inline bool isUserBlock(const uint8_t block) const
    {
        return valid() ? is_user_block(type, block) : false;
    }
 
    inline bool supportsNFC() const
    {
        return valid() && supports_NFC(type);
    }
    inline bool supportsNDEF() const
    {
        return valid() && nfcForumTagType() != NFCForumTag::None;
    }
    inline NFCForumTag nfcForumTagType() const
    {
        return get_nfc_forum_tag_type(type);
    }
    inline bool canFastRead() const
    {
        return valid() && has_fast_read(type);
    }
    inline file_system_feature_t fileSystemFeature() const
    {
        return valid() ? get_file_system_feature(type) : 0;
    }
    inline bool isFileSystemMemory() const
    {
        return valid() && is_file_system_memory(type);
    }
    inline bool isFileSystemFile() const
    {
        return valid() && is_file_system_file(type);
    }
};
 
inline bool operator==(const PICC& a, const PICC& b)
{
    return (a.size == b.size) && (a.sak == b.sak) && (a.type == b.type) && (a.blocks == b.blocks) &&
           std::memcmp(a.uid, b.uid, 10) == 0;
}
inline bool operator!=(const PICC& a, const PICC& b)
{
    return !(a == b);
}
 
enum class Command : uint8_t {
    // ISO/IEC 14443-3
    REQA          = 0x26,  
    WUPA          = 0x52,  
    HLTA          = 0x50,  
    SELECT_CL1    = 0x93,  
    SELECT_CL2    = 0x95,  
    SELECT_CL3    = 0x97,  
    SELCT_CL1_OPT = 0x92,  
    SELCT_CL2_OPT = 0x94,  
    SELCT_CL3_OPT = 0x96,  
    READ          = 0x30,  
    // ISO/IEC 14443-4
    RATS     = 0xE0,  
    DESELECT = 0xC2,  
    // MIFARE
    AUTH_WITH_KEY_A = 0x60,  
    AUTH_WITH_KEY_B = 0x61,  
    AUTHENTICATE_1  = 0x1A,  
    AUTHENTICATE_2  = 0xAF,  
    WRITE_BLOCK     = 0xA0,  
    DECREMENT       = 0xC0,  
    INCREMENT       = 0xC1,  
    RESTORE         = 0xC2,  
    TRANSFER        = 0xB0,  
    PERSONALIZE_UID_USAGE = 0x40,  
    SET_MOD_TYPE          = 0x43,  
    WRITE_PERSO           = 0xA8,  
    COMMIT_PERSO          = 0xAA,  
    // MIFARE,NTAG
    WRITE_PAGE = 0xA2,  
    // NTAG
    GET_VERSION = 0x60,  
    FAST_READ   = 0x3A,  
    READ_CNT    = 0x39,  
    PWD_AUTH    = 0x1B,  
    READ_SIG    = 0x3C,  
    WRITE_SIG   = 0xA9,  
    LOCK_SIG    = 0xAC,  
};
 
constexpr uint32_t TIMEOUT_REQ_WUP{4};   // 4
constexpr uint32_t TIMEOUT_SELECT{8};    // 4
constexpr uint32_t TIMEOUT_ANTICOLL{8};  // 8
constexpr uint32_t TIMEOUT_HALT{2};
constexpr uint32_t TIMEOUT_GET_VERSION{5};  // 5
constexpr uint32_t TIMEOUT_3DES{10};
constexpr uint32_t TIMEOUT_AUTH1{4};   // 2
constexpr uint32_t TIMEOUT_AUTH2{16};  // 10
constexpr uint32_t TIMEOUT_READ{12};
constexpr uint32_t TIMEOUT_FAST_READ{2};
constexpr uint32_t TIMEOUT_FAST_READ_4PAGE{4};    // 3.7
constexpr uint32_t TIMEOUT_FAST_READ_12PAGE{4};   // 3.7
constexpr uint32_t TIMEOUT_FAST_READ_32PAGE{12};  // 11.8
constexpr uint32_t TIMEOUT_WRITE1{5};
constexpr uint32_t TIMEOUT_WRITE2{10};
constexpr uint32_t TIMEOUT_VALUE_BLOCK{5};  // Value block operation
constexpr uint32_t TIMEOUT_RATS{5};
constexpr uint32_t TIMEOUT_DESELECT{8};
 
constexpr uint8_t ACK_NIBBLE{0x0A};
 
namespace st25ta {
constexpr uint16_t SYSTEM_FILE_ID{0xE101};  
 
constexpr uint8_t IC_REFERENCE_ST25TA512B{0xE5};
constexpr uint8_t IC_REFERENCE_ST25TA02KB{0xE2};
constexpr uint8_t IC_REFERENCE_ST25TA02KB_D{0xF2};
constexpr uint8_t IC_REFERENCE_ST25TA02KB_P{0xA2};
constexpr uint8_t PRODUCT_CODE_ST25TA16K{0xC5};
constexpr uint8_t PRODUCT_CODE_ST25TA64K{0xC4};
 
inline Type get_type(const uint8_t ic_ref_or_product_code)
{
    return (ic_ref_or_product_code == IC_REFERENCE_ST25TA512B)
               ? Type::ST25TA_512B
               : ((ic_ref_or_product_code == IC_REFERENCE_ST25TA02KB ||
                   ic_ref_or_product_code == IC_REFERENCE_ST25TA02KB_D ||
                   ic_ref_or_product_code == IC_REFERENCE_ST25TA02KB_P)
                      ? Type::ST25TA_2K
                      : ((ic_ref_or_product_code == PRODUCT_CODE_ST25TA16K)   ? Type::ST25TA_16K
                         : (ic_ref_or_product_code == PRODUCT_CODE_ST25TA64K) ? Type::ST25TA_64K
                                                                              : Type::Unknown));
}
 
struct SystemFile {
#if 0
    struct ST25TA02K {
        uint16_t sflen;                
        uint8_t gpo_config;            
        uint8_t event_counter_config;  
        uint8_t counter[3];            
        uint8_t product_version;       
        uint8_t uid[7];                
        uint16_t memory_size;          
        uint8_t ic_reference_code;     
    } __attribute__((packed));
 
    struct ST25TA16K {
        uint16_t sflen;        
        uint8_t reserved[6];   
        uint8_t uid[7];        
        uint16_t memory_size;  
        uint8_t product_code;  
    } __attribute__((packed_));
 
    struct ST25TA64K {
        uint16_t sflen;        
        uint8_t reserved[6];   
        uint8_t uid[7];        
        uint16_t memory_size;  
        uint8_t product_code;  
    } __attribute__((packed));
 
    union{
        block[18]{};
        ST25TA02K st25ta02k;
        ST25TA16K st25ta02k;
        ST25TA64K st25ta02k;
    };
#else
    uint8_t block[18]{};
#endif
    inline Type type() const
    {
        return get_type(block[17]);
    }
} __attribute__((packed));
 
}  // namespace st25ta
 
}  // namespace a
}  // namespace nfc
}  // namespace m5
 
#endif