[edit on GitHub]

Prerequisites:

• Get Chef Habitat
• Create a Chef Habitat Builder account
• Generate a personal access token
• Create an origin or join an origin by invitation

When you create an origin, Chef Habitat Builder automatically generates origin keys. Origin key cryptography is asymmetric: it has a public origin key that you can distribute freely, and a private origin key (also called a “signing key”) that you should distribute only to users of the origin. All Chef Habitat Builder users with access to the origin can view the public origin key revisions in the origin key tab (Builder > Origin > Keys) and download the public origin key, but only users with the origin ‘administrator’ or ‘owner’ roles can view or download the private origin key, or change the origin key pair.

Chef Habitat uses origin keys:

• When you build an artifact in your local environment, Chef Habitat signs the artifact with the private origin key
• When you upload an artifact to Chef Habitat Builder or Builder on-prem, Chef Habitat uses the public origin key to verify that the artifact was signed with the private origin key
• When you install any package onto a Chef Habitat Supervisor, Chef Habitat uses the public origin key to verify the package’s integrity before it starts the installation
• When you download an artifact to your local Chef Habitat Studio, Chef Habitat uses the public origin key to verify the artifact’s integrity before it starts the installation

Chef Habitat Builder origin key names follow the format:

<origin>-<datetime>.pub (public key)
<origin>-<datetime>.sig.key (private key, also called a "signing key")

For example, in:

testorigin-20190416223046.pub
testorigin-20190416223046.sig.key

• “testorigin” is the origin’s name
• “20190416223046” is the date and time of the key’s creation, which was 2019-04-16 22:30:46.
• .pub is the file extension for the public key
• .sig.key is the file extension for the private key, which is also called a “signing key”

The Keys Tab

When you create an origin, Chef Habitat Builder automatically generates an origin key pair and saves both keys. To view your origin keys on Chef Habitat Builder, navigate to your origin and select the Keys tab. (Builder > Origins > Keys) You will always be able to view and download public origin keys, but you will only see the private keys for origins in which you are an “administrator” or “owner”.

Download Origin Keys from the Keys Tab

Download your private or public origin key by selecting the download icon from the right end of the key details, under the Actions heading.

Upload Origin Keys from the Keys Tab

You can upload origin keys that you generate on the command line to Chef Habitat Builder by selecting either the Upload a private key or Upload a public key icon, and copy your key into the form that appears.

Managing Origin Keys with the CLI

Run Chef Habitat CLI commands from your local environment or from within the Chef Habitat Studio.

See the CLI documentation for more information on the hab origin key commands.

Find Your Origin Keys

Chef Habitat stores your public and private origin keys at ~/.hab/cache/keys on Linux systems, C:\hab\cache\keys on Windows, and at /hab/cache/keys inside of the Chef Habitat Studio environment.

Find Origin Keys in a Local Environment

On Windows:

Get-ChildItem C:\hab\cache\keys

On Linux or macOS:

ls -la ~/.hab/cache/keys

Find Origin Keys in the Chef Habitat Studio

On Windows:

Get-ChildItem C:\hab\cache\keys

On Linux or macOS:

ls -la /hab/cache/keys

Generate Origin Keys

When you create an origin through the site, Chef Habitat Builder automatically generates an origin key pair.

The Chef Habitat CLI creates origin key pairs through two different commands, for two different uses:

• Use hab setup to generate your first origin key pair as part of setting up the hab CLI
• Use the hab origin key generate <ORIGIN> command to create a key pair for an origin

Create origin keys with the hab command:

hab origin key generate <ORIGIN>

Download Origin Keys

To get your public origin key using the command line, use:

hab origin key download <ORIGIN>

Upload Origin Keys

Creating an origin with the hab origin create command registers the origin on Chef Habitat Builder without creating an origin key pair. The hab origin key generate command creates the key pair and saves them in your local environment, but it does not upload either origin key to Chef Habitat Builder.

• Only “administrators” and “owners” can upload new keys to an origin.
• Builder requires the public origin key to upload artifacts for that origin, so you’ll need to upload it.
• Builder requires the private origin key to enable new artifact builds from packages with plans linked to that origin.

Upload origin keys with the hab command:

hab origin key upload <ORIGIN>

Upload the private origin key:

hab origin key upload --secret <ORIGIN>

Upload both origin keys at the same time:

hab origin key upload  --secfile <PATH_TO_PRIVATE_KEY> --pubfile <PATH_TO_PUBLIC_KEY>

Import Origin Keys

Use hab origin key import to read the key from a standard input stream into Chef Habitat Builder:

hab origin key import <enter or paste key>
hab origin key import <PATH_TO_KEY>
cat <PATH_TO_KEY> | hab origin key import

Troubleshoot Origin Key Import

On a macOS, you may encounter an upload failure. To remediate this failure:

• Check that your HAB_AUTH_TOKEN environment variable is properly set and initialized
• Add your SSL_CERT_FILE to the environment variables in your interactive shell configuration file, such as your .bashrc.

  export SSL_CERT_FILE=/usr/local/etc/openssl/cert.pem

Initialize the setting from the command line with:

 source ~/.bashrc