.. index:: 
  !Usage

.. _vds_verification:

================
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:

-   :ref:`id3_bioseal_bioseal_verifies_governance_class_member`: Set to `False` to skip the governance chain verification (LoTL/TSL checks). Useful if you are providing a pre-validated TSL or Manifest directly.
-   :ref:`id3_bioseal_bioseal_verifies_signature_class_member`: Set to `False` to skip cryptographic signature verification of the VDS itself.
-   :ref:`id3_bioseal_bioseal_verifies_crl_updates_class_member`: Controls strictness of CRL `nextUpdate` field checking.

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:

        -   :ref:`id3_bioseal_bioseal_lotl_url_class_member`
        -   :ref:`id3_bioseal_bioseal_tsl_url_class_member`

    -   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:

    -   :ref:`id3_bioseal_bioseal_external_resource_callback_class_member`: To handle the retrieval of these external resources. The SDK will call this function with a :ref:`id3_bioseal_resource_callback_args_class` object detailing the required resource.

    -   :ref:`id3_bioseal_bioseal_decryption_callback_class_member`: To handle the decryption of specific payload fields. The SDK will call this with :ref:`id3_bioseal_decryption_args_class`.

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 :ref:`id3_bioseal_barcode_reader_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:

.. code:: Python

    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 :ref:`id3_bioseal_verification_result_struct` that indicates whether the signature is valid and if the trust chain is intact. This object includes the following information:

* **Authenticity, Integrity**

  - :ref:`The signature is valid<id3_bioseal_verification_result_vds_signature_verified_struct_member>`
  - :ref:`The certification chain is intact<id3_bioseal_verification_result_certification_chain_verified_struct_member>`
  - :ref:`The signer is legitimate<id3_bioseal_verification_result_signing_certificate_usage_authorized_struct_member>`

* **Validity**

  - :ref:`The VDS is still valid, ie. it has not expired<id3_bioseal_verification_result_vds_not_expired_struct_member>`

* **Trust Chain**

  - :ref:`The LoTL is valid<id3_bioseal_verification_result_lotl_governance_valid_struct_member>`
  - :ref:`The TSL is valid<id3_bioseal_verification_result_tsl_governance_valid_struct_member>`
  - :ref:`The manifest is valid<id3_bioseal_verification_result_manifest_governance_valid_struct_member>`
  - :ref:`The CA certificate is valid<id3_bioseal_verification_result_ca_certificate_verified_struct_member>`


5. Accessing and Presenting VDS Data
------------------------------------
If verification is successful, you can access the VDS content:

-   **Payload Data**: Access through :ref:`id3_bioseal_bioseal_payload_class_member` (a :ref:`id3_bioseal_bioseal_payload_class_member` object that acts like a dictionary). You can also access :ref:`id3_bioseal_bioseal_aux_data_class_member` if present.

.. code:: Python

    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 :ref:`id3_bioseal_bioseal_html_view_class_member` or generate it using :ref:`id3_bioseal_bioseal_build_html_view_class_method` by specifying a language.

.. code:: Python

    vds.build_html_view("en", true)

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

.. code:: Python

    vds.build_vds_as_json()

-   **XML Representation**: Get an XML string representation using :ref:`id3_bioseal_bioseal_build_vds_as_xml_class_method`.

.. code:: Python

    vds.build_vds_as_xml()

-   **Document Information**: Retrieve the document name and description using :ref:`id3_bioseal_bioseal_get_document_name_class_method` and :ref:`id3_bioseal_bioseal_get_document_description_class_method`.

.. code:: Python

    vds.get_document_name()
    vds.get_document_description()

-   **Certificate Details**: Information about the VDS signing certificate is available via :ref:`id3_bioseal_bioseal_certificate_information_class_member`.

.. code:: Python

    vds.get_certificate_information()

6. Retrieve Information
---------------------------

* **VDS**

  * :ref:`Format<id3_bioseal_bioseal_format_class_member>`: The format of the VDS (ISO 22376:2023 or ISO 22385:2023).
  * :ref:`Scheme Operator ID<id3_bioseal_bioseal_issuing_agency_code_class_member>`: The Issuing Agency Code (IAC) of the VDS Scheme Operator.
  * :ref:`Signature Date<id3_bioseal_bioseal_signature_date_class_member>`: The date when the VDS was signed.
  * :ref:`Expiry Date<id3_bioseal_bioseal_expiration_date_class_member>`: The date when the VDS expires.

* **Use Case**

  * :ref:`Manifest ID<id3_bioseal_bioseal_manifest_id_class_member>`: The ID of the VDS manifest.
  * :ref:`Name<id3_bioseal_bioseal_get_document_name_class_method>`: The name of the document.
  * :ref:`Description<id3_bioseal_bioseal_get_document_description_class_method>`: The description of the document.

* **Signing Certificate**

  * :ref:`Identifier<id3_bioseal_bioseal_certificate_identifier_class_member>`: The identifier of the signing certificate.
  * :ref:`Common Name<id3_bioseal_certificate_information_subject_common_name_class_member>`: The common name of the signing certificate.
  * :ref:`Country<id3_bioseal_certificate_information_subject_country_class_member>`: The country of the signing certificate.
  * :ref:`Distinguished Name<id3_bioseal_certificate_information_subject_distinguished_name_class_member>`: The distinguished name of the signing certificate.
  * :ref:`Organization<id3_bioseal_certificate_information_subject_organization_class_member>`: The organization of the signing certificate.
  * :ref:`Organizational Unit<id3_bioseal_certificate_information_subject_organizational_unit_class_member>`: The organizational unit of the signing certificate.
  * :ref:`Key Usage List<id3_bioseal_certificate_information_key_usage_class_member>`: The key usage list of the signing certificate.
  * :ref:`Expiry Date<id3_bioseal_certificate_information_not_after_class_member>`: The expiry date of the signing certificate.
  * :ref:`Issuing Date<id3_bioseal_certificate_information_not_before_class_member>`: The issuing date of the signing certificate.
  * :ref:`Policies<id3_bioseal_certificate_information_policies_class_member>`: The policies of the signing certificate.
  * :ref:`Public Key<id3_bioseal_certificate_information_public_key_class_member>`: The public key of the signing certificate.
  * :ref:`Serial Number<id3_bioseal_certificate_information_serial_number_class_member>`: The serial number of the signing certificate.
  * :ref:`Signature Algorithm OID<id3_bioseal_certificate_information_signature_algorithm_class_member>`: The signature algorithm OID of the signing certificate.
  * :ref:`Version<id3_bioseal_certificate_information_version_class_member>`: The version of the signing certificate.

* **Certificate Authority**
  
  * :ref:`Identifier<id3_bioseal_bioseal_certificate_authority_reference_class_member>`: The identifier of the certificate authority.
  * :ref:`Common Name<id3_bioseal_certificate_information_issuer_common_name_class_member>`: The common name of the certificate authority.
  * :ref:`Country<id3_bioseal_certificate_information_issuer_country_class_member>`: The country of the certificate authority.
  * :ref:`Distinguished Name<id3_bioseal_certificate_information_issuer_distinguished_name_class_member>`: The distinguished name of the certificate authority.
  * :ref:`Organization<id3_bioseal_certificate_information_issuer_organization_class_member>`: The organization of the certificate authority.
  * :ref:`Organizational Unit<id3_bioseal_certificate_information_issuer_organizational_unit_class_member>`: The organizational unit of the certificate authority.

Further Assistance
==================
-   The :ref:`id3_bioseal_lotl_class` class can be used independently to parse LoTL files and find TSL URLs.
-   The :ref:`id3_bioseal_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 :ref:`id3_bioseal_bioseal_log_class_member` for detailed insights during development and troubleshooting.

See Also
========
- :ref:`id3_bioseal_bioseal_class`
- :ref:`id3_bioseal_verification_result_struct`
- :ref:`id3_bioseal_certificate_information_class`
