Miloslav TrmaÄ January 2023
containers-sigstore-signing-params.yaml - syntax for the sigstore signing parameter file
Sigstore signing parameter files are used to store options that may be required to create sigstore signatures. There is no default location for these files; they are user-managed, and used as inputs to a container image signing operation, e.g. skopeo copy --sign-by-sigstore=param-file.yaml or podman push --sign-by-sigstore=param-file.yaml .
Sigstore signing parameter files use YAML.
Many parameters are optional, but the file must specify enough to create a signature; in particular either a private key, or Fulcio.
• |
privateKeyFile: path |
Create a
signature using a private key at path.
Existence of this field triggers the use of a private
key.
• |
privateKeyPassphraseFile: passphrasePath |
Read the
passphrase required to use privateKeyFile from
passphrasePath.
Optional: if this is not set, the user must provide the
passphrase interactively.
Instead of a static private key, the signing process generates a short-lived key pair and requests a Fulcio server to issue a certificate for that key pair, based on the user authenticating to an OpenID Connect provider.
To specify Fulcio, include a fulcio sub-object with one or more of the following keys. In addition, a Rekor server must be specified as well.
• |
fulcioURL: URL |
Required. URL of the Fulcio server to use.
• |
oidcMode: interactive | deviceGrant | staticToken |
Required. Specifies how to obtain the necessary OpenID Connect credential.
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.
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.
staticToken provides a pre-existing OpenID Connect âID tokenâ, which must have been obtained separately.
• |
oidcIssuerURL: URL |
Required for oidcMode: interactive or deviceGrant. 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.
• |
oidcClientSecret: client secret |
Used for
oidcMode: interactive or deviceGrant to
authenticate the client when contacting the issuer.
Optional.
• |
oidcIDToken: token |
Required for
oidcMode: staticToken.
An OpenID Connect ID token that identifies the user (and
authorizes certificate issuance).
This can be combined with either a private key or Fulcio. 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.
• |
rekorURL: URL |
URL of the Rekor server to use.
Uses the âcommunity infrastructureâ Rekor server.
privateKeyFile:
"/home/user/sigstore/private-key.key"
privateKeyPassphraseFile:
"/mnt/user/sigstore-private-key"
rekorURL: "https://rekor.sigstore.dev"
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.
fulcio:
fulcioURL: "https://fulcio.sigstore.dev"
oidcMode: "interactive"
oidcIssuerURL: "https://oauth2.sigstore.dev/auth"
oidcClientID: "sigstore"
rekorURL: "https://rekor.sigstore.dev"
skopeo(1), podman(1)