Securing Supervisor Networks

By default, a Supervisor runs unsecured. It communicates with other Supervisors in cleartext, and it allows any user to apply new configuration without authentication. While this is beneficial for demonstrating the concepts of Chef Habitat, you should provide external security on production deployments of Chef Habitat Supervisor networks.

Use following security measures in a Supervisor network:

Wire encryption of inter-Supervisor traffic
Trust relationships between supervisors and users

Wire Encryption

Supervisors running in a ring can be configured to encrypt all traffic between them. This is accomplished by generating a ring key, which is a symmetric shared secret placed into the Supervisor environment prior to starting it.

Generating a Ring Key

Generate a ring key using the hab command-line tool. This can be done on your workstation. The generated key has the .sym.key extension, indicating that it’s a symmetric pre-shared key, and is stored in the $HOME/.hab/cache/keys directory.
```
hab ring key generate <RING>
```
Copy the key file to the environment where the Supervisor will run, into the /hab/cache/keys directory. Ensure that it has the appropriate permissions so only the Supervisor can read it.
Start the Supervisor with the -r or --ring parameter, specifying the name of the ring key to use.
```
hab sup run --ring <RING>
hab svc load <ORIGIN>/<NAME>
```
The Supervisor becomes part of the named ring <RING> and uses the key for network encryption. Other supervisors that now attempt to connect to it without presenting the correct ring key will be rejected.
It’s also possible to set the environment variable HAB_RING_KEY to the contents of the ring key; for example:
```
env HAB_RING_KEY=$(cat /hab/cache/keys/ring-key-file) hab sup run
hab svc load <ORIGIN>/<NAME>
```

Service Group Encryption

Supervisors in a service group can be configured to require key-based authorization prior to allowing configuration changes. In this scenario, the Supervisor in a named service group starts up with a key for that group bound to an organization. This allows for multiple service groups with the same name in different organizations.

As explained in the security overview, this process also requires the generation of a user key for every user making configuration updates to the Supervisor network.

Generating Service Group Keys

Generate a service group key using the hab command-line tool. This can be done on your workstation. Because asymmetric encryption is being used, two files will be generated: a file with a .box.key extension, which is the service group’s private key, and a file with a .pub extension, which is the service group’s public key.
```
hab svc key generate service-group-name.example <ORG>
```
This generated a service group key for the service group service-group-name.example in the organization <ORG>. Copy the .box.key private key to the environment where the Supervisor will run into the /hab/cache/keys directory. Ensure that it has the appropriate permissions so that only the Supervisor can read it.
Start the Supervisor, specifying both the service group and organization that it belongs to:
```
hab sup run --org <ORG> --group service-group-name.example
hab svc load <ORIGIN>/<NAME>
```
Only users whose public keys that the Supervisor already has in its cache will be allowed to reconfigure this service group. If you need to generate a user key pair, see the next section.

Generating User Keys

The user key is used to encrypt configuration data targeted for a particular service group.

Generate a user key using the hab command-line tool. This can be done on your workstation. Because asymmetric encryption is being used, two files will be generated: a file with a .box.key extension, which is the user’s private key, and a file with a .pub extension, which is the user’s public key.
Distribute the user’s public key to any Supervisor that needs it, into the /hab/cache/keys directory. The user will be able to reconfigure that Supervisor, provided they encrypted the configuration update using the service group’s public key.

Apply Configuration Changes

The hab config apply and hab file upload commands will work as usual when user/service group trust relationships are set up in this way.

If a running Supervisor can’t decrypt a secret due to a missing key, it will retry with exponential backoff starting with a one-second interval. This allows an administrator to provide the Supervisor with the key to resume normal operations, without taking down the Supervisor.

Identifying Key Types

To aid the user in the visual identification of the many varieties of keys in use by Chef Habitat, a key itself is in cleartext and contains a header on the first line indicating what its key type. The file extension and, in some situations, the format of the file name, provide additional guidance to the user in identifying the type of key.

YYYYMMDDRRRRRR denotes the creation time and release identifier of that key.

Key Type	Header	Filename Format
Private origin signing key	SIG-SEC-1	originname-YYYYMMDDRRRRRR.sig.key
Public origin signing key	SIG-PUB-1	originname-YYYYMMDDRRRRRR.pub.key
Ring wire encryption key	SYM-SEC-1	ringname-YYYYMMDDRRRRRR.sym.key
Private service group key	BOX-SEC-1	service-group.env@org-YYYYMMDDRRRRRR.box.key
Public service group key	BOX-PUB-1	service-group.env@org-YYYYMMDDRRRRRR.pub
Private user key	BOX-SEC-1	username-YYYYMMDDRRRRRR.box.key
Public user key	BOX-PUB-1	username-YYYYMMDDRRRRRR.pub

Keys that contain SEC in their header should be guarded carefully. Keys that contain PUB in their header can be distributed freely with no risk of information compromise.