hanko keeps your Git allowed signers file up to date with signing keys configured on software development platforms like GitHub and GitLab.
Keeps your Git allowed signers file up to date with signing keys configured on software development platforms like GitHub and GitLab.
Usage: hanko [OPTIONS] <COMMAND>
Commands:
update Update the allowed signers file
signer Manage allowed signers
help Print this message or the help of the given subcommand(s)
Options:
-c, --config <PATH> The configuration file [env: HANKO_CONFIG=]
--file <PATH> The allowed signers file [env: HANKO_ALLOWED_SIGNERS=]
-v, --verbose... Use verbose output
-h, --help Print help
-V, --version Print version
cargo install --locked hanko && hanko signer add octocat octocat@github.comThis will install hanko using cargo, create a configuration file containing a single allowed signer and update the allowed signers file accordingly. For other installation methods see installation.
To use hanko, a set of signers to track need to be configured first.
For starters, we'll add the GitHub user octocat with a single principal octocat@github.com.
$ hanko signer add --no-update octocat octocat@github.com
Updated configuration file ~/.config/hanko/config.tomlSince we didn't have a configuration file yet, hanko went ahead and created one for us in the default location at ~/.config/hanko/config.toml, containing our newly added signer.
[[signers]]
name = "octocat"
principals = ["octocat@github.com"]Given that we told hanko not to touch the allowed signers file yet using the --no-update argument, it is left as-is. We'll update it in the next step.
Tip
Should you prefer to create the configuration file by hand, head to Configuration.
Now that we've configured at least one signer, it's time to update the Git allowed signers file with their signing keys.
$ hanko update
Updated allowed signers file ~/.config/git/allowed_signers in 105.315473ms.If an allowed signers file is configured in Git, hanko will write to that file.
Should no allowed signers file be configured within Git, or should you want to specify a different path, the --file runtime option may be used.
Our allowed signers file now contains all signing keys configured by octocat under the principal octocat@github.com.
octocat@github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIN3ZSWa2S+RI/GdKi6WXl4k+FZ8ecAo0H2dtfLRWuhIs
octocat@github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILSK47p5e3KlWAqe1yPkPZUSK3TJVJUzLqKdaPq/ClOa
Any commits made by octocat with the email octocat@github.com and signed by one of their signing keys will no be considered as valid by Git.
cargo install --locked hankoOr using cargo binstall should you prefer not to build yourself.
cargo binstall hankobrew install srv6d/tap/hanko
From scratch docker images are built and attested in CI for every release and are available through the GitHub container registry for this repository.
docker run -it ghcr.io/srv6d/hankoBinaries for most platforms are built and attested in CI and are available for every release.
All release assets are built in CI and utilize Build Provenance Attestation, providing a way to cryptographically verify the build instructions, environment and git revision used in the process.
You can verify a release asset using the gh CLI.
$ gh at verify -R srv6d/hanko hanko-v0.5.1-aarch64-apple-darwin.tar.gz
Loaded digest sha256:32b37a255ce6ff7a961ccd18d3e1e1207814a2f4410042919a48552ddaf254f9 for file://hanko-v0.5.1-aarch64-apple-darwin.tar.gz
Loaded 1 attestation from GitHub API
✓ Verification succeeded!
sha256:32b37a255ce6ff7a961ccd18d3e1e1207814a2f4410042919a48552ddaf254f9 was attested by:
REPO PREDICATE_TYPE WORKFLOW
SRv6d/hanko https://slsa.dev/provenance/v1 .github/workflows/build.yml@refs/tags/v0.5.1Alternatively, using the sigstore cosign CLI, after downloading the appropriate attestation.
$ cosign verify-blob-attestation --bundle SRv6d-hanko-attestation-3372432.sigstore.json \
--new-bundle-format \
--certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
--certificate-identity-regexp="^https://github.com/SRv6d/hanko/.github/workflows/build.yml@refs/tags/v.*$" \
hanko-v0.5.1-aarch64-apple-darwin.tar.gz
Verified OKSigners are the individuals or entities whose signing keys you want to track and include in your allowed signers file so they can be used to verify the authenticity and integrity of commits and tags. When a commit or tag is signed, Git uses the matching principal's public key to verify its authenticity. Each signer can have multiple principals (email addresses) and can be associated with multiple sources.
name: The username of the signer on the given sources.principals: A list of email addresses associated with the signer. Used by Git to associate a commit with an allowed signer.sources(optional): A list of sources exposing the signers public keys. Defaults to GitHub if not specified.
[[signers]]
name = "torvalds"
principals = ["torvalds@linux-foundation.org"]
sources = ["github"]Sources provide the public keys of allowed signers. Currently any source that is API compatible to either GitHub or GitLab is supported. If you are missing a source, don't hesitate to open an issue or give it a try yourself, as they are fairly trivial to implement. To use a source other than github.com or gitlab.com, e.g. a self-hosted GitLab instance, use the configuration options described below.
name: The name of the source.provider: The type of the source. Eithergithuborgitlab.url: The URL of the source's API endpoint.
[[sources]]
name = "acme-corp"
provider = "gitlab"
url = "https://git.acme.corp"Putting it all together, the following example configures two allowed signers, the first one using the default GitHub source, while the second uses a company specific GitLab instance.
[[signers]]
name = "torvalds"
principals = ["torvalds@linux-foundation.org"]
[[signers]]
name = "cwoods"
principals = ["cwoods@acme.corp"]
sources = ["acme-corp"]
[[sources]]
name = "acme-corp"
provider = "gitlab"
url = "https://git.acme.corp"The following cargo features can be used to enable additional functionality.
- detect-allowed-signers (enabled by default): Enables use of the gix-config crate to detect the location of the allowed signers file from Git configuration.
Contributions of all sizes that improve hanko in any way, be it DX/UX, documentation, performance or other are highly appreciated.
To get started, please read the contribution guidelines. Before starting work on a new feature you would like to contribute that may impact simplicity, reliability or performance, please open an issue first.
The source code of this project is licensed under the MIT License. For more information, see LICENSE.