v2.5.0

[Tochemey]

Highlights

This release introduces EMV TLV (Tag-Length-Value) support for chip card data, enabling first-class parsing, building, and integration of BER-TLV encoded data -- commonly carried in ISO 8583 field 55. The implementation follows the EMV v4.3 Specification and ISO/IEC 8825-1 BER encoding rules.

New Features

• TlvParser -- Parses BER-TLV encoded byte arrays into structured TlvTag records. Handles single-byte tags, multi-byte tags (2-3+ bytes), short-form and long-form lengths, constructed (nested) tags, and inter-TLV padding bytes (0x00, 0xFF).

• TlvBuilder -- Fluent API for constructing BER-TLV byte sequences:

  byte[] data = new TlvBuilder()
      .AddTag("9F26", cryptogramValue)
      .AddTag("9F27", cidValue)
      .Build();

• TlvTag -- Immutable record type representing a single TLV data object with Tag (hex string), Length, Value (byte array), and optional Description. Supports IsConstructed detection and GetNestedTags() for constructed data objects.

• EmvTags -- Built-in FrozenDictionary of 38 common EMV tag descriptions sourced from EMV v4.3 Book 3 (Annex A) and ISO/IEC 7816-4, with case-insensitive lookup. Spec version exposed via EmvTags.SpecVersion.

• TlvField -- ICustomBinaryField implementation that allows field 55 (or any field) to be registered as a TLV-aware composite field in both XML and programmatic (MessageFactoryBuilder) configurations.

• IsoMessage TLV extension methods -- Convenience helpers for field 55 access:

  • GetTlvTags() -- retrieve parsed TLV tags
  • SetTlvTags() -- set TLV tags on the message
  • GetTlvBytes() -- retrieve raw TLV bytes
  • FindTlvTag(string tag) -- find a specific tag by hex identifier

Improvements

• Expanded test coverage: Added new test classes with comprehensive unit tests covering single-byte tags, multi-byte tags, nested constructed tags, round-trip encode/decode, TlvField integration, IsoMessage extension methods, and EmvTags dictionary validation.
• MIT license headers Added to all C# source files across the entire solution.
• Documentation: Comprehensive README section covering BER-TLV encoding rules, standalone usage, XML and programmatic configuration, and IsoMessage extension methods, with a full EMV tag reference table.

Bug Fixes

• Fixed date/time related test failures.

Supported Frameworks

• .NET 8.0
• .NET 9.0
• .NET 10.0

Pull Requests

• test: add tests to validate a bug reported sometime ago by @Tochemey in test: add tests to validate a bug reported sometime ago #45
• feat: ✨ add emv v4.3 field 55 parser support by @Tochemey in feat: ✨ add emv v4.3 field 55 parser support #47

Full Changelog: 2.4.0...v2.5.0

---

This discussion was created from the release v2.5.0.