CONTAINERS-SI...NG-PARAMS.YAML(5)

💖 containers-sigstore-signing-params.yaml — the sigstore signing parameter file, explained 💖

okay bestie, sit down, grab a boba, because this one is literally the cheat sheet for the syntax of the sigstore signing parameter file 🎀 and it's lowkey important so we're doing it properly.

---

✨ NAME ✨

containers-sigstore-signing-params.yaml — it's the syntax spec for the sigstore signing parameter file. that's the whole vibe. 💅

---

🌸 DESCRIPTION 🌸

So. Sigstore signing parameter files exist to store options that may be required to create sigstore signatures. That's it, that's the job.

Big thing you need to know: there is no default location for these files. None. Not a single one. 🙈 They are user-managed, and they get used as inputs to a container image signing operation. Like, for example:

skopeo copy --sign-by-sigstore=param-file.yaml
podman push --sign-by-sigstore=param-file.yaml

see how it's just a plain input file? yeah. you bring the file, they do the signing. 🫶

---

🦋 FORMAT 🦋

Sigstore signing parameter files use YAML. Periodt.

Many parameters are optional, but — and this is the important part — the file must specify enough to create a signature; in particular, either a private key, or Fulcio. one of the two, bestie. you can't just show up empty-handed. 💀

---

🔑 Signing with Private Keys 🔑

• privateKeyFile: path — creates a signature using a private key at path. And listen: the mere existence of this field triggers the use of a private key. it doesn't ask twice, it doesn't wait, it's main character energy. ✨
• privateKeyPassphraseFile: passphrasePath — reads the passphrase required to use privateKeyFile from passphrasePath.
  • Optional: if this is not set, the user must provide the passphrase interactively. so like, you'll be typing it in yourself, live, no cap. ⌨️

---

🧚 Signing with Fulcio-generated Certificates 🧚

Okay this one's the glow-up. Instead of a static private key, the signing process generates a short-lived key pair and asks a Fulcio server to issue a certificate for that key pair, based on the user authenticating to an OpenID Connect provider. iconic behaviour honestly.

To specify Fulcio, include a fulcio sub-object with one or more of the following keys. And heads up: a Rekor server must be specified as well. don't forget the Rekor part, bestie, it's not optional vibes. 🎀

• fulcioURL: URL — Required. the URL of the Fulcio server to use. 💖
• oidcMode: interactive | deviceGrant | staticToken — Required. this specifies how to obtain the necessary OpenID Connect credential. and here's the tea on each one:
  • interactive — opens a web browser on the same machine, or if that is not possible, asks the user to open a browser manually and to type in the provided code. It requires the user to be able to directly interact with the signing process. so like, you gotta be there. present. in the room. 🫶
  • deviceGrant — uses a device authorization grant flow (RFC 8628). It requires the user to be able to read text printed by the signing process, and to act on it reasonably promptly. so read fast and click faster, okay? ⏰
  • staticToken — provides a pre-existing OpenID Connect “ID token”, which must have been obtained separately. you bring the token, it does the rest. 🔥
• oidcIssuerURL: URL — Required for oidcMode: interactive or deviceGrant. the URL of an OpenID Connect issuer server to authenticate with. 👑
• oidcClientID: client ID — used for oidcMode: interactive or deviceGrant to identify the client when contacting the issuer. Optional but likely to be necessary in those cases. so like, "optional" but also... bring it. 🙈
• oidcClientSecret: client secret — used for oidcMode: interactive or deviceGrant to authenticate the client when contacting the issuer. Optional. that's it, that's the whole sentence. ✨
• oidcIDToken: token — Required for oidcMode: staticToken. An OpenID Connect ID token that identifies the user (and authorizes certificate issuance). it's giving "your whole identity in one string". 💅

---

🌈 Recording the Signature to a Rekor Transparency Server 🌈

This can be combined with either a private key or Fulcio. and here's the nuance: it is, practically speaking, required for Fulcio. It is optional when a static private key is used, but necessary for interoperability with the default configuration of cosign. so like... you can skip it with a static key, but cosign will be like "girl what". 😭

• rekorURL: URL — the URL of the Rekor server to use. that's the one. ⭐

---

🎀 EXAMPLES 🎀

🍓 Sign Using a Pre-existing Private Key 🍓

Uses the ”community infrastructure” Rekor server.

privateKeyFile: "/home/user/sigstore/private-key.key"
privateKeyPassphraseFile: "/mnt/user/sigstore-private-key"
rekorURL: "https://rekor.sigstore.dev"

look at that. clean. three lines. slay. 💅

---

🦋 Sign Using a Fulcio-Issued Certificate 🦋

Uses the ”community infrastructure” Fulcio and Rekor server, and the Dex OIDC issuer which delegates to other major issuers like Google and GitHub.

⚠️ Other configurations will very likely need to also provide an OIDC client secret. so if you're not doing the community infra thing, bestie, go add that secret. 🙈

fulcio:
  fulcioURL: "https://fulcio.sigstore.dev"
  oidcMode: "interactive"
  oidcIssuerURL: "https://oauth2.sigstore.dev/auth"
  oidcClientID: "sigstore"
rekorURL: "https://rekor.sigstore.dev"

nested yaml, community infra, browser pops open, you sign in — it's giving whole experience. 🔥

---

👑 SEE ALSO 👑

• skopeo(1)
• podman(1)

go read those too, iykyk. 🫶

---

and that's the page, bestie!! written by Miloslav Trmač back in January 2023, living in the signing corner of the sigstore manual — mwah, obsessed, no notes. 💖✨🎀🦋🌸💅