VDS Verification

The Bioseal SDK provides a comprehensive process to decode and verify a Visible Digital Seal (VDS) embedded in documents. This process ensures that the document’s data is authentic, unaltered, and issued by a trusted authority.

What the SDK Handles Internally

The BioSeal SDK abstracts the complexity of the VDS verification. When you call a verify_from_… method, the SDK internally manages:

  • VDS Structure Parsing: Deconstructing the header, payload, signature, and auxiliary data.

  • Trust Chain Validation: Navigating and verifying the hierarchy of Trust Lists (LoTLs, TSLs) and certificates up to a trusted anchor. This involves XML parsing, signature validation of these lists, and status checks.

  • Manifest Processing: Retrieving, validating (signature and identity), and parsing the VDS Manifest to understand the VDS data schema, policies, and extensions.

  • Cryptographic Operations: Securely performing hash calculations and digital signature verifications.

  • Schema and Constraint Validation: Ensuring the VDS payload data conforms to the rules defined in the Manifest.

  • Extension Evaluation: Interpreting and applying VDS-specific extensions that can modify validation logic or data interpretation.

Optional Controls

For advanced scenarios, you can fine-tune the verification process:

It’s generally recommended to keep these at their default True values for full security.

Core Verification Workflow

1. Preparation

Before you start verifying VDS instances:

  • Initialize the SDK: Ensure the license is correctly set up and validated for your application.

  • (Optional) Configure Trust Anchors:

    • If you know the specific List of Trust Lists (LoTL) or Trust Service List (TSL) your VDS instances will use, you can provide their URLs directly using:

    • If not specified, the SDK will attempt to use a default VDSIC Governance List or discover it based on VDS data.

  • (Optional) Implement Callbacks: If your VDS ecosystem requires fetching external resources (like LoTLs, TSLs, certificates, manifests) from specific locations or if your VDS uses encrypted fields, you’ll need to implement:

2. Acquire the VDS Data

Your application is responsible for obtaining the VDS data. This might come from:

  • Scanning a QR code or other 2D barcode (you can use BarcodeReader Class for this).

  • Reading from an NFC tag.

  • Receiving it as a file or a URL fragment.

The VDS data can be in raw binary form or a string-encoded format (e.g., Base64).

2. Decode and Verify the VDS

Use one of the SDK’s verification functions based on your data format:

vds = Bioseal()

try:
  result = vds.verify_from_buffer(data)
except BiosealException as ex:
    print(f"SDK exception: {ex}")

(Alternatively, use verify_from_string if your VDS is in string format.)

During this step, the SDK decodes the VDS into its components (header, payload, and signature), computes the necessary hashes, and compares them with the embedded signature.

3. Certificate and Trust Chain Validation

The SDK checks that:

  • The signature computed from the header and payload matches the embedded signature.

  • The signing certificate is valid (including key usage, expiration, and revocation status).

  • The certificate chain is trusted by comparing it with an established list of authorized issuers.

4. Review the Verification Result

The function returns a VerificationResult Structure that indicates whether the signature is valid and if the trust chain is intact. This object includes the following information:

5. Accessing and Presenting VDS Data

If verification is successful, you can access the VDS content:

vds.payload
vds.aux_data

  • HTML Presentation (RFF): If the VDS Manifest defines an HTML-based Response Formatting Function (RFF), you can get the ready-to-display HTML from Bioseal.htmlView Property or generate it using id3_bioseal_bioseal_build_html_view_class_method by specifying a language.

vds.build_html_view("en", true)

  • JSON Representation: Get a JSON string of the VDS content (header, payload, signature details) using id3_bioseal_bioseal_build_vds_as_json_class_method.

vds.build_vds_as_json()

  • XML Representation: Get an XML string representation using id3_bioseal_bioseal_build_vds_as_xml_class_method.

vds.build_vds_as_xml()

vds.get_document_name()
vds.get_document_description()

vds.get_certificate_information()

6. Retrieve Information

Further Assistance

  • The Lotl Class class can be used independently to parse LoTL files and find TSL URLs.

  • The Manifest Class class can load and parse manifest files independently.

  • Check the specific API documentation for each class and method for more details.

This overview should help you understand the main interactions with the BioSeal SDK for VDS verification. Remember to consult the Bioseal.log Property for detailed insights during development and troubleshooting.

See Also