Skip to content

binary-verification.md

Latest commit

 

History

History
242 lines (162 loc) · 6.79 KB

binary-verification.md

File metadata and controls

242 lines (162 loc) · 6.79 KB

Binary Verification Guide

← Back to README

This document provides detailed instructions for verifying the integrity and authenticity of Inference Gateway CLI release binaries using SHA256 checksums and Cosign signatures.

Why Verify Binaries?

Verifying release binaries ensures that:

  1. Integrity: The binary hasn't been corrupted during download
  2. Authenticity: The binary was genuinely released by the project maintainers
  3. Supply Chain Security: Protection against supply chain attacks and compromised binaries

All official Inference Gateway CLI releases are signed with Cosign to provide cryptographic verification of authenticity.

Verification Methods

We provide two verification methods:

  1. SHA256 Checksum Verification (Basic): Verifies file integrity
  2. Cosign Signature Verification (Advanced): Verifies authenticity and integrity

SHA256 Checksum Verification

This method verifies that the binary hasn't been corrupted during download.

Step 1: Download the Binary and Checksums

# Download binary (replace with your platform)
curl -L -o infer-darwin-amd64 \
  https://github.com/inference-gateway/cli/releases/latest/download/infer-darwin-amd64

# Download checksums file
curl -L -o checksums.txt \
  https://github.com/inference-gateway/cli/releases/latest/download/checksums.txt

Step 2: Verify the Checksum

# Calculate checksum of downloaded binary
shasum -a 256 infer-darwin-amd64

# Compare with checksums in checksums.txt
grep infer-darwin-amd64 checksums.txt

The output from both commands should match exactly. If they differ, do not use the binary and try downloading again.

Step 3: Install the Binary

Once verified, make the binary executable and install it:

chmod +x infer-darwin-amd64
sudo mv infer-darwin-amd64 /usr/local/bin/infer

Cosign Signature Verification

This advanced method provides cryptographic verification that the binary was actually released by the project maintainers, protecting against supply chain attacks.

Prerequisites

Install Cosign:

# macOS
brew install cosign

# Linux (using release binary)
wget https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64
chmod +x cosign-linux-amd64
sudo mv cosign-linux-amd64 /usr/local/bin/cosign

# Or install via go
go install github.com/sigstore/cosign/v2/cmd/cosign@latest

Step 1: Download All Verification Files

# Download binary (replace with your platform)
curl -L -o infer-darwin-amd64 \
  https://github.com/inference-gateway/cli/releases/latest/download/infer-darwin-amd64

# Download checksums and signature files
curl -L -o checksums.txt \
  https://github.com/inference-gateway/cli/releases/latest/download/checksums.txt
curl -L -o checksums.txt.pem \
  https://github.com/inference-gateway/cli/releases/latest/download/checksums.txt.pem
curl -L -o checksums.txt.sig \
  https://github.com/inference-gateway/cli/releases/latest/download/checksums.txt.sig

Step 2: Verify SHA256 Checksum

First, verify the basic checksum as described in the SHA256 section above:

# Calculate checksum of downloaded binary
shasum -a 256 infer-darwin-amd64

# Compare with checksums in checksums.txt
grep infer-darwin-amd64 checksums.txt

Step 3: Verify Cosign Signature

Now verify that the checksums file was signed by the project's official release workflow:

# Decode base64 encoded certificate
cat checksums.txt.pem | base64 -d > checksums.txt.pem.decoded

# Verify the signature
cosign verify-blob \
  --certificate checksums.txt.pem.decoded \
  --signature checksums.txt.sig \
  --certificate-identity "https://github.com/inference-gateway/cli/.github/workflows/release.yml@refs/heads/main" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  checksums.txt

Successful Output:

If verification succeeds, you should see output similar to:

Verified OK

Failed Verification:

If verification fails, do not use the binary. This could indicate:

  • The binary has been tampered with
  • You downloaded from an unofficial source
  • There was an error in the release process

Step 4: Install the Verified Binary

Once both SHA256 and Cosign verification pass, install the binary:

chmod +x infer-darwin-amd64
sudo mv infer-darwin-amd64 /usr/local/bin/infer

Platform-Specific Binary Names

Replace infer-darwin-amd64 with your platform's binary name:

Platform Architecture Binary Name
macOS Intel (amd64) infer-darwin-amd64
macOS Apple Silicon (arm64) infer-darwin-arm64
Linux amd64 infer-linux-amd64
Linux arm64 infer-linux-arm64

Verifying Specific Versions

To verify a specific release version instead of the latest:

Replace latest in the download URLs with the version tag (e.g., v0.77.0):

# Example for version v0.77.0
curl -L -o infer-darwin-amd64 \
  https://github.com/inference-gateway/cli/releases/download/v0.77.0/infer-darwin-amd64

Troubleshooting

Checksum Mismatch

If the SHA256 checksums don't match:

  1. Retry the download: The download may have been interrupted or corrupted
  2. Check your network: Ensure you're not behind a proxy that modifies downloads
  3. Verify the source: Ensure you're downloading from the official GitHub releases page

Cosign Verification Fails

If Cosign verification fails:

  1. Check Cosign version: Ensure you have a recent version of Cosign installed
  2. Verify certificate identity: Ensure the --certificate-identity matches exactly
  3. Check file permissions: Ensure all downloaded files are readable
  4. Re-download files: The signature files may have been corrupted

Certificate Decoding Issues

If base64 -d fails:

# Try alternative decoding methods
base64 --decode checksums.txt.pem > checksums.txt.pem.decoded

# Or use openssl
openssl base64 -d -in checksums.txt.pem -out checksums.txt.pem.decoded

Security Best Practices

  1. Always verify binaries before installation, especially in production environments
  2. Use HTTPS when downloading to prevent man-in-the-middle attacks
  3. Pin specific versions in automated deployments rather than using latest
  4. Store verification scripts in version control for reproducible builds
  5. Verify checksums AND signatures for maximum security (not just one method)

Additional Resources

← Back to README