[Discussion] Determine interface for SLSA attestation & signing API in glgo

ON HOLD: The new proposal is to add the Cosign binary to GitLab distributions (#556801 (closed) and #556802 (closed)). We keep that issue in case we face significant challenges while pursing that new proposal. If things go well, we'll close that issue, and mark it as won't do/no longer relevant.

Problem to solve

As part of Phase 3: Signing Out of Build Environment Using... (&15862 - closed) we've proposed to add and API for SLSA attestation generation and signing to glgo. The purpose of the issue is to discuss the implementation plan and API interface to be built into glgo.

Proposal

Based on some initial research and prototyping, the current proposal is to implement the API by importing the cosign CLI into glgo and building API interfaces around the relevant commands needed in the generation and signing process.

More specifically, the proposal is to wrap cli.AttestBlobCommand which supports cosign's attest_blob command. That command is the one being called by the verifier template of the SLSA CI/CD component. See attest_blob documentation.

Since cosign is the canonical Sigstore client, this approach will make it possible to support necessary cosign features without duplicating effort. It will also make it possible to stay up to date with fixes and improvements to cosign when they become available.

The proposed API interface is:

POST /slsa/attestation

Creates and returns a signed Sigstore bundle for the provided artifact.

Parameters

Parameter Type Required Description
provenance string Yes The provenance file
artifact_hash string Yes SHA256 hash of the artifact file
oidc_issuer string Yes OIDC provider to be used to issue ID token
identity_token string Yes Identity token to use for certificate from fulcio
fulcio_url string No URL of sigstore PKI server (default: "https://fulcio.sigstore.dev")
rekor_url string No URL of rekor STL server (default: "https://rekor.sigstore.dev")

Request Example

{
  "provenance": "...",
  "artifact_hash": "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
  "oidc_issuer": "https://gitlab.com",
  "identity_token": "eyJhbGciOiJSUzI1NiIs...",
}

Response Example

{
  "mediaType": "application/vnd.dev.sigstore.bundle.v0.3+json",
  "verificationMaterial": { ... },
  "dsseEnvelope": { ... }
}

Other parameters that could be supported in the future

Parameter Type Description
certificate string Path to the X.509 certificate in PEM format to include in the OCI Signature
certificate-chain string Path to a list of CA X.509 certificates in PEM format which will be needed when building the certificate chain for the signing certificate. Must start with the parent intermediate CA certificate of the signing certificate and end with the root certificate. Included in the OCI Signature
key string Path to the private key file, KMS URI or Kubernetes Secret
oidc-client-id string OIDC client ID for application (default "sigstore")
oidc-client-secret-file string Path to file containing OIDC client secret for application
oidc-disable-ambient-providers boolean Disable ambient OIDC providers. When true, ambient credentials will not be read
oidc-redirect-url string OIDC redirect URL (Optional). The default oidc-redirect-url is 'http://localhost:0/auth/callback'
rekor-entry-type string Specifies the type to be used for a rekor entry upload (dsse|intoto) (default "dsse")
rfc3161-timestamp-bundle string Path to an RFC 3161 timestamp bundle FILE
sk boolean Whether to use a hardware security key
slot string Security key slot to use for generated key (default: signature) (authentication|signature|card-authentication|key-management)
timestamp-client-cacert string Path to the X.509 CA certificate file in PEM format to be used for the connection to the TSA Server
timestamp-client-cert string Path to the X.509 certificate file in PEM format to be used for the connection to the TSA Server
timestamp-client-key string Path to the X.509 private key file in PEM format to be used, together with the 'timestamp-client-cert' value, for the connection to the TSA Server
timestamp-server-name string SAN name to use as the 'ServerName' tls.Config field to verify the mTLS connection to the TSA Server
timestamp-server-url string URL to the Timestamp RFC3161 server, default none. Must be the path to the API to request timestamp responses, e.g. https://freetsa.org/tsr
tlog-upload boolean Whether or not to upload to the tlog (default true)
type string Specify a predicate type (slsaprovenance|slsaprovenance02|slsaprovenance1|link|spdx|spdxjson|cyclonedx|vuln|openvex|custom) or an URI (default "custom")
Edited by Fabien Catteau