VDS · Linux

Install VDS on Linux

Step-by-step guide to set up, download, configure, and run the Credence ID Verifier Device Service (VDS) SDK on Ubuntu Linux. Includes full C++ API reference.

Ubuntu 20.04 LTS

C++17

Tap2iD Device

VDS v2.2.5

PrerequisitesInstall packages

DownloadGet release

USB Setupudev rules

Build & RunCompile sample

API ReferenceFunction specs

Introduction

Overview

The Linux Verifier Device Service (VDS) is a software development kit from Credence ID that provides C++ application interfaces for developers to communicate with the Tap2iD® Verifier.

Features

Enables applications to easily integrate in-person identity verification into business workflows.

Provides APIs & endpoints to integrate Tap2iD reader with an existing Linux-based client application.

Allows seamless integration of digital ID verification capabilities with any Linux PC.

Supports Tap2iD-initiated or operator-initiated verification flows.

Asynchronous ReadIDInfo — The ReadIDInfo API is now non-blocking. Results are delivered via the ReadIDCallback callback function.

New SetBarcodeData API — Accepts barcode data from Mashgin POS and performs identity verification. Results are available in the same ReadIDCallback.

⚠️

This document applies to VDS SDK running on Ubuntu. Release LNX_RELEASE_2.2.1 was validated on Ubuntu 20.04.3 LTS with kernel version 5.15.0-113-generic. Release v2.2.5 also supports 32-bit ARM chipsets running Kernel 6.12 / Debian 12 (bookworm).

This guide covers:

Configuring a Ubuntu Linux host machine

Downloading the Credence ID Linux VDS release

Building the Sample C++ test application

Description of the Application Programming Interfaces

Setting Up Your Computer

Before you begin, ensure your environment meets the following hardware, software, and access requirements.

Hardware Requirements

Credence ID Tap2iD Device — A physical Tap2iD reader connected via USB. VID: 18d1, PID: 2d00 or 2d01.

Linux Host PC — x86_64 Ubuntu machine with a USB port available.

Operating System

🐧 Ubuntu 20.04 LTS — Validated on Ubuntu 20.04.3 LTS with kernel 5.15.0-113-generic (x86_64).

Access & Network

sudo privileges — Required to install packages and configure udev rules.

Internet connection — Required to download the release package and install apt dependencies.

apt package manager — Standard Debian/Ubuntu package manager must be available and configured.

Install Required Packages

The Credence ID Linux VDS requires the following packages to be installed on your host.

Update package list

Refresh the apt package index before installing dependencies.

Install required packages

Install libusb, udev, JSON parser, build tools, and logging libraries.

bash

$ sudo apt update

$ sudo apt install -y libusb-1.0-0-dev usbutils udev nlohmann-json3-dev     libstdc++6 libc6 build-essential libspdlog-dev libfmt-dev

💡

Validated on Ubuntu 20.04.3 LTS with kernel 5.15.0-113-generic. All commands require an active internet connection and sudo privileges.

Downloading the Linux VDS Release

The official release package can be downloaded directly from the Credence ID Box repository.

Download Linux VDS v2.2.5

bash — Download & Extract

# Download the Official Linux release
$ https://credenceid.box.com/v/LNX-REL225-20250729
# Filename: CID_LNX_VDS_REL-2.2.5.zip

# Extract the zip file
$ unzip CID_LNX_VDS_REL-2.2.5.zip

The release package contains 5 files:

bash — File listing

├── libvds.so
├── Makefile
├── README.md
├── vds.h
└── vdstest.cpp

0 directories, 5 files

bash — Verify MD5 checksum

$ md5sum libvds.so
9d39ba230c78ddc970896a4b619c1f83  libvds.so

Filename	Description
`libvds.so`	The shared object file containing the VDS implementation
`vds.h`	The C++ header file containing the methods and enums of VDS
`vdstest.cpp`	A sample C++ application that demonstrates the API usage of VDS. Uses nlohmann JSON parser to print output
`Makefile`	The g++ command to compile the test application
`README.md`	The steps to build the sample app

Setup USB Rules for Access Permissions

Configure udev rules so that your Linux user can access the Tap2iD device over USB without requiring root privileges.

bash — Create udev rules

$ sudo vi /etc/udev/rules.d/51-usb-device.rules

Add the following two rules to the file:

/etc/udev/rules.d/51-usb-device.rules

SUBSYSTEM=="usb", ATTRS{idVendor}=="18d1", ATTRS{idProduct}=="2d00", GROUP="plugdev", TAG+="uaccess"
SUBSYSTEM=="usb", ATTRS{idVendor}=="18d1", ATTRS{idProduct}=="2d01", GROUP="plugdev", TAG+="uaccess"

🔌

The Tap2iD device uses vendor ID 18d1 with product IDs 2d00 or 2d01. Both rules are required to cover both device states. After saving, reload udev rules with sudo udevadm control --reload-rules && sudo udevadm trigger.

Compiling and Executing the Sample Application

After extracting the release package and setting up USB rules, build and run the sample application to verify everything is working correctly.

bash — Build & Run

$ cd CID_LNX_VDS_REL-LNX_RELEASE_2.2.5/
$ make
$ LD_LIBRARY_PATH=. ./vdstest.out

A successful run shows the interactive menu below:

terminal output

=====================================================
Software Version: LNX_2.2.5
=====================================================

Please select from the below options:
 1. GetReaderInfo
 2. Set Device Mode
 3. Read Identity Info
 4. GetReaderConnectionStatus
 5. SetDeviceProfile
 6. StopReadID
 7. SetBarcodeData (mdoc)
 8. SetBarcodeData (PDF417)
 9. Exit
Enter your choice: _

✅

If the menu appears, VDS is correctly installed and linked. Connect your Tap2iD device via USB and select option 1 (GetReaderInfo) to confirm the device is detected.

Reference

Overview of Functions

The Linux VDS supports the following C++ application interfaces to interact with the Tap2iD. The Tap2iD device supports multiple operating modes and reader profiles.

Application Programming Interfaces

Category	API	Description
Device Management	`GetReaderInfo`	Obtains information from the Tap2iD reader including device make/model, OS version, network status/SSID, reader profile, etc.
	`GetReaderConnectionStatus`	Checks and returns the connection status of the reader to the Linux PC
	`SetDeviceMode`	Sets Tap2iD to various operating modes (e.g., HOST_DRIVEN)
	`SetDeviceProfile`	Sets Tap2iD to various reader profiles (e.g., AGE_CHECK)
Digital Identity Verification	`ReadIDInfo`	Initiates and reads digital ID (mDL) verification shared by the holder and returns ID attributes via callback
	`StopReadID`	Stops or cancels the read ID operation if device engagement has not been initiated
	`SetBarcodeData`	Accepts barcode data from Mashgin POS and sends it to VDS for ID verification processing

Tap2iD Operating Modes

The Tap2iD device supports three operating modes that control how identity data flows between the device and VDS.

Operating Mode	Description
STANDALONE	The scanned data is not transferred over USB to VDS. In this mode, VDS can still be connected to the device. `GetReaderInfo`, `GetConnectionStatus`, `SetReaderMode`, and `SetReaderProfile` can be used to query Tap2iD properties and change the operating mode/profile.
HOST_DRIVEN	Tap2iD is activated when VDS receives a `ReadIDInfo` API request from the client application. Upon activation, Tap2iD can accept NFC, mDL or non-mDL QR scans by the holder. Once the transaction completes, or when the Stop API is called, Tap2iD abandons the scan request and becomes passive.
HOLDER_DRIVEN	Any data read by Tap2iD is sent over USB to VDS. The Tap2iD reader is always ACTIVE and accepts any NFC, mDL or non-mDL QR scans triggered by the holder.

API Specifications

This section describes all public APIs necessary to access Tap2iD device settings, read mDL and physical ID information, and manage device state.

GetReaderInfo Device Management

›

Identifies connected Credence ID Tap2iD devices and returns device status, connectivity, OS/firmware versions, network status, and reader profile.

Supported Operating Modes

STANDALONE HOST_DRIVEN HOLDER_DRIVEN

Input Parameters

NONE.

Success Response (JSON)

json

{
  "deviceMakeAndModel": "cIDReader",
  "osVersion": "cIDReader 11 USR 1.0.0_10",
  "applicationVersion": "1.16.4",
  "usbMode": "HOST_DRIVEN",
  "debugMode": false,
  "readerProfile": "ID Check",
  "networkStatus": true,
  "networkSsidStatus": "WiFi-5G",
  "deviceState": "CONNECTED"
}

Field Reference

Field	Values / Notes
deviceState	`CONNECTED` — device is connected and VDS APIs work `NOT_CONNECTED` — device is unplugged
readerProfile	`ID Check Profile`, `AGE Check Profile`
usbMode	`STANDALONE`, `HOLDER_DRIVEN`, `HOST_DRIVEN`

Error Response

console output

"Device status: NOT_CONNECTED"

The possible VID:PID values for the Tap2iD device are 18d1:2d00 or 18d1:2d01.

GetReaderConnectionStatus Device Management

›

Returns the connectivity status of the Tap2iD device with the Linux PC.

Supported Operating Modes

STANDALONE HOST_DRIVEN HOLDER_DRIVEN

Input Parameters

NONE.

Success Response (JSON)

json

{
  "deviceState": "CONNECTED"
}

Error Response

console output

"Device status: NOT_CONNECTED"

SetDeviceMode Device Management

›

Sets the Tap2iD device to the desired operating mode.

Supported Operating Modes

STANDALONE HOST_DRIVEN HOLDER_DRIVEN

Input Parameters

c++ — eDevMode enum

typedef enum {
    HOST_DRIVEN,
    STANDALONE,
    HOLDER_DRIVEN
} eDevMode;

// Example usage
eDevMode mode = HOST_DRIVEN;
SetReaderProperties(mode);

Error Response (JSON)

json

{
  "errorCode": 513,
  "errorMessage": "Generic Error"
}

SetDeviceProfile Device Management

›

Sets the Tap2iD device to the desired reader profile, controlling which verification fields are collected.

Supported Operating Modes

STANDALONE HOST_DRIVEN HOLDER_DRIVEN

Input Parameters

c++ — eDevProfile enum

typedef enum {
    ID_CHECK,
    AGE_CHECK
} eDevProfile;

// Example usage
eDevProfile profile = AGE_CHECK;
SetReaderProperties(profile);

Error Response (JSON)

json

{
  "errorCode": 513,
  "errorMessage": "Generic Error"
}

ReadIDInfo Digital Identity

›

Initiates and reads mDL data from the digital ID holder. Collects various ID attributes per the active reader profile. Supports mDL (ISO 18013), QR Code, and PDF417 (physical ID) input formats.

Asynchronous API: ReadIDInfo is non-blocking. Results are delivered via the ReadIDCallback callback registered at call time. The vdstest.cpp and vds.h files are updated accordingly.

Supported Operating Modes

HOST_DRIVEN

Input Parameters

c++ — Callback signature (vds.h)

/**
 * @brief Callback function type for receiving identity information.
 * @param json The parsed JSON data containing identity information.
 */
typedef void (*ReadIDCallback)(nlohmann::json json);

/**
 * @brief Reads identity information asynchronously.
 * @param callback The callback function to receive the identity data.
 */
void ReadIDInfo(ReadIDCallback callback);

// Example usage
ReadIDInfo(idCallback);

Success Response — mDL / ISO 18013 (JSON)

json

{
  "docType": "IDENTITY",
  "transactionID": "",
  "deviceID": "",
  "validationErrorCode": 100,
  "validationErrorMessage": "",
  "data": {
    "type": "ISO18013",
    "familyName": "Doe",
    "givenNames": "Stefan",
    "birthDate": "",
    "issueDate": 1678304350,
    "expiryDate": 1678304350,
    "issuingCountry": "",
    "issuingAuthority": "CredenceID",
    "documentNumber": "987654321",
    "portrait": "",
    "drivingPrivileges": [
      {
        "vehicleCategory": "A",
        "issueDate": 1729382400,
        "expiryDate": 1729382400,
        "codes": [{ "code": "", "sign": "", "value": "" }]
      }
    ],
    "sex": "Male",
    "height": 0,
    "weight": 0,
    "eyeColor": "",
    "hairColor": "",
    "birthPlace": "",
    "residentAddress": "",
    "portraitCaptureDate": 1678304350,
    "ageInYears": 0,
    "ageBirthYear": 0,
    "isAgeOver18": true,
    "isAgeOver21": true,
    "issuingJurisdiction": "",
    "nationality": "",
    "residentCity": "",
    "residentState": "",
    "residentPostalCode": "",
    "residentCountry": "",
    "familyNameNationalCharacter": "",
    "givenNameNationalCharacter": "",
    "signatureUsualMark": ""
  }
}

Success Response — QR Code (JSON)

json

{
  "docType": "QR_CODE",
  "transactionID": "",
  "deviceID": "",
  "data": {
    "qrCodeData": ""
  }
}

Success Response — PDF417 Physical ID (JSON)

json

{
  "docType": "IDENTITY",
  "transactionID": "",
  "deviceID": "",
  "validationErrorCode": 100,
  "validationErrorMessage": "",
  "data": {
    "type": "AAMVA_DL_ID",
    "familyName": "DAVID",
    "givenNames": "AVA NONE",
    "birthDate": "1992-01-10",
    "issueDate": 1678233600,
    "expiryDate": 1799539200,
    "issuingCountry": "USA",
    "issuingAuthority": "",
    "documentNumber": "G4841292",
    "portrait": "",
    "drivingPrivileges": [
      {
        "vehicleCategory": "A",
        "issueDate": 1729382400,
        "expiryDate": 1729382400,
        "codes": [{ "code": "", "sign": "", "value": "" }]
      }
    ],
    "sex": "FEMALE",
    "height": 0,
    "weight": 0,
    "eyeColor": "",
    "hairColor": "",
    "birthPlace": "",
    "residentAddress": "123 N CAPITOL AVE",
    "portraitCaptureDate": "",
    "ageInYears": 0,
    "ageBirthYear": 0,
    "isAgeOver18": false,
    "isAgeOver21": true,
    "residentCity": "SAN JOSE",
    "residentState": "",
    "residentPostalCode": "95133",
    "residentCountry": "",
    "familyNameNationalCharacter": "",
    "givenNameNationalCharacter": "",
    "signatureUsualMark": ""
  }
}

Error Response (JSON)

json

{
  "errorCode": 513,
  "errorMessage": "Generic Error"
}

StopReadID Digital Identity

›

Cancels the READ ID operation initiated earlier. Tap2iD may or may not be able to stop the read depending on whether mDL has already been scanned.

Supported Operating Modes

HOST_DRIVEN

Input Parameters

NONE.

Success Response (JSON)

json

{
  "ID READ stop request has been successfully submitted"
}

Error Response (JSON)

json

{
  "STOP cannot be invoked"
}

SetBarcodeData Digital Identity

›

Accepts barcode data from Mashgin POS and sends it to Linux VDS for identity verification processing. Must be called after ReadIDInfo. Results are delivered via the same ReadIDCallback registered during ReadIDInfo.

Supported Operating Modes

HOST_DRIVEN

Input Parameters

c++ — vds.h signature

/**
 * @brief Sends QR code or barcode data to the reader.
 * @param qrcodeData The QR code or barcode data to send.
 */
void SetBarcodeData(const std::string& qrcodeData);

vdstest.cpp — Async Callback Setup

c++

#include <iostream>
#include <string>
#include "vds.h"

// Callback function to receive identity information
void idCallback(nlohmann::json json) {
    std::cout << "Callback received: JSON = ";
    if (json != nullptr) {
        std::cout << json.dump(4);
    } else {
        std::cout << "null";
    }
    std::cout << std::endl;
}

int main() {
    Init();

    // Step 1: Initiate async read with callback
    ReadIDInfo(idCallback);
    std::cout << "ReadIDInfo initiated, results in callback";

    // Step 2: Send barcode data (after ReadIDInfo)
    std::string qrcodeData;
    std::getline(std::cin, qrcodeData);
    SetBarcodeData(qrcodeData);

    DeInit();
    return 0;
}

Success Response (JSON)

json

{
  "ID READ stop request has been successfully submitted"
}

Error Response (JSON)

json

{
  "STOP cannot be invoked"
}