secretsmgr handbook
Editor sign-in

Install

The client is a single binary with no runtime to install, and there are three ways to get it. None of them requires you to run any infrastructure, including the first one: the release page belongs to the project, not to your organization. If you are using serverless mode, you never stand anything up.

Download it for your platform from the project's release page, verify the signature, and put it on your PATH:

REL=https://gitlab.example.com/tools/secretsmgr/-/releases/v1.0.0/downloads
curl -LO $REL/secretsmgr-$(uname -s)-$(uname -m)
curl -LO $REL/secretsmgr-$(uname -s)-$(uname -m).sig
cosign verify-blob --key secretsmgr-release.pub \
    --signature secretsmgr-$(uname -s)-$(uname -m).sig \
    secretsmgr-$(uname -s)-$(uname -m)
chmod +x secretsmgr-* && sudo mv secretsmgr-* /usr/local/bin/secretsmgr

Option B. Clone and build

For an air-gapped machine, a platform with no published build, or simply if you would rather not run someone else's binary:

git clone https://gitlab.example.com/tools/secretsmgr.git
cd secretsmgr && make build          # needs a Go toolchain, nothing else
./bin/secretsmgr doctor               # runs fine from where it is

sudo cp bin/secretsmgr /usr/local/bin/   # optional, if you want it on PATH

The binary works from wherever it lands, so ./bin/secretsmgr is a complete installation if you want it to be. Nothing in the tool depends on being at a particular path.

Builds are reproducible, which makes this more than a convenience: build from a tag and you can compare your own binary's checksum against the published one. Matching checksums mean the published binary really was built from the source you just read.

Option C. Package manager

Where a package exists for your platform, use it. go install also works if you already have the toolchain and are relaxed about pinning:

go install gitlab.example.com/tools/secretsmgr/cmd/secretsmgr@v1.0.0
However you get it, check what you got

Verify the signature, or compare a checksum, or build from source you have read. A tampered client is the one attack that no amount of good cryptography inside the tool can defend against, because it is the thing holding your key. It sees your passphrase, it sees every value you decrypt, and it decides what to encrypt to whom.

The server deliberately does not hand out the client

If you are running server mode, you might expect the proxy to host the download for your team. It does not, and it will not. The obvious objection is correct as far as it goes: a tampered client is equally fatal whatever machine served it, and the signature is what protects you rather than the choice of host.

The reason is narrower. This design assumes an attacker may hold root on the proxy and is built to survive it. Serving the client from that same machine would make the assumption we plan for imply the failure of the one we rely on. It also invites "the client checks the server for updates", which is a silent, repeating channel from an assumed-hostile machine into every laptop on your team. Distribute the client the way you distribute other trusted software, independently of the machine it talks to.