DavHau
f1f040397d
All checks were successful
buildbot/nix-build .#checks.aarch64-darwin.nixos-test_install_machine Build done.
buildbot/nix-build .#checks.aarch64-darwin.nixos-iso-installer Build done.
buildbot/nix-build .#checks.aarch64-darwin.nixos-flash-installer Build done.
buildbot/nix-build .#checks.aarch64-linux.nixos-test_install_machine Build done.
buildbot/nix-build .#checks.aarch64-linux.nixos-flash-installer Build done.
buildbot/nix-build .#checks.x86_64-linux.check-for-breakpoints Build done.
buildbot/nix-build .#checks.x86_64-linux.clan-dep-age Build done.
buildbot/nix-build .#checks.x86_64-linux.clan-dep-bash Build done.
buildbot/nix-build .#checks.aarch64-darwin.nixos-test-backup Build done.
buildbot/nix-build .#checks.x86_64-linux.clan-dep-e2fsprogs Build done.
buildbot/nix-build .#checks.x86_64-linux.devShell-docs Build done.
buildbot/nix-build .#checks.x86_64-linux.package-module-docs Build done.
buildbot/nix-build .#checks.x86_64-linux.clan-dep-fakeroot Build done.
buildbot/nix-build .#checks.x86_64-linux.clan-dep-git Build done.
buildbot/nix-build .#checks.x86_64-linux.clan-dep-nix Build done.
buildbot/nix-build .#checks.x86_64-linux.renderClanOptions Build done.
buildbot/nix-build .#checks.x86_64-linux.clan-dep-openssh Build done.
buildbot/nix-build .#checks.x86_64-linux."clan-dep-python3.11-mypy" Build done.
buildbot/nix-build .#checks.x86_64-linux.container Build done.
buildbot/nix-build .#checks.x86_64-linux.lib-jsonschema-example-valid Build done.
buildbot/nix-build .#checks.x86_64-linux.devShell-clan-vm-manager Build done.
buildbot/nix-build .#checks.x86_64-linux.package-clan-cli Build done.
buildbot/nix-build .#checks.x86_64-linux.package-default Build done.
buildbot/nix-build .#checks.x86_64-linux.module-schema Build done.
buildbot/nix-build .#checks.x86_64-linux.matrix-synapse Build done.
buildbot/nix-build .#checks.x86_64-linux."clan-dep-python3.11-qemu" Build done.
buildbot/nix-build .#checks.x86_64-linux.clan-dep-rsync Build done.
buildbot/nix-build .#checks.x86_64-linux.clan-dep-sops Build done.
buildbot/nix-build .#checks.x86_64-linux.clan-dep-sshpass Build done.
buildbot/nix-build .#checks.x86_64-linux.clan-dep-tor Build done.
buildbot/nix-build .#checks.x86_64-linux.clan-dep-zbar Build done.
buildbot/nix-build .#checks.x86_64-linux.clan-pytest-without-core Build done.
buildbot/nix-build .#checks.x86_64-linux.clan-vm-manager-no-breakpoints Build done.
buildbot/nix-build .#checks.x86_64-linux.clan-vm-manager-pytest Build done.
buildbot/nix-build .#checks.x86_64-linux.borgbackup Build done.
buildbot/nix-build .#checks.aarch64-linux.nixos-iso-installer Build done.
buildbot/nix-build .#checks.x86_64-linux.devShell-clan-cli Build done.
buildbot/nix-build .#checks.x86_64-linux.devShell-webview-ui Build done.
buildbot/nix-build .#checks.aarch64-linux.nixos-test-backup Build done.
buildbot/nix-build .#checks.x86_64-linux.devShell-default Build done.
buildbot/nix-build .#checks.x86_64-linux.package-clan-cli-docs Build done.
buildbot/nix-build .#checks.x86_64-linux.package-clan-ts-api Build done.
buildbot/nix-build .#checks.x86_64-linux.nixos-test-backup Build done.
buildbot/nix-build .#checks.x86_64-linux.package-clan-vm-manager Build done.
buildbot/nix-build .#checks.x86_64-linux.treefmt Build done.
buildbot/nix-build .#checks.x86_64-linux.deltachat Build done.
buildbot/nix-build .#checks.x86_64-linux.package-editor Build done.
buildbot/nix-build .#checks.x86_64-linux.package-impure-checks Build done.
buildbot/nix-build .#checks.x86_64-linux.package-merge-after-ci Build done.
buildbot/nix-build .#checks.x86_64-linux.lib-jsonschema-nix-unit-tests Build done.
buildbot/nix-build .#checks.x86_64-linux.package-moonlight-sunshine-accept Build done.
buildbot/nix-build .#checks.x86_64-linux.package-webview-ui Build done.
buildbot/nix-build .#checks.x86_64-linux.package-pending-reviews Build done.
buildbot/nix-build .#checks.x86_64-linux.package-zt-tcp-relay Build done.
buildbot/nix-build .#checks.x86_64-linux.package-zerotierone Build done.
buildbot/nix-build .#checks.x86_64-linux.package-tea-create-pr Build done.
buildbot/nix-build .#checks.x86_64-linux.package-wayland-proxy-virtwl Build done.
buildbot/nix-build .#checks.x86_64-linux.package-function-schema Build done.
buildbot/nix-build .#checks.x86_64-linux.package-zerotier-members Build done.
buildbot/nix-build .#checks.x86_64-linux.test-backups Build done.
buildbot/nix-build .#checks.x86_64-linux.nixos-test_install_machine Build done.
buildbot/nix-build .#checks.x86_64-linux.package-module-schema Build done.
buildbot/nix-build .#checks.x86_64-linux.secrets Build done.
buildbot/nix-build .#checks.x86_64-linux.zt-tcp-relay Build done.
buildbot/nix-build .#checks.x86_64-linux.nixos-flash-installer Build done.
buildbot/nix-build .#checks.x86_64-linux.package-iso-installer Build done.
buildbot/nix-build .#checks.x86_64-linux.nixos-iso-installer Build done.
buildbot/nix-build .#checks.x86_64-linux.wayland-proxy-virtwl Build done.
buildbot/nix-build .#checks.x86_64-linux.syncthing Build done.
buildbot/nix-build .#checks.x86_64-linux.clan-pytest-with-core Build done.
buildbot/nix-build .#checks.x86_64-linux.package-docs Build done.
buildbot/nix-build .#checks.x86_64-linux.package-deploy-docs Build done.
checks / checks-impure (pull_request) Successful in 2m29s
buildbot/nix-build .#checks.x86_64-linux.test-installation Build done.
buildbot/nix-eval Build done.
Since we already walk the user through creating a secret in an earlier step, it makes more sense explain first how to add machines/users to an existing secret instead of creating a new one
325 lines
9.5 KiB
Markdown
325 lines
9.5 KiB
Markdown
# Secrets / Facts
|
|
|
|
Clan enables encryption of secrets (such as passwords & keys) ensuring security and ease-of-use among users.
|
|
|
|
Clan utilizes the [sops](https://github.com/getsops/sops) format and integrates with [sops-nix](https://github.com/Mic92/sops-nix) on NixOS machines.
|
|
|
|
This guide will walk you through:
|
|
|
|
- **Creating a Keypair for Your User**: Learn how to generate a keypair for $USER to securely control all secrets.
|
|
- **Creating Your First Secret**: Step-by-step instructions on creating your initial secret.
|
|
- **Assigning Machine Access to the Secret**: Understand how to grant a machine access to the newly created secret.
|
|
|
|
## Create Your Admin Keypair
|
|
|
|
To get started, you'll need to create **Your admin keypair**.
|
|
|
|
!!! info
|
|
Don't worry — if you've already made one before, this step won't change or overwrite it.
|
|
|
|
```bash
|
|
clan secrets key generate
|
|
```
|
|
|
|
**Output**:
|
|
|
|
```{.console, .no-copy}
|
|
Public key: age1wkth7uhpkl555g40t8hjsysr20drq286netu8zptw50lmqz7j95sw2t3l7
|
|
|
|
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 YOUR_USER age1wkth7uhpkl555g40t8hjsysr20drq286netu8zptw50lmqz7j95sw2t3l7' (replace YOUR_USER with your actual username)
|
|
```
|
|
|
|
!!! warning
|
|
Make sure to keep a safe backup of the private key you've just created.
|
|
If it's lost, you won't be able to get to your secrets anymore because they all need the admin key to be unlocked.
|
|
|
|
!!! note
|
|
It's safe to add any secrets created by the clan CLI and placed in your repository to version control systems like `git`.
|
|
|
|
### Add Your Public Key
|
|
|
|
```bash
|
|
clan secrets users add $USER <your_public_key>
|
|
```
|
|
|
|
It's best to choose the same username as on your Setup/Admin Machine that you use to control the deployment with.
|
|
|
|
Once run this will create the following files:
|
|
|
|
```{.console, .no-copy}
|
|
sops/
|
|
└── users/
|
|
└── <your_username>/
|
|
└── key.json
|
|
```
|
|
If you followed the quickstart tutorial all necessary secrets are initialized at this point.
|
|
|
|
---
|
|
|
|
## Whats next?
|
|
|
|
- [Deployment](deploy.md): How to remotely deploy your machine
|
|
|
|
---
|
|
|
|
## More on Secrets
|
|
|
|
If you want to know more about how to save and share passwords in your clan read further!
|
|
|
|
### Adding a Secret
|
|
|
|
```shellSession
|
|
clan secrets set mysecret
|
|
Paste your secret:
|
|
```
|
|
|
|
### Retrieving a Stored Secret
|
|
|
|
```bash
|
|
clan secrets get mysecret
|
|
```
|
|
|
|
### List all Secrets
|
|
|
|
```bash
|
|
clan secrets list
|
|
```
|
|
|
|
### 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;
|
|
};
|
|
}
|
|
```
|
|
|
|
### Assigning Access
|
|
|
|
When using `clan secrets set <secret>` without arguments, secrets are encrypted for the key of the user named like your current $USER.
|
|
|
|
To add machines/users to an existing secret use:
|
|
|
|
```bash
|
|
clan secrets machines add-secret <machine_name> <secret_name>
|
|
```
|
|
|
|
Alternatively specify users and machines while creating a secret:
|
|
|
|
```bash
|
|
clan secrets set --machine <machine1> --machine <machine2> --user <user1> --user <user2> <secret_name>
|
|
```
|
|
|
|
## Advanced
|
|
|
|
In this section we go into more advanced secret management topics.
|
|
|
|
### Groups
|
|
|
|
Clan CLI makes it easy to manage access by allowing you to create groups.
|
|
|
|
All users within a group inherit access to all secrets of the group.
|
|
|
|
This feature eases the process of handling permissions for multiple users.
|
|
|
|
Here's how to get started:
|
|
|
|
1. **Creating Groups**:
|
|
|
|
Assign users to a new group, e.g., `admins`:
|
|
|
|
```bash
|
|
clan secrets groups add admins <username>
|
|
```
|
|
|
|
2. **Listing Groups**:
|
|
|
|
```bash
|
|
clan secrets groups list
|
|
```
|
|
|
|
3. **Assigning Secrets to Groups**:
|
|
|
|
```bash
|
|
clan secrets groups add-secret <group_name> <secret_name>
|
|
```
|
|
|
|
### Adding Machine Keys
|
|
|
|
New machines in Clan come with age keys stored in `./sops/machines/<machine_name>`. To list these machines:
|
|
|
|
```bash
|
|
clan secrets machines list
|
|
```
|
|
|
|
For existing machines, add their keys:
|
|
|
|
```bash
|
|
clan secrets machines add <machine_name> <age_key>
|
|
```
|
|
|
|
To fetch an age key from an SSH host key:
|
|
|
|
```bash
|
|
ssh-keyscan <domain_name> | nix shell nixpkgs#ssh-to-age -c ssh-to-age
|
|
```
|
|
|
|
### 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.
|
|
|
|
|
|
## Indepth Explanation
|
|
|
|
|
|
The secrets system conceptually knows two different entities:
|
|
|
|
- **Machine**: consumes secrets
|
|
- **User**: manages access to secrets
|
|
|
|
**A Users** Can add or revoke machines' access to secrets.
|
|
|
|
**A machine** Can decrypt secrets that where encrypted specifically for that machine.
|
|
|
|
!!! Danger
|
|
**Always make sure at least one _User_ has access to a secret**. Otherwise you could lock yourself out from accessing the secret.
|
|
|
|
### Inherited implications
|
|
|
|
By default clan uses [sops](https://github.com/getsops/sops) through [sops-nix](https://github.com/Mic92/sops-nix) for managing its secrets which inherits some implications that are important to understand:
|
|
|
|
- **Public/Private keys**: Entities are identified via their public keys. Each Entity can use their respective private key to decrypt a secret.
|
|
- **Public keys are stored**: All Public keys are stored inside the repository
|
|
- **Secrets are stored Encrypted**: secrets are stored inside the repository encrypted with the respective public keys
|
|
- **Secrets are deployed encrypted**: Fully encrypted secrets are deployed to machines at deployment time.
|
|
- **Secrets are decrypted by sops on-demand**: Each machine decrypts its secrets at runtime and stores them at an ephemeral location.
|
|
- **Machine key-pairs are auto-generated**: When a machine is created **no user-interaction is required** to setup public/private key-pairs.
|
|
- **secrets are re-encrypted**: In case machines, users or groups are modified secrets get re-encrypted on demand.
|
|
|
|
!!! Important
|
|
After revoking access to a secret you should also change the underlying secret. i.e. change the API key, or the password.
|
|
|
|
---
|
|
|
|
### Machine and user keys
|
|
|
|
The following diagrams illustrates how a user can provide a secret (i.e. a Password).
|
|
|
|
- By using the **Clan CLI** a user encrypts the password with both the **User public-key** and the **machine's public-key**
|
|
|
|
- The *Machine* can decrypt the password with its private-key on demand.
|
|
|
|
- The *User* is able to decrypt the password to make changes to it.
|
|
|
|
```plantuml
|
|
@startuml
|
|
!include C4_Container.puml
|
|
|
|
Person(user, "User", "Someone who manages secrets")
|
|
ContainerDb(secret, "Secret")
|
|
Container(machine, "Machine", "A Machine. i.e. Needs the Secret for a given Service." )
|
|
|
|
Rel_R(user, secret, "Encrypt", "", "Pubkeys: User, Machine")
|
|
Rel_L(secret, user, "Decrypt", "", "user privkey")
|
|
Rel_R(secret, machine, "Decrypt", "", "machine privkey" )
|
|
|
|
@enduml
|
|
```
|
|
|
|
|
|
#### User groups
|
|
|
|
Here we illustrate how machine groups work.
|
|
|
|
Common use cases:
|
|
|
|
- **Shared Management**: Access among multiple users. I.e. a subset of secrets/machines that have two admins
|
|
|
|
```plantuml
|
|
@startuml
|
|
!include C4_Container.puml
|
|
|
|
System_Boundary(c1, "Group") {
|
|
Person(user1, "User A", "has access")
|
|
Person(user2, "User B", "has access")
|
|
}
|
|
|
|
ContainerDb(secret, "Secret")
|
|
Container(machine, "Machine", "A Machine. i.e. Needs the Secret for a given Service." )
|
|
|
|
Rel_R(c1, secret, "Encrypt", "", "Pubkeys: User A, User B, Machine")
|
|
Rel_R(secret, machine, "Decrypt", "", "machine privkey" )
|
|
|
|
|
|
@enduml
|
|
```
|
|
|
|
<!-- TODO: See also [Groups Reference](#groups-reference) -->
|
|
|
|
---
|
|
|
|
#### Machine groups
|
|
|
|
Here we illustrate how machine groups work.
|
|
|
|
Common use cases:
|
|
|
|
- **Shared secrets**: Among multiple machines such as Wifi passwords
|
|
|
|
```plantuml
|
|
@startuml
|
|
!include C4_Container.puml
|
|
!include C4_Deployment.puml
|
|
|
|
Person(user, "User", "Someone who manages secrets")
|
|
ContainerDb(secret, "Secret")
|
|
System_Boundary(c1, "Group") {
|
|
Container(machine1, "Machine A", "Both machines need the same secret" )
|
|
Container(machine2, "Machine B", "Both machines need the same secret" )
|
|
}
|
|
|
|
Rel_R(user, secret, "Encrypt", "", "Pubkeys: machine A, machine B, User")
|
|
Rel(secret, c1, "Decrypt", "", "Both machine A or B can decrypt using their private key" )
|
|
|
|
|
|
@enduml
|
|
```
|
|
|
|
<!-- TODO: See also [Groups Reference](#groups-reference) -->
|
|
|
|
|
|
|
|
See the [readme](https://github.com/Mic92/sops-nix) of sops-nix for more
|
|
examples.
|
|
|
|
|
|
---
|
|
|
|
## Whats next?
|
|
|
|
- [Deployment](deploy.md): How to remotely deploy your machine
|
|
|
|
---
|