Skip to content

APDU via VHL

Use case

  • You want to use APDUs to interact with an ISO 14443-4 card.
  • You want to control reader feedback (e.g. LED and beeper) via the host.
  • You want to update the firmware or configuration via the host.
  • You don't need to use the PC/SC protocol.

Implementation overview

What are APDUs?

APDUs (application protocol data units) are the communication units between a reader and an ISO 14443-4 card.

What is VHL?

VHL stands for Very High Level card access. It's a set of simplistic, card-type-independent commands (learn more). With just a few VHL commands, you can connect to the card and exchange APDUs. This saves you a lot of hassle compared to low-level commands.

How it works

This implementation is based on BALTECH Reader Protocol (BRP). To keep your effort low, we provide an SDK for the most common platforms.

  • Poll for and, if needed, identify the card. During this process, VHL handles communication with the card, and returns only the final results to avoid unnecessary round trips.
  • Exchange APDUs as parameters of the VHL.ExchangeAPDU command.
  • Control reader feedback (e.g. LED and beeper) and other hardware functionality directly via the host.
Diagram showing a host application exchanging APDUs with an ISO 14443-4 card via a BALTECH reader using VHL commands

Exceptional cases requiring a configuration

In the vast majority of cases, you won't need to configure the reader. You only need to create a configuration if one or both of the following applies:

  • Your host protocol isn't enabled in the factory settings.

  • You want to control access permissions and set up authenticated and encrypted communication. In this case, you need to configure Authentication and Encryption.

    Details
    • For non-Ethernet readers, use AES.
    • For Ethernet readers, use PKI.

Supported interfaces

  • USB HID (recommended with the SDK)
  • USB virtual COM port (recommended when not using the SDK, required for RDP)
  • RS-232/UART
  • Ethernet (host as client only)

Your workflow

Set up SDK

The easiest way to use VHL is the BALTECH SDK, available for Windows, macOS, and Linux.

My platform's not supported

If you can't use the SDK, you can create the BRP command frames yourself. Please refer to the BRP specification and example frames.

To set up the SDK:

  1. Download the SDK from our website.
  2. Get familiar with its components. We recommend you get started by trying out the app notes.
  3. Integrate the SDK into your application.
  4. Set up a protocol stack to be able to run commands.

Run commands

Card interaction

  1. Run VHL.Select to scan for cards.

    Set AcceptConfCard = false

    Readers without a preinstalled configuration are vulnerable to attacks with tampered ConfigCards. To prevent this, set the parameter AcceptConfCard = false, so readers will ignore any ConfigCard presented to them.

  2. Run the following commands if you need to identify the card:

    • With VHL.GetSnr, you can request the card's UID.

      This won't work if the card returns a random ID.

    • With VHL.GetATR, you can request the card's Answer to Reset (ATR).

  3. Run VHL.ExchangeAPDU (or VHL.ExchangeLongAPDU for large amounts of data) to send your APDU command as a parameter.

No error correction or retry mechanisms on the reader

If an error occurs, the reader returns the error message as part of the response APDU, i.e. you have to take care of error handling in your application.

Reader hardware control

There are various commands to control the reader hardware. You can control reader feedback (e.g. LED and beeper), reboot the reader, check its firmware version, etc.

What's next?

That's it for the development part. You can now install the readers (and, if necessary, deploy the configuration) as described here.

Troubleshooting & support

Got stuck somewhere along the way? Don't worry, we'll help you troubleshoot:

Title