Skip to content

Policy

APIs for describing identity verification "policies", which describe how the identities passed into an individual verification step are verified.

OIDCIssuer(value)

Bases: _SingleX509ExtPolicy

Verifies the certificate's OIDC issuer, identified by an X.509v3 extension tagged with 1.3.6.1.4.1.57264.1.1.

Creates the new policy, with value as the expected value during verification.

Source code in sigstore/verify/policy.py 
80
81
82
83
84
85
def __init__(self, value: str) -> None:
    """
    Creates the new policy, with `value` as the expected value during
    verification.
    """
    self._value = value

GitHubWorkflowTrigger(value)

Bases: _SingleX509ExtPolicy

Verifies the certificate's GitHub Actions workflow trigger, identified by an X.509v3 extension tagged with 1.3.6.1.4.1.57264.1.2.

Creates the new policy, with value as the expected value during verification.

Source code in sigstore/verify/policy.py 
80
81
82
83
84
85
def __init__(self, value: str) -> None:
    """
    Creates the new policy, with `value` as the expected value during
    verification.
    """
    self._value = value

GitHubWorkflowSHA(value)

Bases: _SingleX509ExtPolicy

Verifies the certificate's GitHub Actions workflow commit SHA, identified by an X.509v3 extension tagged with 1.3.6.1.4.1.57264.1.3.

Creates the new policy, with value as the expected value during verification.

Source code in sigstore/verify/policy.py 
80
81
82
83
84
85
def __init__(self, value: str) -> None:
    """
    Creates the new policy, with `value` as the expected value during
    verification.
    """
    self._value = value

GitHubWorkflowName(value)

Bases: _SingleX509ExtPolicy

Verifies the certificate's GitHub Actions workflow name, identified by an X.509v3 extension tagged with 1.3.6.1.4.1.57264.1.4.

Creates the new policy, with value as the expected value during verification.

Source code in sigstore/verify/policy.py 
80
81
82
83
84
85
def __init__(self, value: str) -> None:
    """
    Creates the new policy, with `value` as the expected value during
    verification.
    """
    self._value = value

GitHubWorkflowRepository(value)

Bases: _SingleX509ExtPolicy

Verifies the certificate's GitHub Actions workflow repository, identified by an X.509v3 extension tagged with 1.3.6.1.4.1.57264.1.5.

Creates the new policy, with value as the expected value during verification.

Source code in sigstore/verify/policy.py 
80
81
82
83
84
85
def __init__(self, value: str) -> None:
    """
    Creates the new policy, with `value` as the expected value during
    verification.
    """
    self._value = value

GitHubWorkflowRef(value)

Bases: _SingleX509ExtPolicy

Verifies the certificate's GitHub Actions workflow ref, identified by an X.509v3 extension tagged with 1.3.6.1.4.1.57264.1.6.

Creates the new policy, with value as the expected value during verification.

Source code in sigstore/verify/policy.py 
80
81
82
83
84
85
def __init__(self, value: str) -> None:
    """
    Creates the new policy, with `value` as the expected value during
    verification.
    """
    self._value = value

OIDCIssuerV2(value)

Bases: _SingleX509ExtPolicyV2

Verifies the certificate's OIDC issuer, identified by an X.509v3 extension tagged with 1.3.6.1.4.1.57264.1.8. The difference with OIDCIssuer is that the value for this extension is formatted to the RFC 5280 specification as a DER-encoded string.

Creates the new policy, with value as the expected value during verification.

Source code in sigstore/verify/policy.py 
80
81
82
83
84
85
def __init__(self, value: str) -> None:
    """
    Creates the new policy, with `value` as the expected value during
    verification.
    """
    self._value = value

OIDCBuildSignerURI(value)

Bases: _SingleX509ExtPolicyV2

Verifies the certificate's OIDC Build Signer URI, identified by an X.509v3 extension tagged with 1.3.6.1.4.1.57264.1.9.

Creates the new policy, with value as the expected value during verification.

Source code in sigstore/verify/policy.py 
80
81
82
83
84
85
def __init__(self, value: str) -> None:
    """
    Creates the new policy, with `value` as the expected value during
    verification.
    """
    self._value = value

OIDCBuildSignerDigest(value)

Bases: _SingleX509ExtPolicyV2

Verifies the certificate's OIDC Build Signer Digest, identified by an X.509v3 extension tagged with 1.3.6.1.4.1.57264.1.10.

Creates the new policy, with value as the expected value during verification.

Source code in sigstore/verify/policy.py 
80
81
82
83
84
85
def __init__(self, value: str) -> None:
    """
    Creates the new policy, with `value` as the expected value during
    verification.
    """
    self._value = value

OIDCRunnerEnvironment(value)

Bases: _SingleX509ExtPolicyV2

Verifies the certificate's OIDC Runner Environment, identified by an X.509v3 extension tagged with 1.3.6.1.4.1.57264.1.11.

Creates the new policy, with value as the expected value during verification.

Source code in sigstore/verify/policy.py 
80
81
82
83
84
85
def __init__(self, value: str) -> None:
    """
    Creates the new policy, with `value` as the expected value during
    verification.
    """
    self._value = value

OIDCSourceRepositoryURI(value)

Bases: _SingleX509ExtPolicyV2

Verifies the certificate's OIDC Source Repository URI, identified by an X.509v3 extension tagged with 1.3.6.1.4.1.57264.1.12.

Creates the new policy, with value as the expected value during verification.

Source code in sigstore/verify/policy.py 
80
81
82
83
84
85
def __init__(self, value: str) -> None:
    """
    Creates the new policy, with `value` as the expected value during
    verification.
    """
    self._value = value

OIDCSourceRepositoryDigest(value)

Bases: _SingleX509ExtPolicyV2

Verifies the certificate's OIDC Source Repository Digest, identified by an X.509v3 extension tagged with 1.3.6.1.4.1.57264.1.13.

Creates the new policy, with value as the expected value during verification.

Source code in sigstore/verify/policy.py 
80
81
82
83
84
85
def __init__(self, value: str) -> None:
    """
    Creates the new policy, with `value` as the expected value during
    verification.
    """
    self._value = value

OIDCSourceRepositoryRef(value)

Bases: _SingleX509ExtPolicyV2

Verifies the certificate's OIDC Source Repository Ref, identified by an X.509v3 extension tagged with 1.3.6.1.4.1.57264.1.14.

Creates the new policy, with value as the expected value during verification.

Source code in sigstore/verify/policy.py 
80
81
82
83
84
85
def __init__(self, value: str) -> None:
    """
    Creates the new policy, with `value` as the expected value during
    verification.
    """
    self._value = value

OIDCSourceRepositoryIdentifier(value)

Bases: _SingleX509ExtPolicyV2

Verifies the certificate's OIDC Source Repository Identifier, identified by an X.509v3 extension tagged with 1.3.6.1.4.1.57264.1.15.

Creates the new policy, with value as the expected value during verification.

Source code in sigstore/verify/policy.py 
80
81
82
83
84
85
def __init__(self, value: str) -> None:
    """
    Creates the new policy, with `value` as the expected value during
    verification.
    """
    self._value = value

OIDCSourceRepositoryOwnerURI(value)

Bases: _SingleX509ExtPolicyV2

Verifies the certificate's OIDC Source Repository Owner URI, identified by an X.509v3 extension tagged with 1.3.6.1.4.1.57264.1.16.

Creates the new policy, with value as the expected value during verification.

Source code in sigstore/verify/policy.py 
80
81
82
83
84
85
def __init__(self, value: str) -> None:
    """
    Creates the new policy, with `value` as the expected value during
    verification.
    """
    self._value = value

OIDCSourceRepositoryOwnerIdentifier(value)

Bases: _SingleX509ExtPolicyV2

Verifies the certificate's OIDC Source Repository Owner Identifier, identified by an X.509v3 extension tagged with 1.3.6.1.4.1.57264.1.17.

Creates the new policy, with value as the expected value during verification.

Source code in sigstore/verify/policy.py 
80
81
82
83
84
85
def __init__(self, value: str) -> None:
    """
    Creates the new policy, with `value` as the expected value during
    verification.
    """
    self._value = value

OIDCBuildConfigURI(value)

Bases: _SingleX509ExtPolicyV2

Verifies the certificate's OIDC Build Config URI, identified by an X.509v3 extension tagged with 1.3.6.1.4.1.57264.1.18.

Creates the new policy, with value as the expected value during verification.

Source code in sigstore/verify/policy.py 
80
81
82
83
84
85
def __init__(self, value: str) -> None:
    """
    Creates the new policy, with `value` as the expected value during
    verification.
    """
    self._value = value

OIDCBuildConfigDigest(value)

Bases: _SingleX509ExtPolicyV2

Verifies the certificate's OIDC Build Config Digest, identified by an X.509v3 extension tagged with 1.3.6.1.4.1.57264.1.19.

Creates the new policy, with value as the expected value during verification.

Source code in sigstore/verify/policy.py 
80
81
82
83
84
85
def __init__(self, value: str) -> None:
    """
    Creates the new policy, with `value` as the expected value during
    verification.
    """
    self._value = value

OIDCBuildTrigger(value)

Bases: _SingleX509ExtPolicyV2

Verifies the certificate's OIDC Build Trigger, identified by an X.509v3 extension tagged with 1.3.6.1.4.1.57264.1.20.

Creates the new policy, with value as the expected value during verification.

Source code in sigstore/verify/policy.py 
80
81
82
83
84
85
def __init__(self, value: str) -> None:
    """
    Creates the new policy, with `value` as the expected value during
    verification.
    """
    self._value = value

OIDCRunInvocationURI(value)

Bases: _SingleX509ExtPolicyV2

Verifies the certificate's OIDC Run Invocation URI, identified by an X.509v3 extension tagged with 1.3.6.1.4.1.57264.1.21.

Creates the new policy, with value as the expected value during verification.

Source code in sigstore/verify/policy.py 
80
81
82
83
84
85
def __init__(self, value: str) -> None:
    """
    Creates the new policy, with `value` as the expected value during
    verification.
    """
    self._value = value

OIDCSourceRepositoryVisibility(value)

Bases: _SingleX509ExtPolicyV2

Verifies the certificate's OIDC Source Repository Visibility At Signing, identified by an X.509v3 extension tagged with 1.3.6.1.4.1.57264.1.22.

Creates the new policy, with value as the expected value during verification.

Source code in sigstore/verify/policy.py 
80
81
82
83
84
85
def __init__(self, value: str) -> None:
    """
    Creates the new policy, with `value` as the expected value during
    verification.
    """
    self._value = value

VerificationPolicy

Bases: Protocol

A protocol type describing the interface that all verification policies conform to.

verify(cert) abstractmethod

Verify the given cert against this policy, raising VerificationError on failure.

Source code in sigstore/verify/policy.py 
349
350
351
352
353
354
355
@abstractmethod
def verify(self, cert: Certificate) -> None:
    """
    Verify the given `cert` against this policy, raising `VerificationError`
    on failure.
    """
    raise NotImplementedError  # pragma: no cover

AnyOf(children)

The "any of" policy, corresponding to a logical OR between child policies.

An empty list of child policies is considered trivially invalid.

Create a new AnyOf, with the given child policies.

Source code in sigstore/verify/policy.py 
365
366
367
368
369
def __init__(self, children: list[VerificationPolicy]):
    """
    Create a new `AnyOf`, with the given child policies.
    """
    self._children = children

verify(cert)

Verify cert against the policy.

Raises VerificationError on failure.

Source code in sigstore/verify/policy.py 
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
def verify(self, cert: Certificate) -> None:
    """
    Verify `cert` against the policy.

    Raises `VerificationError` on failure.
    """

    for child in self._children:
        try:
            child.verify(cert)
        except VerificationError:
            pass
        else:
            return

    raise VerificationError(f"0 of {len(self._children)} policies succeeded")

AllOf(children)

The "all of" policy, corresponding to a logical AND between child policies.

An empty list of child policies is considered trivially invalid.

Create a new AllOf, with the given child policies.

Source code in sigstore/verify/policy.py 
397
398
399
400
401
402
def __init__(self, children: list[VerificationPolicy]):
    """
    Create a new `AllOf`, with the given child policies.
    """

    self._children = children

verify(cert)

Verify cert against the policy.

Source code in sigstore/verify/policy.py 
404
405
406
407
408
409
410
411
412
413
414
415
416
def verify(self, cert: Certificate) -> None:
    """
    Verify `cert` against the policy.
    """

    # Without this, we'd consider empty lists of child policies trivially valid.
    # This is almost certainly not what the user wants and is a potential
    # source of API misuse, so we explicitly disallow it.
    if len(self._children) < 1:
        raise VerificationError("no child policies to verify")

    for child in self._children:
        child.verify(cert)

UnsafeNoOp

The "no-op" policy, corresponding to a no-op "verification".

This policy is fundamentally insecure. You cannot use it safely. It must not be used to verify any sort of certificate identity, because it cannot do so. Using this policy is equivalent to reducing the verification proof down to an integrity check against a completely untrusted and potentially attacker-created signature. It must only be used for testing purposes.

verify(cert)

Verify cert against the policy.

Source code in sigstore/verify/policy.py 
431
432
433
434
435
436
437
438
def verify(self, cert: Certificate) -> None:
    """
    Verify `cert` against the policy.
    """

    _logger.warning(
        "unsafe (no-op) verification policy used! no verification performed!"
    )

Identity(*, identity, issuer=None)

Verifies the certificate's "identity", corresponding to the X.509v3 SAN.

Identities can be verified modulo an OIDC issuer, to prevent an unexpected issuer from offering a particular identity.

Supported SAN types include emails, URIs, and Sigstore-specific "other names".

Create a new Identity, with the given expected identity and issuer values.

Source code in sigstore/verify/policy.py 
453
454
455
456
457
458
459
460
461
462
def __init__(self, *, identity: str, issuer: str | None = None):
    """
    Create a new `Identity`, with the given expected identity and issuer values.
    """

    self._identity = identity
    if issuer:
        self._issuer = OIDCIssuer(issuer)
    else:
        self._issuer = None

verify(cert)

Verify cert against the policy.

Source code in sigstore/verify/policy.py 
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
def verify(self, cert: Certificate) -> None:
    """
    Verify `cert` against the policy.
    """

    if self._issuer:
        self._issuer.verify(cert)

    # Build a set of all valid identities.
    san_ext = cert.extensions.get_extension_for_class(SubjectAlternativeName).value
    all_sans = set(san_ext.get_values_for_type(RFC822Name))
    all_sans.update(san_ext.get_values_for_type(UniformResourceIdentifier))
    all_sans.update(
        [
            on.value.decode()
            for on in san_ext.get_values_for_type(OtherName)
            if on.type_id == _OTHERNAME_OID
        ]
    )

    verified = self._identity in all_sans
    if not verified:
        raise VerificationError(
            f"Certificate's SANs do not match {self._identity}; actual SANs: {all_sans}"
        )