Verify HashiCorp binary downloads

10min
|
Terraform
Packer
Consul
Vault
Boundary
Nomad
Vagrant

Hackers can gain access to your critical systems by tricking you into running an executable that includes malicious code. You can avoid this by verifying that HashiCorp created and signed the binary before you run it.

While you can use the official container images for HashiCorp tools, you may need to build your own container image with additional dependencies to apply Terraform in a CI/CD pipeline, run Vault or Consul on a workload orchestrator, or deploy Boundary in containers. Many container images use Alphine Linux as their base operating system. Since HashiCorp does not include binaries in Alpine Package Keeper, you need to download and verify the binary when you build your custom container image.

In this tutorial, you will download a HashiCorp product binary and verify that no one has tampered with it since HashiCorp created it. In addition, you will create an Alpine Linux container image that includes a verified HashiCorp product binary.

Prerequisites

You will need the following to complete this tutorial.

The curl command line tool, to download files to your local machine.
The gpg command line tool, to import and verify HashiCorp's PGP key.
The shasum command line tool, to verify the checksum of your Terraform archive file. The shasum command is sometimes distributed along with the gpg command, or as part of GNU coreutils.

Optionally, if you want to create an Alpine Linux container image, you will need Docker.

Create a working directory

Make a temporary directory to save your work.

$ mkdir verify-hashicorp-binary

Change into that directory.

$ cd verify-hashicorp-binary

Create a temporary GPG configuration

Create a temporary GPG configuration directory and key to follow this tutorial without affecting your personal GPG configuration. If you would rather use your real GPG configuration to verify the Terraform archive, skip this step.

First, configure gpg to use a temporary directory to hold your configuration and keys instead of the default directory.

$ export GNUPGHOME=./.gnupg

Next create a temporary personal key using a blank passphrase and example email address. You will use this personal key to sign HashiCorp's key in the next step.

$ gpg --quick-generate-key --batch --passphrase "" human@example.com
gpg: directory '/Users/hashicorp/verify-hashicorp-binary/./.gnupg' created
gpg: keybox '/Users/hashicorp/verify-hashicorp-binary/./.gnupg/pubring.kbx' created
gpg: /Users/hashicorp/verify-hashicorp-binary/./.gnupg/trustdb.gpg: trustdb created
gpg: directory '/Users/hashicorp/verify-hashicorp-binary/./.gnupg/openpgp-revocs.d' created
gpg: revocation certificate stored as '/Users/hashicorp/verify-hashicorp-binary/./.gnupg/openpgp-revocs.d/402AFDFB30F35EA92BB8E141AFE161FF374B5F5C.rev'

Warning

Do not use a blank passphrase or example email address for permanent GPG keys. You are doing so in this tutorial so that you can quickly generate an example key that you will not use for real work.

Download and verify HashiCorp's public key

HashiCorp uses a public PGP key to sign certain files, including the checksums for its product archives. You can find HashiCorp's public keys on HashiCorp's security page, and HashiCorp also publishes them to Keybase.

Download HashiCorp's public keys.

$ curl --remote-name https://www.hashicorp.com/.well-known/pgp-key.txt

Import the keys into your GPG keychain.

$ gpg --import pgp-key.txt
gpg: key 34365D9472D7468F: public key "HashiCorp Security (hashicorp.com/security) <security@hashicorp.com>" imported
gpg: Total number processed: 1
gpg:               imported: 1

Now, sign the key with the temporary one you created in the previous step. You can compare this key ID to the one found on HashiCorp's security page. Respond to the confirmation prompt with a y.

$ gpg --sign-key 34365D9472D7468F
gpg: checking the trustdb
gpg: marginals needed: 3  completes needed: 1  trust model: pgp
gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
gpg: next trustdb check due at 2026-02-12
pub  rsa4096/34365D9472D7468F
     created: 2021-04-19  expires: 2026-04-18  usage: SC  
     trust: unknown       validity: unknown
sub  rsa4096/54422F612379BA9A
     created: 2021-04-19  expires: 2026-04-18  usage: E   
sub  rsa4096/B0B441097685B676
     created: 2021-04-19  expired: 2022-04-20  usage: S   
sub  rsa4096/C820C6D5CD27AB87
     created: 2021-04-21  expires: 2026-04-20  usage: S   
[ unknown] (1). HashiCorp Security (hashicorp.com/security) <security@hashicorp.com>

pub  rsa4096/34365D9472D7468F
     created: 2021-04-19  expires: 2026-04-18  usage: SC  
     trust: unknown       validity: unknown
 Primary key fingerprint: C874 011F 0AB4 0511 0D02  1055 3436 5D94 72D7 468F

     HashiCorp Security (hashicorp.com/security) <security@hashicorp.com>

This key is due to expire on 2026-04-18.
Are you sure that you want to sign this key with your
key "human@example.com" (AFE161FF374B5F5C)

Really sign? (y/N) y

Verify PGP key ID and fingerprint

Verify the public key ID and fingerprint with gpg.

$ gpg --fingerprint --list-signatures "HashiCorp Security"
gpg: checking the trustdb
gpg: marginals needed: 3  completes needed: 1  trust model: pgp
gpg: depth: 0  valid:   1  signed:   1  trust: 0-, 0q, 0n, 0m, 0f, 1u
gpg: depth: 1  valid:   1  signed:   0  trust: 1-, 0q, 0n, 0m, 0f, 0u
gpg: next trustdb check due at 2023-05-12
pub   rsa4096 2021-04-19 [SC] [expires: 2026-04-18]
      C874 011F 0AB4 0511 0D02 1055 3436 5D94 72D7 468F
uid           [  full  ] HashiCorp Security (hashicorp.com/security) <security@hashicorp.com>
sig 3        34365D9472D7468F 2021-04-19  HashiCorp Security (hashicorp.com/security) <security@hashicorp.com>
sig          33B7139B683F1365 2021-05-12  human@example.com
sub   rsa4096 2021-04-19 [E] [expires: 2026-04-18]
sig          34365D9472D7468F 2021-04-19  HashiCorp Security (hashicorp.com/security) <security@hashicorp.com>
sub   rsa4096 2021-04-19 [S] [expires: 2022-04-20]
sig          34365D9472D7468F 2021-04-20  HashiCorp Security (hashicorp.com/security) <security@hashicorp.com>
sub   rsa4096 2021-04-21 [S] [expires: 2026-04-20]
sig          34365D9472D7468F 2021-04-21  HashiCorp Security (hashicorp.com/security) <security@hashicorp.com>

Verify that the fingerprint (C874 011F 0AB4 0511 0D02 1055 3436 5D94 72D7 468F) and key ID (34365D9472D7468F) match those shown in the PGP Public Keys section of our security page.

Download HashiCorp product archive and checksums

Download an archive of any HashiCorp tool from HashiCorp's release server. You can follow these steps with any product and product version, but this tutorial uses the MacOS (darwin) release of Terraform v1.7.3 as an example.

First, export the product, version, and operating system and architecture as environment variables.

$ export PRODUCT=terraform && \
  export VERSION=0.15.3 && \
  export OS_ARCH=darwin_amd64

Download the HashiCorp product archive for the product, version, and operating system and architecture you want to use.

$ curl --remote-name https://releases.hashicorp.com/"${PRODUCT}"/"${VERSION}"/"${PRODUCT}"_"${VERSION}"_"${OS_ARCH}".zip

Now, download the SHA 256 checksums that corresponds to the HashiCorp product version you just downloaded. This file contains checksums for the product archive for this version.

$ curl --remote-name https://releases.hashicorp.com/"${PRODUCT}"/"${VERSION}"/"${PRODUCT}"_"${VERSION}"_SHA256SUMS

Also, download the checksum signature file. This file contains a signature of the checksums file, signed with HashiCorp's PGP key.

$ curl --remote-name https://releases.hashicorp.com/"${PRODUCT}"/"${VERSION}"/"${PRODUCT}"_"${VERSION}"_SHA256SUMS.sig

HashiCorp releases these files along with the product binary archives for each version.

Verify checksum, signature files, and product archive

Verify that HashiCorp created the signature file using its private PGP key, and that no one has tampered with it since.

$ gpg --verify ${PRODUCT}_${VERSION}_SHA256SUMS.sig ${PRODUCT}_${VERSION}_SHA256SUMS
gpg: Signature made Wed Feb  7 17:15:42 2024 PST
gpg:                using RSA key 374EC75B485913604A831CC7C820C6D5CD27AB87
gpg: Good signature from "HashiCorp Security (hashicorp.com/security) <security@hashicorp.com>" [full]

The line starting with gpg: Good signature... tells you that the signature matches HashiCorp's public key. Since you signed HashiCorp's key with your personal key earlier in the tutorial, gpg fully trusts HashiCorp's key.

Verify the SHA 256 checksum of the HashiCorp tool archive you downloaded. The SHA256SUMS file contains checksums for each HashiCorp tool release archive file for the indicated version. For this tutorial, you only downloaded the darwin_amd64 (MacOS) release. The shasum command prints out an "OK" message for that file, and "No such file or directory" for the others.

$ shasum --algorithm 256 --check ${PRODUCT}_${VERSION}_SHA256SUMS
terraform_1.7.3_darwin_amd64.zip: OK
shasum: terraform_1.7.3_darwin_arm64.zip: No such file or directory
terraform_1.7.3_darwin_arm64.zip: FAILED open or read
## ...

Now you have verified that no one has tampered with the HashiCorp archive file since HashiCorp created it because its checksum matches the one that HashiCorp provides. You also verified that no one tampered with the checksum file itself since HashiCorp signed it with the appropriate key.

Create Alpine Linux container with HashiCorp tools

You will create a Dockerfile that installs a HashiCorp tool binary in an Alpine Linux container image. You can use this container image to run HashiCorp tools in a containerized environment (for example, in a CI/CD pipeline) or to run HashiCorp tools on a workload orchestrator (for example, Kubernetes).

Create a file named Dockerfile in the verify-hashicorp-binary directory with the following content.

Note

While the example Dockerfile verifies and installs a product's official release binary, it does not include dependencies to run the binary. For example, HashiCorp Nomad requires additional packages such as gcompat. Be sure to install any additional dependencies that your tools require in your container image before running a container for it.

FROM alpine:latest

ARG PRODUCT
ARG VERSION

RUN apk add --update --virtual .deps --no-cache gnupg && \
  cd /tmp && \
  wget https://releases.hashicorp.com/${PRODUCT}/${VERSION}/${PRODUCT}_${VERSION}_linux_amd64.zip && \
  wget https://releases.hashicorp.com/${PRODUCT}/${VERSION}/${PRODUCT}_${VERSION}_SHA256SUMS && \
  wget https://releases.hashicorp.com/${PRODUCT}/${VERSION}/${PRODUCT}_${VERSION}_SHA256SUMS.sig && \
  wget -qO- https://www.hashicorp.com/.well-known/pgp-key.txt | gpg --import && \
  gpg --verify ${PRODUCT}_${VERSION}_SHA256SUMS.sig ${PRODUCT}_${VERSION}_SHA256SUMS && \
  grep ${PRODUCT}_${VERSION}_linux_amd64.zip ${PRODUCT}_${VERSION}_SHA256SUMS | sha256sum -c && \
  unzip /tmp/${PRODUCT}_${VERSION}_linux_amd64.zip -d /tmp && \
  mv /tmp/${PRODUCT} /usr/local/bin/${PRODUCT} && \
  rm -f /tmp/${PRODUCT}_${VERSION}_linux_amd64.zip ${PRODUCT}_${VERSION}_SHA256SUMS ${VERSION}/${PRODUCT}_${VERSION}_SHA256SUMS.sig && \
  apk del .deps

This Dockerfile does the following:

Defines build arguments for the product and version. Build arguments lets you specify the product and version when you build the container image, allowing you to use one Dockerfile for multiple HashiCorp tools and versions.
```
ARG PRODUCT
ARG VERSION
```
Downloads the specified product version. For Alpine Linux, you must use the product binary compiled for Linux AMD64.
```
wget https://releases.hashicorp.com/${PRODUCT}/${VERSION}/${PRODUCT}_${VERSION}_linux_amd64.zip
```

Downloads the release's checksum and signature. Use the signature to verify the checksum and the checksum to validate the archive file.

wget https://releases.hashicorp.com/${PRODUCT}/${VERSION}/${PRODUCT}_${VERSION}_SHA256SUMS && \
wget https://releases.hashicorp.com/${PRODUCT}/${VERSION}/${PRODUCT}_${VERSION}_SHA256SUMS.sig

Verifies HashiCorp's signature on the checksum.

wget -qO- https://www.hashicorp.com/.well-known/pgp-key.txt | gpg --import && \
gpg --verify ${PRODUCT}_${VERSION}_SHA256SUMS.sig ${PRODUCT}_${VERSION}_SHA256SUMS && \
grep ${PRODUCT}_${VERSION}_linux_amd64.zip ${PRODUCT}_${VERSION}_SHA256SUMS | sha256sum

Unzips the product archive and moves the product binary to /usr/local/bin.

unzip /tmp/${PRODUCT}_${VERSION}_linux_amd64.zip -d /tmp && \
mv /tmp/${PRODUCT} /usr/local/bin/${PRODUCT}

Removes the downloaded files and the gnupg package.

rm -f /tmp/${PRODUCT}_${VERSION}_linux_amd64.zip ${PRODUCT}_${VERSION}_SHA256SUMS ${VERSION}/${PRODUCT}_${VERSION}_SHA256SUMS.sig && \
apk del .deps

Build the custom container image. The following example command will create an Alpine Linux base image named terraform-alpine with Terraform version 1.7.3. You can replace the PRODUCT and VERSION arguments with the product and version you want to use.

$ docker build --build-arg PRODUCT=terraform \
  --build-arg VERSION=1.7.3 \
  -t terraform-alpine:test .

Run a container with the new Terraform base image and return the Terraform version on the container.

$ docker run -it terraform-alpine:test terraform version
Terraform v1.7.3
on linux_amd64

Clean your environment

Unset the GNUPGHOME environment variable that you configured earlier.

$ unset GNUPGHOME

Optionally, delete the container image you created.

$ docker image rm -f terraform-alpine:test

Next steps

For more information on topics covered in this tutorial, check out the following resources.

Review HashiCorp's security page for more information about security and HashiCorp products.
Review our official release channels to download and install HashiCorp products on other platforms and architectures. We release official container images for each product in DockerHub under the HashiCorp namespace.

Manage Vault namespace with Terraform

Next Collection

Reliability