Keychain

Summary

The keychain contains secret information necessary for Cosnim’s operation. Cosnim needs at least a default encryption key block in a keychain to encrypt the capsules’ contents and public names. The keychain may also contain:

• One or more encryption key blocks.

• Cloud access credentials.

• A private key to sign data and to authenticate to relays and gateways.

• Public keys for relay/gateway client authorization.

A keychain is created with the command:

cosnim create keychain

By default, this creates a keychain at the location configured for the continuum. See the command reference for details.

Keychain File

The keychain is a single flat file that you can copy and move as you wish. The contents of a keychain shouldn’t change much after initial creation and population. You should keep a copy of your keychain in a safe location. You cannot access a continuum without a keychain and at least one encryption key block.

Passphrase

A keychain can be protected with a passphrase. In this case, the entire keychain is fully encrypted with powerful algorithms to prevent unauthorized access. This is the default when creating a keychain. You may add, change and remove the passphrase with the cosnim update keychain command.

When a keychain is protected with a passphrase, you’ll be prompted for the passphrase each time you run a Cosnim command that needs it. To avoid this inconvenience, you may take a copy of your keychain, remove the passphrase, and store this copy in a very secure location on your machine to be used when running Cosnim commands.

Sharing a Continuum

When sharing a continuum with multiple instances or users, you need each instance to have a copy of the default encryption key block and, if applicable, the cloud access credentials. You can do this in two ways:

1. Create and clone a master keychain

   With this method, you first create a master keychain with a default encryption block and cloud access credentials that are needed to run individual Cosnim instances.

   You then copy this keychain file and then customize it for the end instance or user. That usually involves creating a private signature key with the cosnim generate key command; a private key is needed only if you use signature cascades or are connecting to secure relays or gateways in the continuum. Otherwise, a copy of the master keychain is all that is needed.

2. Export and import keys

   The second method involves using cosnim export key and cosnim import key commands to copy keys from one keychain to another. A normal procedure would be:

   1. Create a destination keychain for the user:

      cosnim create keychain --no-passphrase
      

   2. Copy and replace the default encryption key block. You can pipe the export’s output to the import command to securely copy the key:

      cosnim export key --keychain master.keychain --key default | cosnim import key --keychain user.keychain --key default --replace
      

   3. If needed, create a private key for the user:

      cosnim generate key --keychain user.keychain --key user.name@company.com --type eddsa-255
      

   4. Protect the keychain with a passphrase (if desired):

      cosnim update keychain --keychain user.keychain --prompt-new-passphrase