clan-core/docs/secrets-management.md

Managing Secrets with Clan

Clan enables encryption of secrets within a Clan flake, ensuring secure sharing among users. This documentation will guide you through managing secrets with the Clan CLI, which utilizes the sops format and integrates with sops-nix on NixOS machines.

1. Generating Keys and Creating Secrets

To begin, generate a key pair:

$ clan secrets key generate

Output:

Public key: age1wkth7uhpkl555g40t8hjsysr20drq286netu8zptw50lmqz7j95sw2t3l7
Generated age private key at '/home/joerg/.config/sops/age/keys.txt' for your user.
Generated age private key at '/home/joerg/.config/sops/age/keys.txt' for your user. Please back it up on a secure location or you will lose access to your secrets.
Also add your age public key to the repository with 'clan secrets users add youruser age1wkth7uhpkl555g40t8hjsysr20drq286netu8zptw50lmqz7j95sw2t3l7' (replace you
user with your user name)

⚠️ Important: Backup the generated private key securely, or risk losing access to your secrets.

Next, add your public key to the Clan flake repository:

$ clan secrets users add <your_username> <your_public_key>

Doing so creates this structure in your Clan flake:

sops/
└── users/
    └── <your_username>/
        └── key.json

Now, to set your first secret:

$ clan secrets set mysecret
Paste your secret:

Note: As you type your secret, keypresses won't be displayed. Press Enter to save the secret.

Retrieve the stored secret:

$ clan secrets get mysecret

And list all secrets like this:

$ clan secrets list

Secrets in the repository follow this structure:

sops/
├── secrets/
│   └── <secret_name>/
│       ├── secret
│       └── users/
│           └── <your_username>/

The content of the secret is stored encrypted inside the secret file under mysecret. By default, secrets are encrypted with your key to ensure readability.

2. Adding Machine Keys

New machines in Clan come with age keys stored in ./sops/machines/<machine_name>. To list these machines:

$ clan secrets machines list

For existing machines, add their keys:

$ clan secrets machine add <machine_name> <age_key>

To fetch an age key from an SSH host key:

$ ssh-keyscan <domain_name> | nix shell nixpkgs#ssh-to-age -c ssh-to-age

3. Assigning Access

By default, secrets are encrypted for your key. To specify which users and machines can access a secret:

$ clan secrets set --machine <machine1> --machine <machine2> --user <user1> --user <user2> <secret_name>

You can add machines/users to existing secrets without modifying the secret:

$ clan secrets machines add-secret <machine_name> <secret_name>

4. Utilizing Groups

For convenience, Clan CLI allows group creation to simplify access management. Here's how:

1. Creating Groups:

   Assign users to a new group, e.g., admins:

   $ clan secrets groups add admins <username>
   

2. Listing Groups:

   $ clan secrets groups list
   

3. Assigning Secrets to Groups:

   $ clan secrets groups add-secret <group_name> <secret_name>