Skip to main content

Module secrets

Module secrets 

Source
Expand description

Credential handling for extensions.

Extensions that access external services (HTTP APIs, databases, cloud storage) commonly need credentials.

§What DuckDB does and does not give you

DuckDB has a native secrets system (CREATE SECRET), but the extension C API exposes none of it — there is not one duckdb_secret_* function among the 546 slots of duckdb_ext_api_v1 in DuckDB 1.5.5. An extension cannot ask DuckDB for a credential through the C API at all.

What it can do is query the duckdb_secrets() table function, and list_duckdb_secrets does exactly that. DuckDB redacts there the fields each secret type declares sensitive — and only those. Verified against DuckDB 1.5.5:

CREATE SECRET s (TYPE s3, KEY_ID 'AKIAEXAMPLE', SECRET 'super-secret-value');
SELECT secret_string FROM duckdb_secrets();
-- ...;key_id=AKIAEXAMPLE;secret=redacted

That is not a guarantee that secret_string holds no credential: the built-in http type renders extra_http_headers — an Authorization header included — in full up to DuckDB 1.5.x (2.0.0 redacts it, as default_secrets.cpp now lists it among the type’s redacted keys), a secret type that declares no sensitive keys is rendered whole, and what counts as sensitive changes between releases: an http secret’s bearer_token is redacted by DuckDB 1.5.3 and later but shown in full by 1.4.4 and 1.5.0 (checked in CI; 1.5.1 and 1.5.2 untested). Treat secret_string as sensitive, and do not rely on it as a credential source either: an extension that needs a credential must obtain it some other way — an environment variable, a config option, a file, its own key store.

§What this module is for

SecretsManager is the trait an extension implements over its own credential source, and SecretEntry is what that source returns. It is not a bridge to DuckDB’s secrets, because no such bridge is available; it exists so the credential handling an extension has to write anyway comes with redacting Debug, zeroize-on-drop and no PartialEq already in place.

list_duckdb_secrets complements it by reporting which secrets the user has configured, which is enough to pick a scope, warn about a missing secret, or decide which provider to use.

§Security considerations

SecretEntry is designed to minimize accidental credential leakage:

  • Debug redacts field values — only field keys are shown, values are replaced with "[REDACTED]". Use get_field to access actual values in code.
  • Drop zeroizes sensitive data — every field key and value, plus provider and scope, is overwritten with zeros using std::ptr::write_volatile before deallocation, so secrets do not linger in freed memory. This covers the buffers a SecretEntry owns; it cannot cover a String the caller passed in and still holds, nor a buffer a String abandoned when it grew.
  • No PartialEq — prevents accidental non-constant-time comparisons of secret material. Compare individual fields explicitly if needed.
  • Clone is explicit — cloning is supported but documented so that callers are aware they are duplicating sensitive material in memory.

§Example

use quack_rs::secrets::{SecretEntry, SecretsManager};

struct MySecrets {
    // In practice, the extension's own credential source: environment
    // variables, a config option, a file. The C API offers no route to
    // DuckDB's CREATE SECRET storage (see above).
    entries: Vec<SecretEntry>,
}

impl SecretsManager for MySecrets {
    fn get_secret(&self, name: &str, secret_type: &str) -> Option<SecretEntry> {
        self.entries.iter()
            .find(|e| e.name() == name && e.secret_type() == secret_type)
            .cloned()
    }

    fn list_secrets(&self, secret_type: Option<&str>) -> Vec<SecretEntry> {
        self.entries.iter()
            .filter(|e| secret_type.is_none() || secret_type == Some(e.secret_type()))
            .cloned()
            .collect()
    }

    fn remove_secret(&self, _name: &str, _secret_type: &str) -> bool {
        false // read-only example
    }
}

Structs§

DuckDbSecretInfo
Metadata about one secret the user has configured in DuckDB.
SecretEntry
A single secret entry retrieved from the secrets manager.

Traits§

SecretsManager
Trait for accessing DuckDB’s secrets management system.

Functions§

list_duckdb_secrets⚠
Lists the secrets configured in the DuckDB instance behind connection.