Solving common errors with key management

We’ve noticed that many of the errors folks are encountering around key management in Habitat on a Linux build environment are due to confusion between the global key cache in /hab/cache/keys and the user key cache in $HOME/.hab/cache/keys. This is, in part, our fault in versions of Habitat prior to 0.10.2, because we used to force users to sudo everything. Now that we are much clearer about what operations require sudo (and, in Habitat 0.11.0, we hide sudo for you and prompt you for your sudo password if we need it), it’s time to make sure you have your keys set up correctly in order to avoid key not found errors when entering studios or trying to build packages.

Again, this issue mostly afflicts Linux users, because there is no supervisor system for Mac or Windows yet, thus little danger of confusing keys required to start packages on a host (needs public origin key in host’s global key cache) with the keys required to build packages inside the studio (requires private origin key in user’s local key cache). Here are some troubleshooting tips for making sure you have the right keys in the right places.

Throughout this post we will be using yourorigin as the name of your origin. You’ll want to make sure, before you begin, that yourorigin is set as the origin in your $HOME/.hab/etc/cli.toml. If it’s not, you can either edit that file manually, or run hab setup again to fix it. This post also assumes you’re using Habitat 0.11.0, which has the latest features for managing keys.

Entering a studio on the host: Crypto error: No revisions found for yourorigin sig key

  • Check that your origin is set correctly in $HOME/.hab/etc/cli.toml
  • Check that you have a private signing key for yourorigin in $HOME/.hab/cache/keys. It will have the extension .sig.key and the contents of the file should start with SIG-SEC-1
  • If you are migrating from older versions of Habitat, the key you previously generated for that origin might live in the global key cache in /hab/cache/keys. You’ll want to cp or mv that to the local key cache $HOME/.hab/cache/keys and make sure it’s owned by you and not root.

Starting a package: 404 Not Found on downloading public origin key

  • Habitat packages can only be started if they can be verified using the public signing key for that origin.
  • Check that you published the public key for your origin to the depot (hab origin key upload yourorigin).
  • If you don’t want to publish the key, you’ll have to install it manually into the global key cache /hab/cache/keys before starting the package. It has the .pub extension and the first line of the file contains SIG-PUB-1.

If there are other scenarios that I didn’t cover here (i.e. error messages you’ve seen related to keys) please reply to this post and let’s talk about how to overcome them. Or maybe they are bugs that we should dig into more. Either way, thanks for using Habitat!