vdstools

0.18.0indexed

Facilitates decoding, verifying, encoding, and signing of Visible Digital Seals and ICAO IDB barcodes, offering comprehensive support for digital seal handling and barcode generation.

JVMNative·tsenger/vdstools

Stars

—

Used by

dependents

—

Health

/ 100

VdsTools - Kotlin multiplatform library to work with Visible Digital Seals

vdstools Logo

Maven Central Version GitHub Actions Workflow Status

This a Kotlin multiplatform (JVM and iOS) library to decode/verify and encode/sign Visible Digital Seals (VDS) as specified in

It also fully supports encoding and decoding Seals defined in the new draft of ICAO Datastructure for Barcode. VDS and ICD barcodes can be parsed by a generic interface. An example is given in the following chapter.

VDS can be created with the help of this library or, if you want to try it out quickly, via the web Sealgen tool. There is also the Sealva mobile app which scans, verifies and displays all VDS profiles defined in the above specifications.

Parse and verify a VDS / IDB

Here is a quick overview how to use the generic parser and verifier. The generic interface handles VDS and IDB barcodes via common function calls. When you received the raw string from your favorite datamatrix decoder use VdsTools like this:

Configuring accepted seal types

SealParser can be configured to only accept specific seal types — analogous to configuring a barcode scanner to recognise only certain symbologies. If an input matches a type that is not in allowedTypes, a SealParseException is thrown.

// Accept only VDS, reject IDB
val parser = SealParser(allowedTypes = setOf(SealType.VDS))
val seal = parser.parse(rawString)  // throws SealParseException for an IDB input

For VDS seals provided as raw bytes (e.g. when working with test fixtures or binary data):

val parser = SealParser()
val seal: Seal = parser.parse(rawBytes)  // ByteArray input, VDS only

Dispatching on seal type

Every Seal exposes a sealType: SealType property. Combined with Kotlin's exhaustive when, this gives compile-time safety when adding a new seal type:

when (seal.sealType) {
    SealType.VDS -> println("VDS seal, issuing country: ${seal.issuingCountry}")
    SealType.IDB -> println("IDB seal, document type: ${seal.documentType}")
    // compiler warns here if a new SealType value is added and not handled
}

Metadata messages (administrative documents)

Some seal types use a two-stage lookup: the header's documentRef points to a base type (e.g. ADMINISTRATIVE_DOCUMENTS), and the first tags of the message zone carry administrative metadata (e.g. the document profile UUID at tag 0, validity dates at tag 1) rather than user-visible content.

These tags are declared as metadataTagList in VdsDocumentTypes.json and are automatically separated from the regular messageList during parsing. They are only accessible via metadataMessageList.

val seal: Seal = SealParser().parse(rawString)

// Regular user-visible messages (metadata tags are excluded)
 messageList = seal.messageList


 metadataList = seal.metadataMessageList
 (message  metadataList) {
    println()
}


 (seal.metadataMessageList.isNotEmpty()) {
    
     validity = seal.metadataMessageList.firstOrNull { it.name ==  }
     v = validity?.value ? MessageValue.ValidityDatesValue
    println()
}

To check at the type level which tags are configured as metadata (without a concrete seal instance):

DataEncoder.vdsDocumentTypes.getMetadataTags("ADMINISTRATIVE_DOCUMENTS") // → {0, 1, 2, 3}
DataEncoder.vdsDocumentTypes.getMetadataTags("RESIDENT_PERMIT")          // → {} (no metadata tags)

Regular document types have no metadataTagList configured, so their metadataMessageList is always empty and all tags appear in messageList as usual.

Build a barcode

The library follows a symmetric design:

Parsing uses a single entry point — SealParser accepts any raw barcode string (or bytes) and returns a Seal, regardless of whether it is VDS or IDB. You never need to know the internal structure.
Building mirrors this with one builder per seal type — VdsSeal.Builder and IdbSeal.Builder. Call at the end and get back the finished seal. All internal components (header, message group, signature, payload) are handled automatically.

Both builders follow the same Kotlin fluent style: chain configuration calls, then call build().

VDS

VDS seals are always signed. The only way to create one is via VdsSeal.Builder.build(signer):

IDB

IDB seals can be unsigned (e.g. for test fixtures) or signed. Use build() for unsigned and build(signer) for signed. The signature algorithm is derived automatically from the signer's key size.

Also have a look at the testcases for more usage inspiration. You will also find an example on how to generate a datamatrix image with the Zxing library in the jvmTests.

Custom seal codings

VdsTools uses a JSON-based configuration to define seal document types and their message encodings which follows the encoding based on BSI TR-03137. VDS data according to BSI TR-03171 are also supported and can be parsed from document profiles. However, the official profile definitions and certificates are not yet publicly available. You can load your own custom codings at runtime to support additional document types beyond the standard ones.

Loading Custom Codings

There are two strategies for providing custom definitions:

replaceCustom* – replaces the entire registry with your JSON. The built-in defaults are no longer available.
addCustom* – merges your entries into the existing registry. Built-in defaults are preserved; entries with the same key (e.g. documentRef) are overwritten by your version.

val customJson = """[
  {
    "documentType": "MY_CUSTOM_DOCUMENT",
    "documentRef": "ab01",
    "version": 1,
    "messages": [
      {
        "name": "OWNER_NAME",
        "tag": 1,
        "coding": "C40",
        "required": true,
        "minLength": 1,
        "maxLength": 20
      },
      {
        "name": "ISSUE_DATE",
        "tag": 2,
        "coding": "DATE",
        "required": true,
        "minLength": 3,
        "maxLength": 3
      }
    ]
  }
]"""

// Add to defaults – built-in types remain available:
DataEncoder.addCustomVdsDocumentTypes(customJson)
DataEncoder.addCustomVdsDocumentTypesFromFile("path/to/MyDocumentTypes.json")  // JVM only

// Replace defaults entirely – only your types are available:
DataEncoder.replaceCustomVdsDocumentTypes(customJson)
DataEncoder.replaceCustomVdsDocumentTypesFromFile("path/to/MyDocumentTypes.json")

The same pattern applies to the other registries:

// IDB message types
DataEncoder.addCustomIdbMessageTypes(jsonString)
DataEncoder.replaceCustomIdbMessageTypes(jsonString)

// IDB document types
DataEncoder.addCustomIdbDocumentTypes(jsonString)
DataEncoder.replaceCustomIdbDocumentTypes(jsonString)

// VDS profile definitions (VDS administrative documents)
DataEncoder.addCustomVdsProfileDefinitions(jsonString)
DataEncoder.replaceCustomVdsProfileDefinitions(jsonString)

// Revert all registries to embedded defaults:
DataEncoder.resetToDefaults()

Using Custom Document Types

Once loaded, custom document types work seamlessly with the existing API:

val vdsSeal = VdsSeal.Builder("MY_CUSTOM_DOCUMENT")
    .issuingCountry("D<<")
    .signerIdentifier("TEST")
    .certificateReference("32")
    .addMessage("OWNER_NAME", "MAX MUSTERMANN")
    .addMessage("ISSUE_DATE", "2024-06-15")
    .build(signer)

Available Coding Types

See src/commonMain/resources/VdsDocumentTypes.json for the complete structure of the default document types.

Byte-level structure inspection with the `dissect` package

The dissect package is not part of the core VDS/IDB processing workflow. It is a utility for developers who need to inspect the raw byte layout of a parsed seal — for example to build a hex viewer, a debugging tool, or an educational visualisation of the barcode content.

The entry point is an extension function on Seal:

import de.tsenger.vdstools.dissect.dissect

val seal: Seal = SealParser().parse(rawString)
val dissection: SealDissection = seal.dissect()

The result is a SealDissection with four fields:

Each FieldDissection contains a ByteRange(offset, length) relative to the decoded payload bytes, and optionally a list of children for nested sub-fields.

Example: highlighting fields in a hex viewer

Note for IDB seals: all offsets are relative to the decoded payload bytes returned by seal.encoded — the library concatenates header, message group, optional signer certificate, and signature for you.

How to include

The vdstools library is available on the Maven Central Repository to be easy to integrate in your projects.

Gradle

To include this library to your Gradle build add this dependency:

dependencies {
    implementation 'de.tsenger:vdstools:0.18.0'
}

Maven

To include this library to your Maven build add this dependency:


<dependency>
    <groupId>de.tsenger</groupId>
    <artifactId>vdstools</artifactId>
    <version>0.18.0</version>
</dependency>

Related libraries

Surfaced from shared tags and platforms — no rankings paid for.

kson★ 171

kson-orgCombines JSON and YAML features for a robust, readable, and toolable data format. Offers flexible syntax, native JSON Schema support, and code embed functionality. Supports multiple platforms and IDE environments.Shared: serialization, parsing, fileformat

snakeyaml-engine-kmp★ 42

krzema12Processes YAML 1.2 with fine-grained control and advanced functionality. Suitable for projects needing customization and flexibility. Integrates with various platforms and uses comprehensive YAML test suites for validation.Shared: serialization, parsing, fileformat

accompanist-lyrics-core★ 39

6xingyvOffers smart auto-detection and parsing for various lyrics formats, karaoke-ready syllable timing, translation support, and extensibility for custom formats. Includes metadata extraction.Shared: serialization, parsing, fileformat

`C40`	Compressed text encoding (uppercase, digits, special chars)
`MRZ`	Machine Readable Zone (special C40 variant)
`UTF8_STRING`	Direct UTF-8 text
`BYTE`	Single byte value
`BYTES`	Variable-length byte array (images, binary data)
`DATE`	3-byte date (ICAO format, e.g. "2024-06-15")
`MASKED_DATE`	4-byte date with uncertainty masks

`header`	Byte range of the header, including all sub-fields
`messageGroup`	Byte range of the message group, including individual TLV fields
`signerCertificate`	Byte range of the signer certificate (IDB only, otherwise `null`)
`signature`	Byte range of the signature (`null` for unsigned seals)

vdstools

VdsTools - Kotlin multiplatform library to work with Visible Digital Seals

Parse and verify a VDS / IDB

Configuring accepted seal types

Dispatching on seal type

Metadata messages (administrative documents)

Build a barcode

VDS

IDB

Custom seal codings

Loading Custom Codings

Using Custom Document Types

Available Coding Types

Byte-level structure inspection with the dissect package

How to include

Gradle

Maven

Related libraries

VdsTools - Kotlin multiplatform library to work with Visible Digital Seals

Parse and verify a VDS / IDB

Configuring accepted seal types

Dispatching on seal type

Metadata messages (administrative documents)

Build a barcode

VDS

IDB

Custom seal codings

Loading Custom Codings

Using Custom Document Types

Available Coding Types

Byte-level structure inspection with the dissect package

How to include

Gradle

Maven

Related libraries

Byte-level structure inspection with the `dissect` package

Byte-level structure inspection with the `dissect` package