325 lines
7.0 KiB
Markdown
325 lines
7.0 KiB
Markdown
## Secrets (CLI Reference)
|
|
|
|
#### Adding Secrets (set)
|
|
|
|
```bash
|
|
clan secrets set mysecret
|
|
> Paste your secret:
|
|
```
|
|
|
|
!!! note
|
|
As you type your secret won't be displayed. Press Enter to save the secret.
|
|
|
|
#### List all Secrets (list)
|
|
|
|
```bash
|
|
clan secrets list
|
|
```
|
|
|
|
#### Assigning Access (set)
|
|
|
|
By default, secrets are encrypted for your key. To specify which users and machines can access a secret:
|
|
|
|
```bash
|
|
clan secrets set --machine <machine1> --machine <machine2> --user <user1> --user <user2> <secret_name>
|
|
```
|
|
|
|
#### Displaying Secrets (get)
|
|
|
|
```bash
|
|
clan secrets get mysecret
|
|
```
|
|
|
|
#### Rename
|
|
|
|
TODO
|
|
|
|
#### Remove
|
|
|
|
TODO
|
|
|
|
#### import-sops
|
|
|
|
TODO
|
|
|
|
### Users (Reference)
|
|
|
|
Learn how to manage users and allowing access to existing secrets.
|
|
|
|
#### list user
|
|
|
|
Lists all added users
|
|
|
|
```bash
|
|
clan secrets user list
|
|
```
|
|
|
|
``` {.console, title="Example output", .no-copy}
|
|
jon
|
|
sara
|
|
```
|
|
|
|
!!! Question "Who can execute this command?"
|
|
Everyone - completely public.
|
|
|
|
#### add user
|
|
|
|
add a user
|
|
|
|
```bash
|
|
clan secrets users add {username} {public-key}
|
|
```
|
|
|
|
!!! Note
|
|
Changes can be trusted by maintainer review in version control.
|
|
|
|
#### get user
|
|
|
|
get a user public key
|
|
|
|
```bash
|
|
clan secrets users get {username}
|
|
```
|
|
|
|
``` {.console, title="Example output", .no-copy}
|
|
age1zk8uzrte55wkg9lkqxu5x6twsj2ja4lehegks0cw4mkg6jv37d9qsjpt44
|
|
```
|
|
|
|
#### remove user
|
|
|
|
remove a user
|
|
|
|
```bash
|
|
clan secrets users remove {username}
|
|
```
|
|
|
|
!!! Note
|
|
Changes can be trusted by maintainer review in version control.
|
|
|
|
#### add-secret user
|
|
|
|
Grants the user (`username`) access to the secret (`secret_name`)
|
|
|
|
```bash
|
|
clan secrets users add-secret {username} {secret_name}
|
|
```
|
|
|
|
!!! Note
|
|
Requires the executor of the command to have access to the secret (`secret_name`).
|
|
|
|
#### remove-secret user
|
|
|
|
remove the user (`username`) from accessing the secret (`secret_name`)
|
|
|
|
!!! Danger "Make sure at least one person has access."
|
|
It might still be possible for the machine to access the secret. (See [machines](#machines))
|
|
|
|
We highly recommend to use version control such as `git` which allows you to rollback secrets in case anything gets messed up.
|
|
|
|
```bash
|
|
clan secrets users remove-secret {username} {secret_name}
|
|
```
|
|
|
|
!!! Question "Who can execute this command?"
|
|
Requires the executor of the command to have access to the secret (`secret_name`).
|
|
|
|
### Machines (Reference)
|
|
|
|
- [list](): list machines
|
|
- [add](): add a machine
|
|
- [get](): get a machine public key
|
|
- [remove](): remove a machine
|
|
- [add-secret](): allow a machine to access a secret
|
|
- [remove-secret](): remove a machine's access to a secret
|
|
|
|
#### List machine
|
|
|
|
New machines in Clan come with age keys stored in `./sops/machines/<machine_name>`. To list these machines:
|
|
|
|
```bash
|
|
clan secrets machines list
|
|
```
|
|
|
|
#### Add machine
|
|
|
|
For clan machines the machine key is generated automatically on demand if none exists.
|
|
|
|
```bash
|
|
clan secrets machines add <machine_name> <age_key>
|
|
```
|
|
|
|
If you already have a device key and want to add it manually, see: [How to obtain a remote key](#obtain-remote-keys-manually)
|
|
|
|
#### get machine
|
|
|
|
TODO
|
|
|
|
#### remove machine
|
|
|
|
TODO
|
|
|
|
#### add-secret machine
|
|
|
|
TODO
|
|
|
|
#### remove-secret machine
|
|
|
|
TODO
|
|
|
|
### Groups (Reference)
|
|
|
|
The Clan-CLI makes it easy to manage access by allowing you to create groups.
|
|
|
|
- [list](): list groups
|
|
- [add-user](): add a user to group
|
|
- [remove-user](): remove a user from group
|
|
- [add-machine](): add a machine to group
|
|
- [remove-machine](): remove a machine from group
|
|
- [add-secret](): allow a user to access a secret
|
|
- [remove-secret](): remove a group's access to a secret
|
|
|
|
#### List Groups
|
|
|
|
```bash
|
|
clan secrets groups list
|
|
```
|
|
|
|
#### add-user
|
|
|
|
Assign users to a new group, e.g., `admins`:
|
|
|
|
```bash
|
|
clan secrets groups add-user admins <username>
|
|
```
|
|
|
|
!!! info
|
|
The group is created if no such group existed before.
|
|
|
|
The user must exist in beforehand (See: [users](#users-reference))
|
|
|
|
```{.console, .no-copy}
|
|
.
|
|
├── flake.nix
|
|
. ...
|
|
└── sops
|
|
├── groups
|
|
│ └── admins
|
|
│ └── users
|
|
│ └── <username> -> ../../../users/<username>
|
|
```
|
|
|
|
#### remove-user
|
|
|
|
TODO
|
|
|
|
#### add-machine
|
|
|
|
TODO
|
|
|
|
#### remove-machine
|
|
|
|
TODO
|
|
|
|
#### add-secret
|
|
|
|
```bash
|
|
clan secrets groups add-secret <group_name> <secret_name>
|
|
```
|
|
|
|
#### remove-secret
|
|
|
|
TODO
|
|
|
|
### Key (Reference)
|
|
|
|
- [generate]() generate age key
|
|
- [show]() show age public key
|
|
- [update]() re-encrypt all secrets with current keys (useful when changing keys)
|
|
|
|
#### generate
|
|
|
|
TODO
|
|
|
|
#### show
|
|
|
|
TODO
|
|
|
|
#### update
|
|
|
|
TODO
|
|
|
|
## Further
|
|
|
|
Secrets in the repository follow this structure:
|
|
|
|
```{.console, .no-copy}
|
|
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.
|
|
|
|
### Obtain remote keys manually
|
|
|
|
To fetch a **SSH host key** from a preinstalled system:
|
|
|
|
```bash
|
|
ssh-keyscan <domain_name> | nix shell nixpkgs#ssh-to-age -c ssh-to-age
|
|
```
|
|
|
|
!!! Success
|
|
This command converts the SSH key into an age key on the fly. Since this is the format used by the clan secrets backend.
|
|
|
|
Once added the **SSH host key** enables seamless integration of existing machines with clan.
|
|
|
|
Then add the key by executing:
|
|
|
|
```bash
|
|
clan secrets machines add <machine_name> <age_key>
|
|
```
|
|
|
|
See also: [Machine reference](#machines-reference)
|
|
|
|
### NixOS integration
|
|
|
|
A NixOS machine will automatically import all secrets that are encrypted for the
|
|
current machine. At runtime it will use the host key to decrypt all secrets into
|
|
an in-memory, non-persistent filesystem using [sops-nix](https://github.com/Mic92/sops-nix).
|
|
In your nixos configuration you can get a path to secrets like this `config.sops.secrets.<name>.path`. For example:
|
|
|
|
```nix
|
|
{ config, ...}: {
|
|
sops.secrets.my-password.neededForUsers = true;
|
|
|
|
users.users.mic92 = {
|
|
isNormalUser = true;
|
|
passwordFile = config.sops.secrets.my-password.path;
|
|
};
|
|
}
|
|
```
|
|
|
|
See the [readme](https://github.com/Mic92/sops-nix) of sops-nix for more
|
|
examples.
|
|
|
|
### Migration: Importing existing sops-based keys / sops-nix
|
|
|
|
`clan secrets` stores each secret in a single file, whereas [sops](https://github.com/Mic92/sops-nix) commonly allows to put all secrets in a yaml or json document.
|
|
|
|
If you already happened to use sops-nix, you can migrate by using the `clan secrets import-sops` command by importing these files:
|
|
|
|
```bash
|
|
% clan secrets import-sops --prefix matchbox- --group admins --machine matchbox nixos/matchbox/secrets/secrets.yaml
|
|
```
|
|
|
|
This will create secrets for each secret found in `nixos/matchbox/secrets/secrets.yaml` in a `./sops` folder of your repository.
|
|
Each member of the group `admins` in this case will be able to decrypt the secrets with their respective key.
|
|
|
|
Since our clan secret module will auto-import secrets that are encrypted for a particular nixos machine,
|
|
you can now remove `sops.secrets.<secrets> = { };` unless you need to specify more options for the secret like owner/group of the secret file.
|