Signatures

Why Sign?

Problem: A lockfile is just a JSON file. Anyone can create or modify it.

Solution: Cryptographic signatures bind the lockfile to an identity (key or OIDC principal).

Outcome: Downstream consumers can verify: "This lockfile was approved by [identity]."

Ed25519 Mode (Key-Based): Traditional Team Signing

Workflow:

1. Generate Keys:

   mcptrust keygen
   # Creates: private.key, public.key

2. Sign:

   mcptrust sign --key private.key
   # Creates: mcp-lock.json.sig

3. Verify:

   mcptrust verify --key public.key
   # Exit 0 = valid, Exit 1 = invalid

Key Management:

• private.key: Keep SECRET. Store in a vault, HSM, or GitHub secret.
• public.key: Distribute freely. Commit to repo, publish on website.

Use Cases: Offline environments, team-controlled signing, air-gapped deployments.

Sigstore Mode (Keyless): CI/CD Automation with OIDC

What is Sigstore?: A Linux Foundation project for keyless signing using OIDC identities.

Workflow (GitHub Actions):

1. Workflow requests OIDC token:

   permissions:
     id-token: write

2. Sign with identity:

   mcptrust sign --sigstore

3. Verify with identity constraints:

   mcptrust verify \
     --issuer https://token.actions.githubusercontent.com \
     --identity "https://github.com/org/repo/.github/workflows/sign.yml@refs/heads/main"

Transparency Log: All signatures are recorded in Rekor (public, immutable).

Use Cases: Automated pipelines, GitHub Actions, GitLab CI, no secrets to rotate.

Signature File Format

• v1/v2 (Ed25519): Hex-encoded 64-byte signature.
• v3 (Sigstore): JSON envelope containing a sigstore_bundle (base64) and the v2 signature. This is not a new hashing algorithm, but a packaging format that binds the signature to a Sigstore identity.

Example v3 header:

{"version":"v3","type":"sigstore","canon_version":"v1"}

Choosing a Mode