VerifiableData Class

Overview

The VerifiableData class represents digitally signed data whose integrity can be cryptographically verified. It comprises serialized data and metadata, along with a list of attestations (digital signatures) that can be verified.

Package: keychain.core.verifiable_data

from keychain.core.verifiable_data import VerifiableData

Class Definition

class VerifiableData(SerializableObject):
    """Represents digitally signed data whose integrity can be cryptographically verified."""

Constructor

def __init__(
    self,
    serialized_string: Optional[bytes] = None,
    serialization_format: SerializationFormat = SerializationFormat.PROTOBUF,
    serialized_data: Optional[SerializedData] = None,
    c_pointer: Optional[ctypes.c_void_p] = None,
) -> None

Initialize a VerifiableData object. VerifiableData objects are typically created through Gateway.sign() or Persona.sign() methods.

Parameters:

  • serialized_string (bytes, optional) - Serialized verifiable data bytes to deserialize

  • serialization_format (SerializationFormat) - Format of the serialized string (default: PROTOBUF)

  • serialized_data (SerializedData, optional) - SerializedData object to construct from

  • c_pointer (ctypes.c_void_p, optional) - Existing C pointer to wrap

Example:

# Create from serialized bytes
vdata = VerifiableData(serialized_string=vdata_bytes)

# Create from existing C pointer (typically from library functions)
vdata = VerifiableData(c_pointer=existing_pointer)

Class Methods

from_copy(other)

@classmethod
def from_copy(cls, other: "VerifiableData") -> "VerifiableData"

Create a deep copy of an existing verifiable data object.

Parameters:

  • other (VerifiableData) - The verifiable data to copy

Returns: New VerifiableData instance that is a deep copy

Example:

original_vdata = gateway.sign(persona, data)
copied_vdata = VerifiableData.from_copy(original_vdata)

Properties

cleartext

@property
def cleartext(self) -> SerializedData

Get the original data as SerializedData.

Returns: SerializedData object containing the original data

content

@property
def content(self) -> str

Get the original serialized data string. Equivalent to cleartext().content().

Returns: The original data content string

version

@property
def version(self) -> Version

Get the serialization data format version.

Returns: Version enumeration value

timestamp

@property
def timestamp(self) -> int

Get the timestamp.

Returns: The timestamp as number of milliseconds since the epoch

tags

@property
def tags(self) -> TagSet

Get the tags tag set containing metadata.

Returns: TagSet object with metadata tags

base_variables

@property
def base_variables(self) -> TagSet

Get the original verifiable variable tag set (stack variables at time index 0).

Returns: TagSet object with the initial variable set

attestations

@property
def attestations(self) -> List[Attestation]

Get the attestations (digital signatures).

Returns: List of Attestation objects

Methods

stack_variables(time_index)

def stack_variables(self, time_index: int) -> TagSet

Get the current (merged) stack variables at the specified time index.

Parameters:

  • time_index (int) - Time index (0 = initial variables, 1 = after first attestation, etc.)

Returns: TagSet object with merged variables at the specified time

Example:

# Get initial variables
initial_vars = vdata.stack_variables(0)

# Get variables after first attestation
updated_vars = vdata.stack_variables(1)

copy()

def copy(self) -> "VerifiableData"

Create a deep copy of this verifiable data.

Returns: New VerifiableData instance that is a deep copy

reattach_attachable_attestation(attestation)

def reattach_attachable_attestation(self, attestation: Attestation) -> None

Attach an attachable attestation to the verifiable data.

Parameters:

  • attestation (Attestation) - The attestation to attach

Raises: KeychainError if the attestation cannot be attached

serialize()

def serialize(self) -> bytes

Serialize the verifiable data to bytes.

Returns: Bytes serialization in protobuf format

data_type()

def data_type(self) -> DataType

Get the data type.

Returns: DataType.VERIFIABLE_DATA

Comparison Methods

eq(other)

def __eq__(self, other: object) -> bool

Compare verifiable data for equality.

Parameters:

  • other (VerifiableData) - The other verifiable data to compare

Returns: True if verifiable data are equal

Example: Creating and Using VerifiableData

from keychain.gateway import Gateway
from keychain.core.serialized_data import SerializedData
from keychain.core.tag_set import TagSet
from keychain.constants import SecurityLevel, DataType
import time

# Initialize gateway
settings = Gateway.init("keychain.config")
gateway = Gateway(settings)

try:
    # Create personas
    alice = gateway.create_persona(
        name="alice",
        subname="company.com",
        security_level=SecurityLevel.HIGH,
        auto_renew=True
    )

    bob = gateway.create_persona(
        name="bob",
        subname="company.com",
        security_level=SecurityLevel.HIGH,
        auto_renew=True
    )

    # Wait for personas to mature
    if not alice.is_mature():
        alice.await_maturity()
    if not bob.is_mature():
        bob.await_maturity()

    # Add Bob as a contact for Alice
    bob_contact = alice.add_contact("bob", "company.com", bob.did)

    # Create document to be signed
    document_content = "Important contract terms and conditions"
    document = SerializedData.from_string(document_content, DataType.UTF8_STRING)

    # Alice signs the document
    signed_document = alice.sign(
        cleartext=document,
        is_approval=True
    )

    print("Document signed successfully")

    # Display verifiable data information
    print(f"Content: {signed_document.content}")
    print(f"Timestamp: {signed_document.timestamp}")
    print(f"Version: {signed_document.version}")
    print(f"Data Type: {signed_document.data_type()}")

    # Access attestations
    attestations = signed_document.attestations
    print(f"\nAttestations: {len(attestations)}")
    for i, attestation in enumerate(attestations):
        print(f"  Attestation {i+1}: Present")

    # Access original cleartext
    cleartext_data = signed_document.cleartext
    print(f"Original data: {cleartext_data.content}")

    # Add metadata tags
    tags = signed_document.tags
    print(f"Metadata tags available")

finally:
    Gateway.close()

See Also