Reference Manual


VHL.Setup

This command creates a VHL file dynamically and transfers it to the reader's RAM. The VHL file specifies the card-specific memory structure required to call VHL.Read or VHL.Write. You need to run VHL.Setup if you don't want to configure the readers with a static VHL file ( learn more).

To run VHL.Format, you cannot use a dynamic VHL file. In this case, you have to follow the standard VHL implementation with a static VHL file.

What to specify

To describe the memory structure, provide a list of parameters depending on the card type (see optional fields in the Parameters table below). If you omit a parameter, the reader will use the default value. To fill in the parameter values, please refer to the card specification. For LEGIC or MIFARE cards, you can also analyze the card structure using BALTECH ID-engine Explorer.

Mixing dynamic and static VHL files

In principle, it is possible to mix dynamic VHL files and static VHL files (as part of the reader configuration for the VHL & Autoread). However, please note that the dynamic VHL file is lost as soon as you run VHL.Read or VHL.Write with a static VHL file. Thus, if you later want to run VHL.Read or VHL.Write with the dynamic VHL file again, you first need to rerun VHL.Setup to recreate the dynamic VHL file.

Properties

Parameters (request frame)

Name Type/Size Description
ConsideredCardType Enumeration (8 bits)

Type of card to consider. The default value is 0x00, i.e. the reader will use the card type detected by VHL.Select. To handle the card as a different type (e.g. handle a DESFire card as an inter-industry ISO 14443-4 card), set this value to the desired card type.

Not all card types support all VHL commands. For details, see our overview of supported commands

The type of the selected card. Since there are no reliable identification standards amongst card manufacturers, we use a heuristic that examines the UID, its length, and other information as documented here.

Due to the lack of standards, we cannot guarantee the card type is always identified correctly.
Values (48):
  • Default (0x00)
    See description above
  • MifareClassic (0x10)
    MIFARE Classic (1k and 4k variants)
  • Iso14443aGeneric (0x11)
    Generic ISO 14443-3 Type A without ISO 7816-4 support
  • Iso14443aInterIndustryLegacy (0x12)
    ISO 14443-4 Type A compliant with ISO7816-4; this is a legacy value that is no longer returned since firmware version 2.20.00.
  • MifareUltraLight (0x13)
    MIFARE Ultralight
  • MifareDesfire (0x14)
    MIFARE DESFire (2k, 4k, and 8k variants)
  • InfineonSle55 (0x15)
    Infineon my-d proximity (SLE55); this is a legacy value that is no longer returned since firmware version 2.20.00.
  • Iso14443aIntIndustry (0x16)
    ISO 14443-4 Type A; this card type is capable of transferring application protocol data units (APDU) as defined in ISO 7816-4
  • MifarePlusL2 (0x17)
    MIFARE Plus L2 (2k and 4k variants)
  • LEGICAdvantIso14443a (0x18)
    LEGIC advant ISO 14443 Type A
  • MifarePlusL3 (0x19)
    MIFARE Plus L3
  • LEGICPrimeLegacy (0x20)
    LEGIC prime; this is a legacy value - it has been replaced by LEGICPrime.
  • LEGICAdvantLegacy (0x21)
    LEGIC advant (ISO 14443 Type A/ISO 15693); this is a legacy value - it has been replaced by LEGICAdvantIso14443a and LEGICAdvantIso15693.
  • Iso15693 (0x30)
    ISO-15693-compliant label
  • LEGICAdvantIso15693 (0x32)
    LEGIC advant ISO 15693
  • Iso14443bUnknown (0x40)
    ISO 14443-3 Type B without ISO 7816-4 support
  • Iso14443bIntIndustry (0x41)
    ISO 14443-4 Type B with ISO 7816-4 support
  • IClassIso14B (0x42)
    iCLASS via standard-compliant ISO 14443 Type B protocol (Level 3 compatible)
  • IClassIso14B2 (0x50)
    iCLASS via proprietary ISO 14443 Type B protocol derivate (Level 2 compatible)
  • IClass (0x60)
    iCLASS via ISO 15693
  • Felica (0x70)
    FeliCa
  • EM4205 (0x80)
    EM 4205/EM 4305
  • EM4100 (0x81)
    EM 4100/EM 4102
  • EM4450 (0x83)
    EM 4450
  • Pyramid (0x84)
    Farpointe Pyramid
  • HidProx32 (0x85)
    HID Prox32
  • Keri (0x86)
    Keri
  • Quadrakey (0x87)
    QuadraKey
  • HidIndala (0x88)
    HID Indala ASP
  • HidAwid (0x89)
    AWID
  • HidProx (0x8A)
    HID Proximity
  • HidIoprox (0x8B)
    ioProx
  • Hitag1S (0x8C)
    HITAG 1 or S
  • Hitag2M (0x8D)
    HITAG 2 Manchester
  • Hitag2B (0x8E)
    HITAG 2 Biphase
  • TTF (0x8F)
    Low-level card type/programmable decoder
  • STSRIX (0x90)
    ST SRIX
  • SecuraKey (0xA0)
    SecuraKey
  • GProx (0xA1)
    G-Prox
  • HidIndalaSecure (0xA2)
    HID Indala ASP+
  • Cotag (0xA3)
    Cotag
  • Idteck (0xA4)
    IDTECK
  • BluetoothMce (0xB0)
    Bluetooth MCE; Mobile Card Emulation over Bluetooth
  • LEGICPrime (0xC0)
    LEGIC prime
  • HidSio (0xE0)
    Abstract card type for reading SIO Elements
  • Fido (0xE4)
    Fido 2.1
  • Piv (0xE5)
    FIPS201 Personal Identity Verification (PIV)
  • DesfireForLegic (0xE6)
    Abstract card type for reading MIFARE DESFire cards using a special VHL implementation for LEGIC readers
RFU Raw data (length 1 Byte) Fixed value 0x00
Optional field, condition: ConsideredCardType == ConsideredCardType.MifareClassic
HasMifareKey Enumeration (8 bits)
Values (2):
  • Disabled (0x00)
  • Enabled (0x06)
Optional field, condition: HasMifareKey == HasMifareKey.Enabled
MifareKey Raw data (length 6 Bytes) Encryption key to access the card.
MifareHasAsKeyA Enumeration (8 bits)
Values (2):
  • Disabled (0x00)
  • Enabled (0x01)
Optional field, condition: MifareHasAsKeyA == MifareHasAsKeyA.Enabled
MifareAsKeyA Boolean (8 bits) If true, Key A is used to access the card.
If false, Key B is used.
MifareHasMadId Enumeration (8 bits)
Values (2):
  • Disabled (0x00)
  • Enabled (0x02)
Optional field, condition: MifareHasMadId == MifareHasMadId.Enabled
MifareMadId Integer (16 bits)

2-byte application ID (AID) that identifies the sectors to access. If specified, only the payload of that application will be accessed. If not specified, the payload of all sectors will be accessed.

All sector trailer blocks and block 0 will be omitted, i.e. the following block order is used: 1,2,4,5,6,8, etc. (0,3,7, etc. are omitted).
Optional field, condition: ConsideredCardType == ConsideredCardType.MifareDesfire
DesfireHasAppId Enumeration (8 bits)
Values (2):
  • Disabled (0x00)
  • Enabled (0x04)
Optional field, condition: DesfireHasAppId == DesfireHasAppId.Enabled
DesfireAppId Integer (32 bits) Application ID, ranging from 0 to 0x00FFFFFF (big-endian)
HasDesfireFileDesc Enumeration (8 bits)
Values (2):
  • Disabled (0x00)
  • Enabled (0x10)
Optional field, condition: HasDesfireFileDesc == HasDesfireFileDesc.Enabled
DesfireFileDesc.FileNo Integer (8 bits) The DESFire file number to access
(Minimum value: 0, maximum value: 31)
DesfireFileDesc.FileCommunicationSecurity Enumeration (8 bits) Communication settings that define if data is to be MAC'ed or encrypted before it's transmitted to the host system.
Values (3):
  • Plain (0x00)
  • Mac (0x01)
  • Encrypted (0x03)
DesfireFileDesc.FileType Enumeration (8 bits) Type of file to read Only Standard and Backup files are supported. There's no support for Cyclic, Record, or Value files.
Values (3):
  • Standard (0x00)
  • Backup (0x01)
    Commit will be performed automatically.
  • BackupManualCommit (0x02)
    Commit will be performed when writing to address 0xFFFF.
DesfireFileDesc.ReadKeyNo Integer (8 bits)

ReadKeyNo, i.e. the index of the read key within the DESFire application key table

The value 14 allows unencrypted access.
(Minimum value: 0, maximum value: 14)
DesfireFileDesc.WriteKeyNo Integer (8 bits)

WriteKeyNo, i.e. the index of the write key within the DESFire application key table

The value 14 allows unencrypted access.
(Minimum value: 0, maximum value: 14)
DesfireFileDesc.Offset Integer (16 bits) Number of the first byte in the DESFire file to map into the VHL file.
(Minimum value: 0, maximum value: 65535)
DesfireFileDesc.Length Integer (16 bits) Length of byte sequence within the DESFire file to map into the VHL file.
(Minimum value: 0, maximum value: 32767)
DesfireFileDesc.ReadKeyIdx Integer (8 bits) Index of the read key on the reader
  1. 0x00-0x7F refer to an index in a SAM (key version has to be 0).
  2. 0x80-0xBF refer to an index in Crypto Key.
  3. 0xC0-0xCB refer to an index in VhlCfg/File/DesfireKeyList.
DesfireFileDesc.WriteKeyIdx Integer (8 bits) Index of the write key on the reader
If omitted and WriteKeyNo is equal to ReadKeyNo, it defaults to ReadKeyIdx. Otherwise it defaults to ReadKeyIdx + 1.
  1. 0x00-0x7F refer to an index in a SAM (key version has to be 0).
  2. 0x80-0xBF refer to an index in Crypto Key.
  3. 0xC0-0xCB refers to an index in VhlCfg/File/DesfireKeyList.
DesfireFileDesc.AccessRightsLowByte Integer (8 bits) Only needed to run VHL.Format.

This byte is composed of a high nibble (ReadWriteKeyNo) and a low nibble (ChangeKeyNo). It corresponds to the low byte of the access rights (see DESFire spec 3.5; chapter 8.3) of the DESFire file. The high byte is composed implicitly of ReadKeyNo and WriteKeyNo.

DesfireFileDesc.ChangeKeyIdx Integer (8 bits) Only needed to run VHL.Format.

Index of the key on the reader that is used to change a key when running VHL.Format. If ChangeKeyNo (see AccessRightsLowByte) is equal to WriteKeyNo, this value defaults to WriteKeyIdx. Otherwise, it defaults to WriteKeyIdx + 1.

  1. 0x00-0x7F refer to an index in a SAM (key version has to be 0).
  2. 0x80-0xBF refer to an index in Crypto Key.
  3. 0xC0-0xCB refer to an index in VhlCfg/File/DesfireKeyList.
DesfireFileDesc.FileSize Integer (16 bits) Only needed to run VHL.Format.

The size of the DESfire file. It's usually Offset + Len.

DesfireFileDesc.IsoFid Integer (16 bits) Only needed to run VHL.Format.

ISO file identifier (ISO FID). If the card already contains a DESFire file with the same ISO FID, the existing file will be replaced. If this value is not specified (or 0x3F00), no ISO FID will be used.

Length of DesfireKey Integer (8 bits) Length of DesfireKey in bytes
DesfireKey Raw data Key with preceding crypto byte. Please refer to Device / CryptoKey SubKey for more details.
Optional field, condition: (ConsideredCardType == ConsideredCardType.LEGICPrimeLegacy) or (ConsideredCardType == ConsideredCardType.LEGICAdvantLegacy) or (ConsideredCardType == ConsideredCardType.LEGICPrime) or (ConsideredCardType == ConsideredCardType.LEGICAdvantIso14443a) or (ConsideredCardType == ConsideredCardType.LEGICAdvantIso15693)
Length of LegicSegmentInfo Integer (8 bits) Length of LegicSegmentInfo in bytes
LegicSegmentInfo Raw data Either segment number or stamp, as defined in the LegicEnStamp parameter. By default, the first segment will be accessed using its segment number.
LegicHasEnStamp Enumeration (8 bits)
Values (2):
  • Disabled (0x00)
  • Enabled (0x01)
Optional field, condition: LegicHasEnStamp == LegicHasEnStamp.Enabled
LegicEnStamp Boolean (8 bits)

If true, LegicSegmentInfo contains a stamp, i.e. the identifier of the application.
If false, it contains a segment number.

This parameter will only be evaluated if LegicSegmentInfo has a length of 1. In this case, the reader can't distinguish between ID and stamp as a valid segment number always has length 1.
LegicHasAdrMode Enumeration (8 bits)
Values (2):
  • Disabled (0x00)
  • Enabled (0x01)
Optional field, condition: LegicHasAdrMode == LegicHasAdrMode.Enabled
LegicAdrMode Enumeration (8 bits)

Specifies the addressing mode. This parameter is only available on readers supporting LEGIC advant. LEGIC prime readers ignore it.

To allow for backward compatibility with LEGIC prime readers, omitting this parameter will not result in the default value, but in the following behavior: VHL address 0 is mapped to protocol header address 25, starting with the first data byte after the longest possible LEGIC prime stamp.
Values (2):
  • ProtocolHeader (0x00)

    To read the segment stamp, use this mode.

    VHL address 0 corresponds to protocol header address 18, starting with the first stamp data byte. The stamp, which has a length between 1 and 12 bytes, is followed by the application data.

  • Advant (0x01)

    To only read the application data of the segment, use this mode.

    VHL address 0 corresponds to address 0 in the user-specific application data area ("DATA area" according to the LEGIC documentation).

    For LEGIC prime cards, this addressing mode is available only with restrictions: Here, the stamp length is undefined - the card doesn't know it. So, when accessing the card using VHL.Setup, the stamp in LegicSegmentInfo with the given length will be applied.

    If the actual stamp is longer, the reader assigns the remaining part of the stamp to the application data area (DATA). If the segment is accessed via segment number, no stamp length information is available at all. In this case, the application data area (DATA) contains the complete stamp (this is equivalent to the ProtocolHeader addressing mode).

    See the following table for examples.
    LegicSegmentInfo LegicEnStamp LegicAdrMode Result of VHL.Read(Id=0xFF, Adr=0, Len=5)
    1 False ProtocolHeader 0x11 22 33 44 01
    0x11 22 33 True ProtocolHeader 0x11 22 33 44 01
    1 False Advant 0x11 22 33 44 01
    0x11 22 33 44 False Advant 0x01 02 03 04 05
    0x11 22 True Advant 0x33 44 01 02 03
Optional field, condition: ConsideredCardType == ConsideredCardType.Iso15693
Iso15HasFirstBlock Enumeration (8 bits)
Values (2):
  • Disabled (0x00)
  • Enabled (0x01)
Optional field, condition: Iso15HasFirstBlock == Iso15HasFirstBlock.Enabled
Iso15FirstBlock Integer (8 bits) First block of the application data Firmware versions 1100 2.07.00 and above also support a 16-bit length value. This is not explicitly documented.
Iso15HasBlockCount Enumeration (8 bits)
Values (2):
  • Disabled (0x00)
  • Enabled (0x01)
Optional field, condition: Iso15HasBlockCount == Iso15HasBlockCount.Enabled
Iso15BlockCount Integer (8 bits) Number of blocks occupied by the application data Firmware versions 1100 2.07.00 and above also support a 16-bit length value. This is not explicitly documented.
Iso15HasOptionFlag Enumeration (8 bits)
Values (2):
  • Disabled (0x00)
  • Enabled (0x01)
Optional field, condition: Iso15HasOptionFlag == Iso15HasOptionFlag.Enabled
Iso15OptionFlag Enumeration (8 bits) Option flag value for read/write operations
Values (3):
  • OptFlagZero (0x00)
  • OptFlagOne (0x01)
  • OptFlagAuto (0x02)
Iso15HasBlockSize Enumeration (8 bits)
Values (2):
  • Disabled (0x00)
  • Enabled (0x01)
Optional field, condition: Iso15HasBlockSize == Iso15HasBlockSize.Enabled
Iso15BlockSize Integer (8 bits) Block size in bytes
Optional field, condition: ConsideredCardType == ConsideredCardType.Iso14443aIntIndustry
Iso14SelectFileCmdListLen Integer (8 bits) Length of SelectFileCmdList (including the following "Length of SelectFileCmdList" field) in bytes
Length of Iso14SelectFileCmdList Integer (8 bits) Number of elements in the Iso14SelectFileCmdList array
Iso14SelectFileCmdList Array -
FileSpecifier Enumeration (8 bits) The method to select the file
Values (3):
  • SelectByName (0x00)
    Select the file by DF name
  • SelectByPath (0x01)

    Select the file by path, i.e. a list of 16-bit file IDs
    If a single file ID is used, a MF, DF, or EF can be specified -> P1 is set to 0
    If a list of file ID is used, the path without the MF has to be specified -> P1 is set to 8

  • SelectByAPDU (0x02)
    Select the file using an APDU command
Optional field, condition: FileSpecifier == FileSpecifier.SelectByName
Length of Name Integer (8 bits) Length of Name in bytes
Name Raw data The name of the DF to be selected (1..16 bytes)
Optional field, condition: FileSpecifier == FileSpecifier.SelectByPath
Length of Path Integer (8 bits) Length of Path in bytes
Path Raw data A list of one or more 16-bit file IDs
Optional field, condition: FileSpecifier == FileSpecifier.SelectByAPDU
Length of ApduCommand Integer (8 bits) Length of ApduCommand in bytes
ApduCommand Raw data APDU command by which to select the file
Iso14HasFileLen Enumeration (8 bits)
Values (2):
  • Disabled (0x00)
  • Enabled (0x04)
Optional field, condition: Iso14HasFileLen == Iso14HasFileLen.Enabled
Iso14FileLen Integer (32 bits) File length in bytes
Iso14HasApduTimeout Enumeration (8 bits)
Values (2):
  • Disabled (0x00)
  • Enabled (0x02)
Optional field, condition: Iso14HasApduTimeout == Iso14HasApduTimeout.Enabled
Iso14ApduTimeout Integer (16 bits)

Timeout for APDU command execution in ms. The default value is 2500 ms.

Keep in mind that this timeout may add up several times in the scope of a single read or write access as file selection usually requires multiple APDUs to be executed.

Returned values (response frame)

None