- Lightweight & feature-rich Wayland clipboard "manager" with fast persistent history and
- robust multi-media support. Stores and previews clipboard entries (text, images)
- on the clipboard with a neat TUI and advanced scripting capabilities.
+ Lightweight & feature-rich Wayland clipboard "manager" with fast persistent
+ history and robust multi-media support. Stores and previews clipboard
+ entries (text, images) on the clipboard with a neat TUI and advanced scripting
+ capabilities.
@@ -52,6 +53,7 @@ with many features such as but not necessarily limited to:
- Drop-in replacement for `wl-clipboard` tools (`wl-copy` and `wl-paste`)
- Sensitive clipboard filtering via regex (see below)
- Sensitive clipboard filtering by application (see below)
+- Database encryption using age (see below)
on top of the existing features of Cliphist, which are as follows:
@@ -357,21 +359,38 @@ sensitive pattern, using a regular expression. This is useful for preventing
accidental storage of secrets, passwords, or other sensitive data. You don't
want sensitive data ending up in your persistent clipboard, right?
-The filter can be configured in one of three ways, as part of two separate
-features.
+The filter can be configured in several ways, as part of two separate features.
#### Clipboard Filtering by Entry Regex
-This can be configured in one of two ways. You can use the **environment
-variable** `STASTH_SENSITIVE_REGEX` to a valid regex pattern, and if the
+This can be configured in one of several ways. You can use the **environment
+variable** `STASH_SENSITIVE_REGEX` to a valid regex pattern, and if the
clipboard text matches the regex it will not be stored. This can be used for
trivial secrets such as but not limited to GitHub tokens or secrets that follow
a rule, e.g. a prefix. You would typically set this in your `~/.bashrc` or
similar but in some cases this might be a security flaw.
-The safer alternative to this is using **Systemd LoadCrediental**. If Stash is
-running as a Systemd service, you can provide a regex pattern using a crediental
-file. For example, add to your `stash.service`:
+The _less-insecure_ [^1] alternative to this is using
+`STASH_SENSITIVE_REGEX_FILE` to read the regex from a file path. This is useful
+for NixOS secrets managers like agenix or sops-nix.
+
+```bash
+# You can set this in your configuration with `environment.sessionVariables`
+# or similar, pointing to the *decryption path*.
+$ export STASH_SENSITIVE_REGEX_FILE=/run/secrets/stash/clipboard_filter
+```
+
+Or use `STASH_SENSITIVE_REGEX_COMMAND` to execute a command that returns the
+regex pattern. This works well with password managers:
+
+```bash
+# Stash will execute the command and consume the result
+$ export STASH_SENSITIVE_REGEX_COMMAND="pass show stash/clipboard-filter"
+```
+
+The safest option is using **Systemd LoadCredential**. If Stash is running as a
+Systemd service, you can provide a regex pattern using a credential file. For
+example, add to your `stash.service`:
```dosini
LoadCredential=clipboard_filter:/etc/stash/clipboard_filter
@@ -382,9 +401,9 @@ quotes). This is done automatically in the
[vendored Systemd service](./contrib/stash.service). Remember to set the
appropriate file permissions if using this option.
-The service will check the credential file first, then the environment variable.
-If a clipboard entry matches the regex, it will be skipped and a warning will be
-logged.
+The service will check the credential file first, then the command, then the
+file path, then the environment variable. If a clipboard entry matches the
+regex, it will be skipped and a warning will be logged.
> [!TIP]
> **Example regex to block common password patterns**:
@@ -393,17 +412,21 @@ logged.
>
> For security reasons, you are recommended to use the regex only for generic
> tokens that follow a specific rule, for example a generic prefix or suffix.
+> For blocking entries from applications that emit sensitive data, such as
+> password managers, filter by application class instead.
#### Clipboard Filtering by Application Class
Stash allows blocking an entry from the persistent history if it has been copied
from certain applications. This depends on the `use-toplevel` feature flag and
uses the the `wlr-foreign-toplevel-management-v1` protocol for precise focus
-detection. While this feature flag is enabled (the default) you may use
-`--excluded-apps` in, e.g., `stash watch` or set the `STASH_EXCLUDED_APPS`
-environment variable to block entries from persisting in the database if they
-are coming from your password manager for example. The entry is still copied to
-the clipboard, but it will never be put inside the database.
+detection.
+
+While this feature flag is enabled (the default) you may use `--excluded-apps`
+in, e.g., `stash watch` or set the `STASH_EXCLUDED_APPS` environment variable to
+block entries from persisting in the database if they are coming from your
+password manager for example. The entry is still copied to the clipboard, but it
+will never be put inside the database.
This is a more robust alternative to using the regex method above, since you
likely do not want to catch your passwords with a regex. Simply pass your
@@ -516,6 +539,66 @@ figured out something new, e.g. a neat shell trick, feel free to add it here!
the packagers. While building from source, you may link
`target/release/stash` manually.
+### Database Encryption
+
+Stash supports encrypting clipboard entries at rest using the
+[age](https://age-encryption.org/) encryption format. This provides protection
+for sensitive data stored in the database.
+
+> [!WARNING]
+> If you enable encryption after already having entries in the database, the
+> existing entries will remain unencrypted. Only new entries added after
+> configuring encryption will be encrypted. To encrypt existing entries, you
+> would need to wipe the database and re-copy your clipboard contents.
+
+Encryption is **opt-in** and only takes effect when a passphrase is configured.
+When one _is_ configured, all new clipboard entries are encrypted before being
+stored in the database. Entries without encryption configured are stored in
+plaintext instead.
+
+Encrypted entries are detected by the `age-encryption.org/v1` header and
+decrypted automatically on retrieval. Search operations (e.g.,
+`stash delete --type query`) decrypt entries on-the-fly to match queries;
+entries that fail decryption are skipped with a warning
+
+#### Configuration
+
+Encryption is configured using a passphrase, which can be provided in one of
+several ways. The simplest is using the **environment variable**
+`STASH_ENCRYPTION_PASSPHRASE`:
+
+```bash
+export STASH_ENCRYPTION_PASSPHRASE="your-secure-passphrase"
+```
+
+Alternatively, you can use `STASH_ENCRYPTION_PASSPHRASE_FILE` to read the
+passphrase from a file path. This is useful for NixOS secrets managers:
+
+```bash
+export STASH_ENCRYPTION_PASSPHRASE_FILE=/run/secrets/stash/encryption_passphrase
+```
+
+Or use `STASH_ENCRYPTION_PASSPHRASE_COMMAND` to execute a command that returns
+the passphrase. This works well with password managers:
+
+```bash
+export STASH_ENCRYPTION_PASSPHRASE_COMMAND="pass show stash/encryption-key"
+```
+
+The safest option is using **Systemd LoadCredential**. If Stash is running as a
+Systemd service, you can provide the passphrase using a credential file:
+
+```dosini
+LoadCredential=stash_encryption_passphrase:/etc/stash/encryption_passphrase
+```
+
+This is done automatically in the
+[vendored Systemd service](./contrib/stash.service).
+
+> [!TIP]
+> When using encryption, make sure to back up your passphrase. Without it, you
+> will not be able to recover encrypted entries.
+
### Entry Expiration
Stash supports time-to-live (TTL) for clipboard entries. When an entry's
diff --git a/src/db/mod.rs b/src/db/mod.rs
index 65eb097..c0d24d8 100644
--- a/src/db/mod.rs
+++ b/src/db/mod.rs
@@ -215,12 +215,18 @@ pub enum StashError {
QueryDelete(Box
),
#[error("Failed to delete entry with id {0}: {1}")]
DeleteEntry(i64, Box),
+
+ #[error("Encryption error: {0}")]
+ Encryption(Box),
+ #[error("Decryption error: {0}")]
+ Decryption(Box),
}
pub trait ClipboardDb {
/// Store a new clipboard entry.
///
/// # Arguments
+ ///
/// * `input` - Reader for the clipboard content
/// * `max_dedupe_search` - Maximum number of recent entries to check for
/// duplicates
@@ -595,11 +601,24 @@ impl SqliteClipboardDb {
.get(2)
.map_err(|e| StashError::ListDecode(e.to_string().into()))?;
+ let decrypted_contents = if contents.starts_with(b"age-encryption.org/v1")
+ {
+ match decrypt_data(&contents) {
+ Ok(decrypted) => decrypted,
+ Err(e) => {
+ warn!("skipping entry {id}: decryption failed: {e}");
+ continue;
+ },
+ }
+ } else {
+ contents
+ };
+
let contents_str = match mime.as_deref() {
Some(m) if m.starts_with("text/") || m == "application/json" => {
- String::from_utf8_lossy(&contents).into_owned()
+ String::from_utf8_lossy(&decrypted_contents).into_owned()
},
- _ => base64::prelude::BASE64_STANDARD.encode(&contents),
+ _ => base64::prelude::BASE64_STANDARD.encode(&decrypted_contents),
};
entries.push(serde_json::json!({
"id": id,
@@ -689,13 +708,22 @@ impl ClipboardDb for SqliteClipboardDb {
None => None,
};
+ let encrypted_buf = if load_encryption_passphrase().is_some() {
+ Some(encrypt_data(&buf)?)
+ } else {
+ debug!("No encryption passphrase configured, storing entry unencrypted");
+ None
+ };
+
+ let contents_to_store = encrypted_buf.unwrap_or(buf);
+
self
.conn
.execute(
"INSERT INTO clipboard (contents, mime, content_hash, last_accessed, \
mime_types) VALUES (?1, ?2, ?3, ?4, ?5)",
params![
- buf,
+ contents_to_store,
mime,
content_hash,
std::time::SystemTime::now()
@@ -837,8 +865,20 @@ impl ClipboardDb for SqliteClipboardDb {
let mime: Option = row
.get(2)
.map_err(|e| StashError::ListDecode(e.to_string().into()))?;
+ let preview_contents = if contents.starts_with(&[0x01u8]) {
+ match decrypt_data(&contents) {
+ Ok(decrypted) => decrypted,
+ Err(e) => {
+ warn!("skipping entry {id}: decryption failed: {e}");
+ continue;
+ },
+ }
+ } else {
+ contents
+ };
- let preview = preview_entry(&contents, mime.as_deref(), preview_width);
+ let preview =
+ preview_entry(&preview_contents, mime.as_deref(), preview_width);
if writeln!(out, "{id}\t{preview}").is_ok() {
listed += 1;
}
@@ -872,8 +912,15 @@ impl ClipboardDb for SqliteClipboardDb {
|row| Ok((row.get(0)?, row.get(1)?)),
)
.map_err(|e| StashError::DecodeGet(e.to_string().into()))?;
+
+ let decrypted_contents = if contents.starts_with(&[0x01u8]) {
+ decrypt_data(&contents)?
+ } else {
+ contents
+ };
+
out
- .write_all(&contents)
+ .write_all(&decrypted_contents)
.map_err(|e| StashError::DecodeWrite(e.to_string().into()))?;
log::info!("decoded entry with id {id}");
Ok(())
@@ -898,7 +945,23 @@ impl ClipboardDb for SqliteClipboardDb {
let contents: Vec = row
.get(1)
.map_err(|e| StashError::QueryDelete(e.to_string().into()))?;
- if contents.windows(query.len()).any(|w| w == query.as_bytes()) {
+
+ let searchable_contents = if contents.starts_with(&[0x01u8]) {
+ match decrypt_data(&contents) {
+ Ok(decrypted) => decrypted,
+ Err(e) => {
+ warn!("skipping entry {id}: decryption failed: {e}");
+ continue;
+ },
+ }
+ } else {
+ contents
+ };
+
+ if searchable_contents
+ .windows(query.len())
+ .any(|w| w == query.as_bytes())
+ {
self
.conn
.execute("DELETE FROM clipboard WHERE id = ?1", params![id])
@@ -963,7 +1026,13 @@ impl ClipboardDb for SqliteClipboardDb {
}
}
- Ok((id, contents, mime))
+ let decrypted_contents = if contents.starts_with(&[0x01u8]) {
+ decrypt_data(&contents)?
+ } else {
+ contents
+ };
+
+ Ok((id, decrypted_contents, mime))
}
}
@@ -1038,7 +1107,20 @@ impl SqliteClipboardDb {
let mime: Option = row
.get(2)
.map_err(|e| StashError::ListDecode(e.to_string().into()))?;
- let preview = preview_entry(&contents, mime.as_deref(), preview_width);
+ let decrypted_contents = if contents.starts_with(&[0x01u8]) {
+ match decrypt_data(&contents) {
+ Ok(decrypted) => decrypted,
+ Err(e) => {
+ warn!("skipping entry {id}: decryption failed: {e}");
+ continue;
+ },
+ }
+ } else {
+ contents
+ };
+
+ let preview =
+ preview_entry(&decrypted_contents, mime.as_deref(), preview_width);
let mime_str = mime.unwrap_or_default();
window.push((id, preview, mime_str));
}
@@ -1155,10 +1237,23 @@ impl SqliteClipboardDb {
/// changes made after daemon startup. Regex compilation is cached by
/// pattern to avoid recompilation.
fn load_sensitive_regex() -> Option {
+ use std::process::Command;
+
// Get the current pattern from env vars
- let pattern = if let Ok(regex_path) = env::var("CREDENTIALS_DIRECTORY") {
- let file = format!("{regex_path}/clipboard_filter");
+ let pattern = if let Ok(cred_dir) = env::var("CREDENTIALS_DIRECTORY") {
+ let file = format!("{cred_dir}/clipboard_filter");
fs::read_to_string(&file).ok().map(|s| s.trim().to_string())
+ } else if let Ok(cmd) = env::var("STASH_SENSITIVE_REGEX_COMMAND") {
+ Command::new("sh")
+ .args(["-c", &cmd])
+ .output()
+ .ok()
+ .filter(|o| o.status.success())
+ .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
+ } else if let Ok(file_path) = env::var("STASH_SENSITIVE_REGEX_FILE") {
+ fs::read_to_string(&file_path)
+ .ok()
+ .map(|s| s.trim().to_string())
} else {
env::var("STASH_SENSITIVE_REGEX").ok()
}?;
@@ -1185,6 +1280,68 @@ fn load_sensitive_regex() -> Option {
})
}
+fn load_encryption_passphrase() -> Option {
+ use std::process::Command;
+
+ static PASSPHRASE_CACHE: OnceLock =
+ OnceLock::new();
+
+ if let Some(cached) = PASSPHRASE_CACHE.get() {
+ return Some(cached.clone());
+ }
+
+ let passphrase = if let Ok(cred_dir) = env::var("CREDENTIALS_DIRECTORY") {
+ let file = format!("{cred_dir}/stash_encryption_passphrase");
+ fs::read_to_string(&file).ok().map(|s| s.trim().to_owned())
+ } else if let Ok(cmd) = env::var("STASH_ENCRYPTION_PASSPHRASE_COMMAND") {
+ Command::new("sh")
+ .args(["-c", &cmd])
+ .output()
+ .ok()
+ .filter(|o| o.status.success())
+ .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_owned())
+ } else if let Ok(file_path) = env::var("STASH_ENCRYPTION_PASSPHRASE_FILE") {
+ fs::read_to_string(&file_path)
+ .ok()
+ .map(|s| s.trim().to_owned())
+ } else {
+ env::var("STASH_ENCRYPTION_PASSPHRASE").ok()
+ }?;
+
+ let secret = age::secrecy::SecretString::from(passphrase);
+ let _ = PASSPHRASE_CACHE.set(secret.clone());
+ Some(secret)
+}
+
+fn encrypt_data(data: &[u8]) -> Result, StashError> {
+ let passphrase = load_encryption_passphrase().ok_or_else(|| {
+ StashError::Encryption("No encryption passphrase configured".into())
+ })?;
+
+ let recipient = age::scrypt::Recipient::new(passphrase);
+ let encrypted = age::encrypt(&recipient, data)
+ .map_err(|e| StashError::Encryption(e.to_string().into()))?;
+ // Prepend marker byte to identify our encrypted data
+ let mut result = Vec::with_capacity(1 + encrypted.len());
+ result.push(0x01u8);
+ result.extend_from_slice(&encrypted);
+ Ok(result)
+}
+
+fn decrypt_data(encrypted: &[u8]) -> Result, StashError> {
+ let passphrase = load_encryption_passphrase().ok_or_else(|| {
+ StashError::Decryption("No encryption passphrase configured".into())
+ })?;
+
+ // Strip our marker byte if present
+ let data_to_decrypt = encrypted.strip_prefix(&[0x01u8]).unwrap_or(encrypted);
+
+ let identity = age::scrypt::Identity::new(passphrase);
+ let decrypted = age::decrypt(&identity, data_to_decrypt)
+ .map_err(|e| StashError::Decryption(e.to_string().into()))?;
+ Ok(decrypted)
+}
+
pub fn extract_id(input: &str) -> Result {
let id_str = input.split('\t').next().unwrap_or("");
id_str.parse().map_err(|_| "invalid id")