Skip to main content

Enable Checksum Verification

About Checksum Verification, please see also.

Create a GitHub Repository​

Let's create a GitHub Repository for this tutorial. You can remove the repository after this tutorial.

Prepare GitHub Access Token​

Please create a classic personal access token and add it to Repository Secrets.

  • name: GH_TOKEN
  • required permissions: contents: write
caution

GitHub Actions' token GITHUB_TOKEN is unavailable.

info

Unfortunately, fine-grained personal access token is unavailable at the moment because it doesn't support GraphQL API. https://github.com/cli/cli/issues/6680

2023-04-27 fine-grained access token supports GraphQL API now.

info

In this time we use a classic personal access token, but we recommend GitHub App or fine-grained access token in terms of security.

Create aqua.yaml​

aqua init
aqua g -i suzuki-shunsuke/tfcmt

Enable Checksum Verification​

By default, checksum verification is disabled. Let's edit aqua.yaml and enable Checksum Verification.

---
checksum:
  enabled: true
registries:
- type: standard
  ref: v4.155.1 # renovate: depName=aquaproj/aqua-registry
packages:
- name: suzuki-shunsuke/tfcmt@v4.2.0

Set up GitHub Actions Workflow​

caution

For CircleCI Users, please use circleci-orb-aqua's update-checksum command instead.

To create and update aqua-checksum.json automatically, let's set up GitHub Actions.

mkdir -p .github/workflows
vi .github/workflows/update-aqua-checksum.yaml
name: update-aqua-checksum
on:
  pull_request:
    paths:
      - aqua.yaml
      - aqua-checksums.json
jobs:
  update-aqua-checksums:
    uses: aquaproj/update-checksum-workflow/.github/workflows/update-checksum.yaml@f367004e7f17e99d30297cd9e89afad30ee1f251 # v1.0.0
    permissions:
      contents: read
    with:
      aqua_version: v2.28.0
      prune: true
    secrets:
      gh_token: ${{secrets.GH_TOKEN}}
      # gh_app_id: ${{secrets.APP_ID}}
      # gh_app_private_key: ${{secrets.APP_PRIVATE_KEY}}

We use update-checksum-action.

Create a pull request​

Commit aqua.yaml and .github/workflows/update-aqua-checksum.yaml.

git checkout -b ci/aqua-checksum
git add aqua.yaml .github/workflows/update-aqua-checksum.yaml
git commit -m "ci: add aqua.yaml and set up workflow"
git push origin ci/aqua-checksum

Create a pull request. Then aqua-checksums.json will be created by GitHub Actions.

image

image

Change a package version​

Let's change version.

sed -i "s/v4.2.0/v4.1.0/" aqua.yaml
-- name: suzuki-shunsuke/tfcmt@v4.2.0
+- name: suzuki-shunsuke/tfcmt@v4.1.0

Push a commit.

git pull origin ci/aqua-checksum
git add aqua.yaml
git commit -m "chore: change tfcmt version"
git push origin "ci/aqua-checksum"

Then aqua-checksums.json is updated automatically.

image

image

See how Checksum Verification prevents tampering​

Let's see how Checksum Verification prevents tampering. It's bothersome to tamper assets actually, so in this time let's simulate the situation by tampering checksum in aqua-checksums.json.

git pull origin ci/aqua-checksum
vi aqua-checksums.json
     {
       "id": "github_release/github.com/suzuki-shunsuke/tfcmt/v4.1.0/tfcmt_linux_amd64.tar.gz",
-      "checksum": "A8E55BEA1A5F94F9515FD9C5C3296D1874461BA1DBD158B3FC0ED6A0DB3B7D91",
+      "checksum": "A8E55BEA1A5F94F9515FD9C5C3296D1874461BA1DBD158B3FC0ED6A0DB3B7D92",
       "algorithm": "sha256"
     },

Add a GitHub Actions job that runs a tampered package.

  test:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    env:
      AQUA_LOG_COLOR: always
      AQUA_REQUIRE_CHECKSUM: "true"
    steps:
      - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0
      - uses: aquaproj/aqua-installer@6ce1f8848ec8e61f14d57bd5d7597057a6dd187c # v3.0.1
        with:
          aqua_version: v2.28.0
        env:
          GITHUB_TOKEN: ${{github.token}}
      - run: tfcmt -v
git add aqua-checksums.json
git commit -m "chore: tamper aqua-checksums.json"
git push origin "ci/aqua-checksum"

Then test job would fail because the checksum is unmatched.

image

time="2023-03-12T06:36:05Z" level=fatal msg="aqua failed" actual_checksum=A8E55BEA1A5F94F9515FD9C5C3296D1874461BA1DBD158B3FC0ED6A0DB3B7D91 aqua_version=2.28.0 env=linux/amd64 error="checksum is invalid" exe_name=tfcmt expected_checksum=A8E55BEA1A5F94F9515FD9C5C3296D1874461BA1DBD158B3FC0ED6A0DB3B7D92 package=suzuki-shunsuke/tfcmt package_version=v4.1.0 program=aqua

💡 Update aqua-checksums.json using autofix.ci​

Instead of update-checksum-action and update-checksum-workflow, you can use aqua upc command and autofix.ci.

About autofix.ci, please see the website. https://autofix.ci/ autofix.ci is free for OSS. autofix.ci has various benefits:

  • You can fix pull requests from fork securely
  • Easy to use. You don't need to take care of how to create and push commits
  • Commits are verified
  • You no longer need to branch processing based on whether the pull request is from a fork or not

We're using autofix.ci in various places.

e.g. https://github.com/aquaproj/aqua-renovate-config/blob/main/.github/workflows/autofix.yaml

This is an example workflow:

name: autofix.ci
on: pull_request
permissions: {}
jobs:
  autofix:
    runs-on: ubuntu-24.04
    permissions: {}
    timeout-minutes: 15
    steps:
      - name: Checkout the repository
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          persist-credentials: false
      - name: Install aqua
        uses: aquaproj/aqua-installer@e2d0136abcf70b7a2f6f505720640750557c4b33 # v3.1.1
        with:
          aqua_version: v2.43.0
      - name: Fix aqua-checksums.json
        run: aqua upc -prune
      - name: Run autofix.ci
        uses: autofix-ci/action@2891949f3779a1cafafae1523058501de3d4e944 # v1.3.1

💡 Update aqua-checksums.json using commit-action​

You can also use suzuki-shunsuke/commit-action.

e.g.

name: Update aqua-checksums.json
on: pull_request
permissions: {}
jobs:
  update-aqua-checksums:
    runs-on: ubuntu-24.04
    permissions: {}
    timeout-minutes: 15
    steps:
      - name: Checkout the repository
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          persist-credentials: false
      - name: Install aqua
        uses: aquaproj/aqua-installer@e2d0136abcf70b7a2f6f505720640750557c4b33 # v3.1.1
        with:
          aqua_version: v2.43.0
      - name: Fix aqua-checksums.json
        run: aqua upc -prune
      - name: Commit and push
        uses: suzuki-shunsuke/commit-action@v0.0.4
        with:
          app_id: ${{secrets.APP_ID}}
          app_private_key: ${{secrets.APP_PRIVATE_KEY}}