# `Stevedore.Verify`
[🔗](https://github.com/oshlabs/stevedore/blob/v0.2.0/lib/stevedore/verify.ex#L1)

Verify an image's signatures against a policy. Default-deny: verification fails unless a
signature satisfies the policy.

Signatures are supplied directly (`opts[:signatures]`, a list of cosign signature artifact
images) or fetched from a transport (`opts[:transport]`) via the Referrers API / the cosign
`.sig` tag. Each cosign signature layer's payload is checked against the policy's public keys
with native ECDSA (`Stevedore.Sign.Sigstore`).

Spec: [cosign SIGNATURE_SPEC](https://github.com/sigstore/cosign/blob/main/specs/SIGNATURE_SPEC.md).

# `policy`

```elixir
@type policy() :: %{optional(:keys) => [pubkey()], optional(:require) => :any | :all}
```

# `pubkey`

```elixir
@type pubkey() :: binary() | tuple()
```

# `verified`

```elixir
@type verified() :: %{key: pubkey(), signature: String.t()}
```

# `image`

```elixir
@spec image(Stevedore.Image.t() | Stevedore.Digest.t(), policy(), keyword()) ::
  {:ok, [verified()]} | {:error, Stevedore.Verify.Error.t()}
```

Verifies `subject` against `policy`, returning the signatures that passed.

`policy` is `%{keys: [public_key], require: :any | :all}` (`:any` by default). `opts` must
carry `:signatures` (signature artifact images) or `:transport` (to fetch them).

---

*Consult [api-reference.md](api-reference.md) for complete listing*