Nyckelfri signering av commits med gitsign

Signera Git-commits med din IdP-identitet i stället för med en långlivad SSH-nyckel. fremforges nyckelfria signering av commits bygger på byggstenar från Sigstore, men varje komponent körs i T Cloud Public eu-de, rot-CA:n finns i en HSM enligt FIPS 140-2 nivå 3 i Tyskland, och dina signaturer är bundna till den IdP som din fremforge-organisation redan litar på (Microsoft Entra, Okta, Google Workspace, Authentik eller vad som helst som talar OIDC).

Varje signerad commit visas i Forgejo som Verified by sigstore: <your-email> via <your-IdP>. Ingen nyckelserver. Inga överraskningar när något går ut. Inget ”importerade jag den nyckeln på den nya laptopen?”.

Varför (jämfört med SSH-signering)

Båda signeringsmetoderna samexisterar i fremforge; organisationens administratör väljer hur strikt det ska vara (se Organisationspolicyer nedan). Nya utvecklare bör använda gitsign som standard; befintliga konfigurationer med SSH-signering fortsätter att fungera.

Konfiguration (en gång)

1. Installera gitsign

# macOS (Homebrew)
brew install sigstore/tap/gitsign

# Linux (binary)
curl -sLO https://github.com/sigstore/gitsign/releases/latest/download/gitsign-linux-amd64
chmod +x gitsign-linux-amd64 && sudo mv gitsign-linux-amd64 /usr/local/bin/gitsign

# Verify
gitsign --version

2. Konfigurera git

git config --global gpg.x509.program gitsign
git config --global gpg.format x509
git config --global commit.gpgsign true

# Point gitsign at fremforge's private Fulcio + TSA (not the public Sigstore).
git config --global gitsign.fulcio https://sign.frem.sh
git config --global gitsign.timestamp-server-url https://tsa.frem.sh
git config --global gitsign.rekor ""   # explicitly empty — fremforge uses TSA-only, no transparency log
git config --global gitsign.connectorID https://your-idp-issuer-url

Ersätt https://your-idp-issuer-url med den OIDC-utfärdar-URL som din organisation har konfigurerat (se avsnittet Organisationspolicyer → Tillåtna OIDC-utfärdar-URL:er i fremforges administration, eller fråga organisationens administratör).

3. Signera din första commit

cd your-repo
git commit -S -m "First signed commit"

En flik öppnas i webbläsaren, du autentiserar dig hos din IdP (ett tryck om du redan är inloggad), och commiten signeras. Webbläsarens cache håller certifikatet i ungefär 10 minuter, så följande commits i samma session frågar inte igen.

4. Kontrollera att det fungerade

git verify-commit HEAD
# tlog index: <n>
# Good signature from [you@yourorg.com](you@yourorg.com)
# Validated Git signature: true
# Validated Rekor entry: true (or "skipped" — fremforge doesn't run Rekor)

I fremforges webbgränssnitt visar din commit märket Verified by sigstore bredvid commit-hashen.

Föredrar du en GPG-nyckel?

fremforge verifierar också commits som har signerats med din egen GPG-nyckel. Skapa en, tala om för Git att använda den och exportera dess publika halva:

gpg --full-generate-key
gpg --list-secret-keys --keyid-format=long     # the key ID follows "sec   ed25519/"
git config --global user.signingkey <key-id>
git config --global commit.gpgsign true
gpg --armor --export <key-id>

Klistra in blocket som börjar med -----BEGIN PGP PUBLIC KEY BLOCK----- under Inställningar → SSH/GPG-nycklar → Hantera GPG-nycklar → Lägg till nyckel. Nyckelns mejladress måste vara en verifierad adress på ditt konto; dina signerade commits visas då som Verified. Den nyckelfria signeringen ovan gör samma sak utan någon nyckel att ta hand om, och därför är den den rekommenderade vägen. Kombinera inte de två: inställningen gpg.format x509 från steg 2 gäller bara gitsign.

Signering i CI och utan webbläsare

Om du signerar från CI eller från en dator utan webbläsare:

# Get an OIDC token from your IdP (different per IdP — see below)
export SIGSTORE_ID_TOKEN="<bearer-token-from-your-idp>"

# Then sign as usual
git commit -S -m "Signed from CI"

Recept för att hämta token per IdP:

• GitHub Actions → inbyggd behörighet id-token: write
• Microsoft Entra workload identity → az account get-access-token --resource <fulcio-audience>
• Authentik → OAuth-flöde med enhetskod via gitsign utan webbläsare
• Allt annat → alla OIDC-konforma token fungerar, så länge utfärdaren finns på organisationens tillåtelselista

Organisationspolicyer

Två inställningar på /<your-org>/_admin/auth-policy styr hur den nyckelfria signeringen fungerar:

• Tillåtna OIDC-utfärdar-URL:er: måste innehålla din IdP:s utfärdar-URL. Pre-receive-hooken läser certifikatets tillägg OIDCIssuer och avvisar varje commit vars utfärdare inte finns på listan. Tom lista = sigstore-signering avstängd för organisationen.
• Strikt läge: när det är påslaget accepteras bara sigstore-signerade commits på brancher där Require signed commits är påslaget. SSH-signerade commits avvisas. Slå inte på det förrän alla dina utvecklare har gått över.

Felsökning

gitsign: oidc issuer not allowed by Fulcio: din IdP:s utfärdar-URL är rätt, men plattformens Fulcio litar inte på den än. Organisationens administratör: öppna /<slug>/_admin/auth-policy och lägg till utfärdar-URL:en under Tillåtna OIDC-utfärdar-URL:er. fremforge tillämpar ändringen automatiskt (~30 s); inget ärende till operatören behövs.

gitsign: cert expired before push completed: du körde ett långvarigt skript mellan att certifikatet skapades och pushen. Certifikatet gäller i 10 minuter. Kör git commit --amend --no-edit -S för att signera om med ett nytt certifikat innan du pushar.

Märket Verified saknas på en signerad commit: kontrollera /<your-org>/<repo>/commit/<sha>/status; statusen fremforge-sigstore-verified visas som en kontroll bredvid andra CI-kontroller. Om den är ”failure”, klicka för att se orsaken. Om den saknas helt kördes inte pre-receive-hooken: antingen är commiten för gammal (pushad innan policyn slogs på) eller så gick pushen en oväntad väg. Kontakta supporten med commitens SHA.

Forgejos märke ”Verified” säger ”unsigned” men git verify-commit fungerar: Forgejos inbyggda verifierare förstår ännu inte sigstore-signaturer, och därför använder vi märket från commit-statusen i stället. Statusen fremforge-sigstore-verified är den som gäller. (Vi följer gitea#34361 för stöd uppströms.)

Så fungerar det under huven

1. gitsign öppnar inloggningsflödet för OIDC hos din IdP.
2. Din IdP utfärdar en kortlivad ID-token som intygar din identitet.
3. gitsign skickar token till fremforges Fulcio-CA (sign.frem.sh).
4. Fulcio validerar token och skapar ett X.509-certifikat som gäller i 10 minuter, med din mejladress i SAN och IdP:ns utfärdar-URL i tillägget OIDCIssuer. Signeringsnyckeln finns i en DEW-HSM i T Cloud Public (FIPS 140-2 nivå 3, tysk jurisdiktion).
5. gitsign signerar commitens innehåll med certifikatets privata nyckel (som bara finns i webbläsarens lokala minne under certifikatets livslängd).
6. fremforges TSA (tsa.frem.sh) signerar en betrodd tidsstämpel enligt RFC 3161 som intygar att ”certifikatet var giltigt exakt den här sekunden”; det är det som gör att verifieringen fungerar även efter att certifikatet har gått ut.
7. Signaturen, certifikatet och tidsstämpeln bäddas in i commitens gpgsig-header (CMS/PKCS7-format).
8. Du pushar. fremforges pre-receive-hook verifierar certifikatkedjan → vår Fulcio-rot, tidsstämpeln → vår TSA-rot, och OIDC-utfärdaren mot organisationens tillåtelselista.
9. Forgejos API för commit-status registrerar resultatet.

Verifieringen behöver bara Fulcios rotcertifikat och TSA-roten, inga nätverksanrop under verifieringen. Driftstopp i CA:n påverkar inte redan signerade commits, bara nya signeringsförsök.

Verifiera oberoende utanför fremforge

Om du vill att en CI hos tredje part (eller bara din laptop) ska verifiera commits som signerats via fremforge utan att lita på fremforge:

# Fetch fremforge's CA root + TSA root (publicly served, integrity via TLS)
curl -sf https://docs.frem.sh/_pki/fulcio-root.pem > /tmp/fremforge-fulcio.pem
curl -sf https://docs.frem.sh/_pki/tsa-root.pem    > /tmp/fremforge-tsa.pem

# Use cosign to verify a specific commit
cosign verify-blob \
  --certificate-chain /tmp/fremforge-fulcio.pem \
  --timestamp-certificate-chain /tmp/fremforge-tsa.pem \
  --certificate-identity "you@yourorg.com" \
  --certificate-oidc-issuer "https://your-idp-issuer" \
  <commit-bytes>

Samma signaturformat som alla andra signaturer i Sigstores ekosystem: fungerar med cosign verify-blob och resten av OpenSSF:s verktyg för signering av commits och blobbar. (Observera: slsa-verifier verifierar byggproveniens för artefakter, inte signaturer på git-commits, så det är inte tillämpligt här. fremforges byggproveniens är en separat väg som signeras med Ed25519; se SLSA-proveniens.)