[pbs-devel] [PATCH proxmox-backup 1/3] pbs-config: cache verified API token secrets

[Fabian Grünbichler]

Quoting Samuel Rufinatscha (2025-12-05 14:25:54)
> Currently, every token-based API request reads the token.shadow file and
> runs the expensive password hash verification for the given token
> secret. This shows up as a hotspot in /status profiling (see
> bug #6049 [1]).
> 
> This patch introduces an in-memory cache of successfully verified token
> secrets. Subsequent requests for the same token+secret combination only
> perform a comparison using openssl::memcmp::eq and avoid re-running the
> password hash. The cache is updated when a token secret is set and
> cleared when a token is deleted. Note, this does NOT include manual
> config changes, which will be covered in a subsequent patch.
> 
> This patch partly fixes bug #6049 [1].
> 
> [1] https://bugzilla.proxmox.com/show_bug.cgi?id=7017
> 
> Signed-off-by: Samuel Rufinatscha <s.rufinatscha at proxmox.com>
> ---
>  pbs-config/src/token_shadow.rs | 58 +++++++++++++++++++++++++++++++++-
>  1 file changed, 57 insertions(+), 1 deletion(-)
> 
> diff --git a/pbs-config/src/token_shadow.rs b/pbs-config/src/token_shadow.rs
> index 640fabbf..47aa2fc2 100644
> --- a/pbs-config/src/token_shadow.rs
> +++ b/pbs-config/src/token_shadow.rs
> @@ -1,6 +1,8 @@
>  use std::collections::HashMap;
> +use std::sync::RwLock;
>  
>  use anyhow::{bail, format_err, Error};
> +use once_cell::sync::OnceCell;
>  use serde::{Deserialize, Serialize};
>  use serde_json::{from_value, Value};
>  
> @@ -13,6 +15,13 @@ use crate::{open_backup_lockfile, BackupLockGuard};
>  const LOCK_FILE: &str = pbs_buildcfg::configdir!("/token.shadow.lock");
>  const CONF_FILE: &str = pbs_buildcfg::configdir!("/token.shadow");
>  
> +/// Global in-memory cache for successfully verified API token secrets.
> +/// The cache stores plain text secrets for token Authids that have already been
> +/// verified against the hashed values in `token.shadow`. This allows for cheap
> +/// subsequent authentications for the same token+secret combination, avoiding
> +/// recomputing the password hash on every request.
> +static TOKEN_SECRET_CACHE: OnceCell<RwLock<ApiTokenSecretCache>> = OnceCell::new();
> +
>  #[derive(Serialize, Deserialize)]
>  #[serde(rename_all = "kebab-case")]
>  /// ApiToken id / secret pair
> @@ -54,9 +63,25 @@ pub fn verify_secret(tokenid: &Authid, secret: &str) -> Result<(), Error> {
>          bail!("not an API token ID");
>      }
>  
> +    // Fast path
> +    if let Some(cached) = token_secret_cache().read().unwrap().secrets.get(tokenid) {

did you benchmark this with a lot of parallel token requests? a plain RwLock
gives no guarantees at all w.r.t. ordering or fairness, so a lot of token-based
requests could effectively prevent token removal AFAICT (or vice-versa,
spamming token creation could lock out all tokens?)

since we don't actually require the cache here to proceed, we could also make this a try_read
or a read with timeout, and fallback to the slow path if there is too much
contention? alternatively, comparing with parking_lot would also be
interesting, since that implementation does have fairness guarantees.

note that token-based requests are basically doable by anyone being able to
reach PBS, whereas token creation/deletion is available to every authenticaed
user.

> +        // Compare cached secret with provided one using constant time comparison
> +        if openssl::memcmp::eq(cached.as_bytes(), secret.as_bytes()) {
> +            // Already verified before
> +            return Ok(());
> +        }
> +        // Fall through to slow path if secret doesn't match cached one
> +    }

this could also be a helper, like the rest. then it would consume (a reference
to) the user-provided secret value, instead of giving access to all cached
ones. doesn't make a real difference now other than consistence, but the cache
is (more) cleanly encapsulated then.

> +
> +    // Slow path: read file + verify hash
>      let data = read_file()?;
>      match data.get(tokenid) {
> -        Some(hashed_secret) => proxmox_sys::crypt::verify_crypt_pw(secret, hashed_secret),
> +        Some(hashed_secret) => {
> +            proxmox_sys::crypt::verify_crypt_pw(secret, hashed_secret)?;
> +            // Cache the plain secret for future requests
> +            cache_insert_secret(tokenid.clone(), secret.to_owned());

same applies here - storing the value in the cache is optional (and good if it
works), but we don't want to stall forever waiting for the cache insertion to
go through..

> +            Ok(())
> +        }
>          None => bail!("invalid API token"),
>      }
>  }
> @@ -82,6 +107,8 @@ fn set_secret(tokenid: &Authid, secret: &str) -> Result<(), Error> {
>      data.insert(tokenid.clone(), hashed_secret);
>      write_file(data)?;
>  
> +    cache_insert_secret(tokenid.clone(), secret.to_owned());

this

> +
>      Ok(())
>  }
>  
> @@ -97,5 +124,34 @@ pub fn delete_secret(tokenid: &Authid) -> Result<(), Error> {
>      data.remove(tokenid);
>      write_file(data)?;
>  
> +    cache_remove_secret(tokenid);

and this need to block of course and can't be skipped, because otherwise the
read above might operate on wrong data..

> +
>      Ok(())
>  }
> +
> +struct ApiTokenSecretCache {
> +    /// Keys are token Authids, values are the corresponding plain text secrets.
> +    /// Entries are added after a successful on-disk verification in
> +    /// `verify_secret` or when a new token secret is generated by
> +    /// `generate_and_set_secret`. Used to avoid repeated
> +    /// password-hash computation on subsequent authentications.
> +    secrets: HashMap<Authid, String>,
> +}
> +
> +fn token_secret_cache() -> &'static RwLock<ApiTokenSecretCache> {
> +    TOKEN_SECRET_CACHE.get_or_init(|| {
> +        RwLock::new(ApiTokenSecretCache {
> +            secrets: HashMap::new(),
> +        })
> +    })
> +}
> +
> +fn cache_insert_secret(tokenid: Authid, secret: String) {
> +    let mut cache = token_secret_cache().write().unwrap();
> +    cache.secrets.insert(tokenid, secret);
> +}
> +
> +fn cache_remove_secret(tokenid: &Authid) {
> +    let mut cache = token_secret_cache().write().unwrap();
> +    cache.secrets.remove(tokenid);
> +}
> -- 
> 2.47.3
> 
> 
> 
> _______________________________________________
> pbs-devel mailing list
> pbs-devel at lists.proxmox.com
> https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel
> 
>