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=redactedThat 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:
Debugredacts field values — only field keys are shown, values are replaced with"[REDACTED]". Useget_fieldto access actual values in code.Dropzeroizes sensitive data — every field key and value, plusproviderandscope, is overwritten with zeros usingstd::ptr::write_volatilebefore deallocation, so secrets do not linger in freed memory. This covers the buffers aSecretEntryowns; it cannot cover aStringthe caller passed in and still holds, nor a buffer aStringabandoned when it grew.- No
PartialEq— prevents accidental non-constant-time comparisons of secret material. Compare individual fields explicitly if needed. Cloneis 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§
- Duck
DbSecret Info - Metadata about one secret the user has configured in
DuckDB. - Secret
Entry - A single secret entry retrieved from the secrets manager.
Traits§
- Secrets
Manager - Trait for accessing
DuckDB’s secrets management system.
Functions§
- list_
duckdb_ ⚠secrets - Lists the secrets configured in the
DuckDBinstance behindconnection.