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

Sign an image so its authenticity can later be verified by `Stevedore.Verify`.

`sigstore/3` produces a **cosign-compatible** signature artifact: a small OCI image whose single
layer is the [simple-signing payload](`Stevedore.Sign.Sigstore`) and whose layer annotation
carries the base64 signature (`dev.cosignproject.cosign/signature`). The artifact's `subject`
points at the signed image (OCI 1.1 referrer) and its `tag` is cosign's `sha256-<hex>.sig`. Push
it with `Stevedore.copy/3` or attach it with `Stevedore.Referrers.attach/4`.

`simple/3` is a Stevedore-native detached signature over the manifest digest (ECDSA). It is
*not* the containers/image GPG "simple signing" wire format — GPG interop is a future opt-in.

All crypto is native (`:public_key`); nothing shells out to `cosign`/`gpg`/`openssl`.

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

# `payload_media_type`

```elixir
@spec payload_media_type() :: String.t()
```

The media type of the cosign simple-signing payload layer.

# `signature_annotation`

```elixir
@spec signature_annotation() :: String.t()
```

The layer-annotation key cosign stores its signature under.

# `sigstore`

```elixir
@spec sigstore(
  Stevedore.Image.t() | Stevedore.Digest.t(),
  Stevedore.Sign.Sigstore.key(),
  keyword()
) ::
  {:ok, Stevedore.Image.t()} | {:error, Stevedore.Sign.Error.t()}
```

Signs `subject` (an image or a manifest digest) with `key`, returning the cosign signature
artifact as a `t:Stevedore.Image.t/0` ready to copy or attach.

`opts`: `:reference` (docker-reference in the payload), `:annotations` (payload optional
section). For a bare digest, `:subject_size`/`:subject_media_type` describe the subject.

# `simple`

```elixir
@spec simple(
  Stevedore.Image.t() | Stevedore.Digest.t(),
  Stevedore.Sign.Sigstore.key(),
  keyword()
) ::
  {:ok, binary()} | {:error, Stevedore.Sign.Error.t()}
```

Produces a native detached ECDSA signature (DER bytes) over `subject`'s manifest digest.

---

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