CONTAINERS-SIGSTORE-SIGNING-PARAMS.YAML(5)                          parameters

Miloslav Trmac January 2023


NAME
       containers-sigstore-signing-params.yaml - syntax for the sigstore
       signing parameter file



DESCRIPTION
       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 .


FORMAT
       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.


   Signing with Private Keys

              o privateKeyFile: path



       Create a signature using a private key at path.
          Existence of this field triggers the use of a private key.


              o privateKeyPassphraseFile: passphrasePath



       Read the passphrase required to use privateKeyFile from passphrasePath.
          Optional: if this is not set, the user must provide the passphrase
       interactively.


   Signing with Fulcio-generated Certificates
       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.


              o fulcioURL: URL



       Required. URL of the Fulcio server to use.


              o 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.


              o oidcIssuerURL: URL



       Required for oidcMode: interactive or deviceGrant. URL of an OpenID
       Connect issuer server to authenticate with.


              o 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.


              o oidcClientSecret: client secret



       Used for oidcMode: interactive or deviceGrant to authenticate the
       client when contacting the issuer.
         Optional.


              o oidcIDToken: token



       Required for oidcMode: staticToken.
         An OpenID Connect ID token that identifies the user (and authorizes
       certificate issuance).


   Recording the Signature to a Rekor Transparency Server
       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.


              o rekorURL: URL



       URL of the Rekor server to use.



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"


   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.

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



SEE ALSO
       skopeo(1), podman(1)

signing                            sigstore
                                    CONTAINERS-SIGSTORE-SIGNING-PARAMS.YAML(5)