Models

Common models shared between signing and verification.

LogInclusionProof

Bases: BaseModel

Represents an inclusion proof for a transparency log entry.

LogEntry

Represents a transparency log entry.

Log entries are retrieved from the transparency log after signing or verification events, or loaded from "Sigstore" bundles provided by the user.

This representation allows for either a missing inclusion promise or a missing inclusion proof, but not both: attempting to construct a LogEntry without at least one will fail.

uuid: Optional[str] instance-attribute

This entry's unique ID in the log instance it was retrieved from.

For sharded log deployments, IDs are unique per-shard.

Not present for LogEntry instances loaded from Sigstore bundles.

body: B64Str instance-attribute

The base64-encoded body of the transparency log entry.

integrated_time: int instance-attribute

The UNIX time at which this entry was integrated into the transparency log.

log_id: str instance-attribute

The log's ID (as the SHA256 hash of the DER-encoded public key for the log at the time of entry inclusion).

log_index: int instance-attribute

The index of this entry within the log.

inclusion_proof: LogInclusionProof instance-attribute

An inclusion proof for this log entry.

inclusion_promise: Optional[B64Str] instance-attribute

An inclusion promise for this log entry, if present.

Internally, this is a base64-encoded Signed Entry Timestamp (SET) for this log entry.

encode_canonical()

Returns a canonicalized JSON (RFC 8785) representation of the transparency log entry.

This encoded representation is suitable for verification against the Signed Entry Timestamp.

Source code in sigstore/models.py

def encode_canonical(self) -> bytes:
    """
    Returns a canonicalized JSON (RFC 8785) representation of the transparency log entry.

    This encoded representation is suitable for verification against
    the Signed Entry Timestamp.
    """
    payload: dict[str, int | str] = {
        "body": self.body,
        "integratedTime": self.integrated_time,
        "logID": self.log_id,
        "logIndex": self.log_index,
    }

    return rfc8785.dumps(payload)

TimestampVerificationData(inner)

Represents a TimestampVerificationData structure.

@private

Init method.

Source code in sigstore/models.py

def __init__(self, inner: _TimestampVerificationData) -> None:
    """Init method."""
    self._inner = inner
    self._verify()

rfc3161_timestamps: list[TimeStampResponse] property

Returns a list of signed timestamp.

from_json(raw) classmethod

Deserialize the given timestamp verification data.

Source code in sigstore/models.py

@classmethod
def from_json(cls, raw: str | bytes) -> TimestampVerificationData:
    """
    Deserialize the given timestamp verification data.
    """
    inner = _TimestampVerificationData().from_json(raw)
    return cls(inner)

VerificationMaterial(inner)

Represents a VerificationMaterial structure.

Init method.

Source code in sigstore/models.py

def __init__(self, inner: _VerificationMaterial) -> None:
    """Init method."""
    self._inner = inner

timestamp_verification_data: TimestampVerificationData property

Returns the Timestamp Verification Data.

InvalidBundle

Bases: Error

Raised when the associated Bundle is invalid in some way.

diagnostics()

Returns diagnostics for the error.

Source code in sigstore/models.py

def diagnostics(self) -> str:
    """Returns diagnostics for the error."""

    return dedent(
        f"""\
    An issue occurred while parsing the Sigstore bundle.

    The provided bundle is malformed and may have been modified maliciously.

    Additional context:

    {self}
    """
    )

Bundle(inner)

Represents a Sigstore bundle.

Creates a new bundle. This is not a public API; use from_json instead.

@private

Source code in sigstore/models.py

def __init__(self, inner: _Bundle) -> None:
    """
    Creates a new bundle. This is not a public API; use
    `from_json` instead.

    @private
    """
    self._inner = inner
    self._verify()

signing_certificate: Certificate property

Returns the bundle's contained signing (i.e. leaf) certificate.

log_entry: LogEntry property

Returns the bundle's log entry, containing an inclusion proof (with checkpoint) and an inclusion promise (if the latter is present).

signature: bytes property

Returns the signature bytes of this bundle. Either from the DSSE Envelope or from the message itself.

verification_material: VerificationMaterial property

Returns the bundle's verification material.

BundleType

Bases: str, Enum

Known Sigstore bundle media types.

from_json(raw) classmethod

Deserialize the given Sigstore bundle.

Source code in sigstore/models.py

@classmethod
def from_json(cls, raw: bytes | str) -> Bundle:
    """
    Deserialize the given Sigstore bundle.
    """
    inner = _Bundle().from_json(raw)
    return cls(inner)

to_json()

Return a JSON encoding of this bundle.

Source code in sigstore/models.py

def to_json(self) -> str:
    """
    Return a JSON encoding of this bundle.
    """
    return self._inner.to_json()

from_parts(cert, sig, log_entry) classmethod

Construct a Sigstore bundle (of hashedrekord type) from its constituent parts.

Source code in sigstore/models.py

@classmethod
def from_parts(cls, cert: Certificate, sig: bytes, log_entry: LogEntry) -> Bundle:
    """
    Construct a Sigstore bundle (of `hashedrekord` type) from its
    constituent parts.
    """

    return cls._from_parts(
        cert, common_v1.MessageSignature(signature=sig), log_entry
    )