Dave HammerandGitHub
0919fff83c
Mount, unmount, init, and auto-mount gocryptfs volumes from Noctalia. Passwords use secret-tool (desktop keyring) plus keyctl session cache.
106 lines
5.2 KiB
Markdown
106 lines
5.2 KiB
Markdown
# Gocryptfs
|
|
|
|
Mount, unmount, initialize, and auto-mount [gocryptfs](https://github.com/rfjakob/gocryptfs) encrypted volumes from Noctalia — bar status, manager panel, and optional auto-mount after login.
|
|
|
|
## Plugin
|
|
|
|
| Field | Value |
|
|
| --- | --- |
|
|
| ID | `davemhammer/gocryptfs` |
|
|
| Entries | Bar widget: `status`; panel: `manager`; service: `service` |
|
|
|
|
## Requirements
|
|
|
|
Install these on `PATH` (declared in `plugin.toml` `dependencies`):
|
|
|
|
- `gocryptfs` — mount and `gocryptfs -init`
|
|
- `fusermount3` or `fusermount` — FUSE unmount (first found wins)
|
|
- `keyctl` — kernel user-keyring session cache for remembered passwords (package `keyutils`)
|
|
- `secret-tool` — Freedesktop Secret Service client for reboot-persistent passwords (package `libsecret` / `libsecret-tools`)
|
|
- `chmod` — mode bits on short-lived temp password files
|
|
- `xdg-open` — open the mount point in the file manager
|
|
- `cat` — read `/proc/mounts` for mount status
|
|
|
|
**Desktop keyring:** persistent “Remember” needs a Secret Service backend (GNOME Keyring, KeePassXC as Secret Service, etc.) running and unlocked after login. If only `keyctl` is available, remember still works for the current login session.
|
|
|
|
## Usage
|
|
|
|
Add the **status** bar widget from Settings → Bar (`davemhammer/gocryptfs:status`).
|
|
|
|
- **Left-click** — open the manager panel
|
|
- **Right-click** — refresh mount status
|
|
|
|
In the panel you can:
|
|
|
|
- Select a volume → **Mount** / **Unmount** / **Open** (file manager via `xdg-open`)
|
|
- **Edit → Remember / Forget** — store or clear the volume password (desktop keyring + session cache)
|
|
- **Add** an existing cipher directory, or **Init** a new one (`gocryptfs -init`)
|
|
- Mount with a remembered keyring password, an optional advanced passfile path, or a one-shot password prompt (optional “also remember”)
|
|
|
|
```sh
|
|
noctalia msg panel-toggle davemhammer/gocryptfs:manager
|
|
```
|
|
|
|
### Auto-mount on login
|
|
|
|
Requires all of:
|
|
|
|
1. Plugin setting **Auto-mount on login** (default on)
|
|
2. Per-volume **Auto-mount** enabled
|
|
3. A remembered keyring password (**Remember**) or an advanced passfile path
|
|
|
|
After reboot, the desktop keyring must unlock (normal login) so `secret-tool` can supply the password. The kernel session key is refilled automatically on mount.
|
|
|
|
## Settings
|
|
|
|
| Setting | Type | Default | Description |
|
|
| --- | --- | --- | --- |
|
|
| `refresh_interval` | `int` | `3` | Seconds between `/proc/mounts` polls. |
|
|
| `notify_on_action` | `bool` | `true` | Notify after mount, unmount, init, remember, and forget. |
|
|
| `create_mountpoint` | `bool` | `true` | Create the mount directory if missing before mount. |
|
|
| `auto_mount` | `bool` | `true` | Global switch: on service start, queue volumes that have auto-mount + keyring/passfile. |
|
|
| `show_count` | `bool` (widget) | `true` | Show `mounted/total` on the bar. |
|
|
| `glyph_color` | `select` (widget) | `on_surface` | Lock icon color when nothing is mounted. |
|
|
| `mounted_color` | `select` (widget) | `tertiary` | Icon/dot color when at least one volume is mounted. |
|
|
| `unmounted_color` | `select` (widget) | `on_surface_variant` | Status-dot color when nothing is mounted. |
|
|
|
|
## IPC
|
|
|
|
```sh
|
|
noctalia msg panel-toggle davemhammer/gocryptfs:manager
|
|
noctalia msg plugin davemhammer/gocryptfs:service all refresh
|
|
noctalia msg plugin davemhammer/gocryptfs:service all reload
|
|
noctalia msg plugin davemhammer/gocryptfs:service all automount
|
|
```
|
|
|
|
- `refresh` — re-read `/proc/mounts` and refresh the snapshot
|
|
- `reload` — reload `volumes.json` from the plugin data dir, clear the auto-mount queue, then refresh
|
|
- `automount` — reset the auto-mount schedule and refresh (eligible volumes are queued again on the next status pass)
|
|
|
|
## Notes
|
|
|
|
### Data and filesystem
|
|
|
|
- Volume definitions live under the plugin data directory as `volumes.json` (not inside the cipher directory).
|
|
- With **Create mount points** on, the service may `mkdir` the configured mount path before mounting.
|
|
- Cipher, mount, and passfile paths reject empty values, NUL, and `..` segments. Symlinks on those paths are followed by design (user-chosen paths).
|
|
|
|
### Secrets (no long-lived plaintext under plugin data)
|
|
|
|
**Remember password** does **not** write a long-lived password file under the plugin data dir. It stores the secret in:
|
|
|
|
1. **Desktop keyring** via `secret-tool` — attributes `service=noctalia-gocryptfs`, `volume-id=<volume-id>`. Survives reboot while the login keyring is unlocked.
|
|
2. **Kernel session keyring** via `keyctl` — description `noctalia-gocryptfs:<volume-id>`. Fast cache for this login only; cleared on reboot/logout.
|
|
|
|
On mount / auto-mount, the service prefers the session key; if missing, it hydrates from `secret-tool` into `keyctl`, then runs `gocryptfs -extpass keyctl pipe <id>`. Fallback: `gocryptfs -extpass secret-tool lookup …`.
|
|
|
|
- One-shot typed passwords use a short-lived file under `/dev/shm` (tmpfs) when available, then delete it.
|
|
- Optional **advanced** passfile paths remain supported for users who manage their own files (plaintext by user choice; not recommended).
|
|
- **Forget** and volume remove clear both the desktop keyring entry and the session key.
|
|
- Passwords are not logged.
|
|
|
|
### Processes and network
|
|
|
|
- Spawns: `gocryptfs`, `fusermount3` or `fusermount`, `keyctl`, `secret-tool`, `chmod`, `cat` (`/proc/mounts`), `xdg-open`.
|
|
- **Network:** none.
|