Verifier

Verification API machinery.

Verifier(*, trusted_root)

The primary API for verification operations.

Create a new Verifier.

trusted_root is the TrustedRoot object containing the root of trust for the verification process.

Source code in sigstore/verify/verifier.py

def __init__(self, *, trusted_root: TrustedRoot):
    """
    Create a new `Verifier`.

    `trusted_root` is the `TrustedRoot` object containing the root of trust
    for the verification process.
    """
    self._fulcio_certificate_chain: list[X509] = [
        X509.from_cryptography(parent_cert)
        for parent_cert in trusted_root.get_fulcio_certs()
    ]
    self._trusted_root = trusted_root

    # this is an ugly hack needed for verifying "detached" materials
    # In reality we should be choosing the rekor instance based on the logid
    url = trusted_root._inner.tlogs[0].base_url
    self._rekor = RekorClient(url)

production(*, offline=False) classmethod

Return a Verifier instance configured against Sigstore's production-level services.

offline controls the Trusted Root refresh behavior: if True, the verifier uses the Trusted Root in the local TUF cache. If False, a TUF repository refresh is attempted.

Source code in sigstore/verify/verifier.py

@classmethod
def production(cls, *, offline: bool = False) -> Verifier:
    """
    Return a `Verifier` instance configured against Sigstore's production-level services.

    `offline` controls the Trusted Root refresh behavior: if `True`,
    the verifier uses the Trusted Root in the local TUF cache. If `False`,
    a TUF repository refresh is attempted.
    """
    config = ClientTrustConfig.production(offline=offline)
    return cls(
        trusted_root=config.trusted_root,
    )

staging(*, offline=False) classmethod

Return a Verifier instance configured against Sigstore's staging-level services.

offline controls the Trusted Root refresh behavior: if True, the verifier uses the Trusted Root in the local TUF cache. If False, a TUF repository refresh is attempted.

Source code in sigstore/verify/verifier.py

@classmethod
def staging(cls, *, offline: bool = False) -> Verifier:
    """
    Return a `Verifier` instance configured against Sigstore's staging-level services.

    `offline` controls the Trusted Root refresh behavior: if `True`,
    the verifier uses the Trusted Root in the local TUF cache. If `False`,
    a TUF repository refresh is attempted.
    """
    config = ClientTrustConfig.staging(offline=offline)
    return cls(
        trusted_root=config.trusted_root,
    )

verify_dsse(bundle, policy)

Verifies an bundle's DSSE envelope, returning the encapsulated payload and its content type.

This method is only for DSSE-enveloped payloads. To verify an arbitrary input against a bundle, use the verify_artifact method.

bundle is the Sigstore Bundle to both verify and verify against.

policy is the VerificationPolicy to verify against.

Returns a tuple of (type, payload), where type is the payload's type as encoded in the DSSE envelope and payload is the raw bytes of the payload. No validation of either type or payload is performed; users of this API must assert that type is known to them before proceeding to handle payload in an application-dependent manner.

Source code in sigstore/verify/verifier.py

def verify_dsse(
    self, bundle: Bundle, policy: VerificationPolicy
) -> tuple[str, bytes]:
    """
    Verifies an bundle's DSSE envelope, returning the encapsulated payload
    and its content type.

    This method is only for DSSE-enveloped payloads. To verify
    an arbitrary input against a bundle, use the `verify_artifact`
    method.

    `bundle` is the Sigstore `Bundle` to both verify and verify against.

    `policy` is the `VerificationPolicy` to verify against.

    Returns a tuple of `(type, payload)`, where `type` is the payload's
    type as encoded in the DSSE envelope and `payload` is the raw `bytes`
    of the payload. No validation of either `type` or `payload` is
    performed; users of this API **must** assert that `type` is known
    to them before proceeding to handle `payload` in an application-dependent
    manner.
    """

    # (1) through (6) are performed by `_verify_common_signing_cert`.
    self._verify_common_signing_cert(bundle, policy)

    # (7): verify the bundle's signature and DSSE envelope against the
    #      signing certificate's public key.
    envelope = bundle._dsse_envelope
    if envelope is None:
        raise VerificationError(
            "cannot perform DSSE verification on a bundle without a DSSE envelope"
        )

    signing_key = bundle.signing_certificate.public_key()
    signing_key = cast(ec.EllipticCurvePublicKey, signing_key)
    dsse._verify(signing_key, envelope)

    # (8): verify the consistency of the log entry's body against
    #      the other bundle materials.
    # NOTE: This is very slightly weaker than the consistency check
    # for hashedrekord entries, due to how inclusion is recorded for DSSE:
    # the included entry for DSSE includes an envelope hash that we
    # *cannot* verify, since the envelope is uncanonicalized JSON.
    # Instead, we manually pick apart the entry body below and verify
    # the parts we can (namely the payload hash and signature list).
    entry = bundle.log_entry
    if entry._inner.kind_version.kind != "dsse":
        raise VerificationError(
            f"Expected entry type dsse, got {entry._inner.kind_version.kind}"
        )
    if entry._inner.kind_version.version == "0.0.2":
        _validate_dsse_v002_entry_body(bundle)
    elif entry._inner.kind_version.version == "0.0.1":
        _validate_dsse_v001_entry_body(bundle)
    else:
        raise VerificationError(
            f"Unsupported dsse version {entry._inner.kind_version.version}"
        )

    return (envelope._inner.payload_type, envelope._inner.payload)

verify_artifact(input_, bundle, policy)

Public API for verifying.

input_ is the input to verify, either as a buffer of contents or as a prehashed Hashed object.

bundle is the Sigstore Bundle to verify against.

policy is the VerificationPolicy to verify against.

On failure, this method raises VerificationError.

Source code in sigstore/verify/verifier.py

def verify_artifact(
    self,
    input_: bytes | Hashed,
    bundle: Bundle,
    policy: VerificationPolicy,
) -> None:
    """
    Public API for verifying.

    `input_` is the input to verify, either as a buffer of contents or as
    a prehashed `Hashed` object.

    `bundle` is the Sigstore `Bundle` to verify against.

    `policy` is the `VerificationPolicy` to verify against.

    On failure, this method raises `VerificationError`.
    """

    # (1) through (6) are performed by `_verify_common_signing_cert`.
    self._verify_common_signing_cert(bundle, policy)

    hashed_input = sha256_digest(input_)

    # (7): verify that the signature was signed by the public key in the signing certificate.
    try:
        signing_key = bundle.signing_certificate.public_key()
        signing_key = cast(ec.EllipticCurvePublicKey, signing_key)
        signing_key.verify(
            bundle._inner.message_signature.signature,  # type: ignore[union-attr]
            hashed_input.digest,
            ec.ECDSA(hashed_input._as_prehashed()),
        )
    except InvalidSignature:
        raise VerificationError("Signature is invalid for input")

    _logger.debug("Successfully verified signature...")

    # (8): verify the consistency of the log entry's body against
    #      the other bundle materials (and input being verified).
    entry = bundle.log_entry
    if entry._inner.kind_version.kind != "hashedrekord":
        raise VerificationError(
            f"Expected entry type hashedrekord, got {entry._inner.kind_version.kind}"
        )

    if entry._inner.kind_version.version == "0.0.2":
        _validate_hashedrekord_v002_entry_body(bundle, hashed_input)
    elif entry._inner.kind_version.version == "0.0.1":
        _validate_hashedrekord_v001_entry_body(bundle, hashed_input)
    else:
        raise VerificationError(
            f"Unsupported hashedrekord version {entry._inner.kind_version.version}"
        )