Crate openbao 

Secure, typed, async Rust SDK for OpenBao.

This crate is intentionally conservative:

• unsafe Rust is forbidden;
• tokens are stored as secrecy::SecretString;
• HTTPS is required by default;
• OpenBao API URLs are assembled with structured URL path segments;
• authentication state is represented in the type system.

The public API covers environment-based client construction, AppRole login, direct token auth, LDAP/RADIUS/Kerberos auth, JWT/OIDC browser-flow helpers, token lifecycle and token-role helpers, Cubbyhole, Identity lifecycle, lookup, and merge helpers, KV v1/v2, Kubernetes secrets, RabbitMQ secrets, Transit lifecycle, batch, single-operation cryptography, import/BYOK, and PKI issue/sign/revoke/tidy helpers, system health/readiness, dev-only bootstrap, mount management, audit devices, exact and prefix lease helpers, password policies, resultant ACL inspection, operator-gated root/recovery token ceremonies, in-flight request diagnostics, plugin catalog operations, OpenBao 2.6 workflow management and bounded secret-aware execution, SSH, TOTP, and raw JSON calls for advanced users. Workflow trace and token-free execution require separate acknowledgment feature pairs because traces can expose the caller token and unauthenticated routes expand public attack surface. Public raw JSON, byte, and response-wrapping transports require the non-default raw-api plus raw-api-acknowledged features because they bypass typed endpoint validation and operation-specific feature gates. JWT/OIDC callback and poll GET operations, plus the Identity provider GET authorize variant, require the non-default oidc-get-callback-acknowledged feature because OpenBao places credentials or correlation values in URL query strings. OpenBao 2.6 identity-template delimiter overrides require the non-default identity-template-overrides-acknowledged feature and explicit per-surface acknowledgment constructors. Ordinary ACL, PKI, and SSH request serialization cannot enable these injection-sensitive flags. Selected system endpoints that return non-JSON data, such as Prometheus metrics and capped Raft snapshots, are exposed through typed helpers rather than a public raw-body escape hatch. The non-default monitor-stream feature exposes /sys/monitor as a lazy, bounded stream of sanitizing frames. Frames remain untrusted log data; their contents are never included in crate Debug or tracing output.

AdminBootstrap performs read-compare-write convergence. Run only one bootstrap plan per OpenBao cluster at a time unless the caller provides an external lock. KV v2 secret convergence uses OpenBao CAS where available, but ACL policies, AppRole settings, and other bootstrap operations still require caller-owned serialization to avoid overwriting concurrent changes.

Secret request payloads are serialized through a sanitizing intermediate buffer before handoff to reqwest. The HTTP stack still owns a normal body buffer after that handoff, and TLS, kernel, allocator, and device buffers can retain transient copies outside this crate’s control. Treat Transit plaintext and other request-body secret material as process-resident during the request lifecycle.

OpenBao’s /v1 prefix is a routing namespace, not a server-version compatibility guarantee. New deployments should configure OpenBaoCompatibilityPolicy::automatic_strict, or use an exact policy for a pinned server release. Exact, range, and strict policies perform one public, token-free, namespace-free health probe and cache the result per client. A range verifies only the backend that answered that probe; callers must provide backend affinity or restrict mixed clusters to the capability intersection for the entire range. Assumed and acknowledged-unknown-newer reports are deliberately not OpenBaoCompatibilityStatus::Verified. Raw transports bypass typed capability selection, and core profiles cannot establish compatibility for deployment-specific external plugins.

With the optional tracing feature, request spans include HTTP method, status, and a redacted URL path shape. Bodies, tokens, and namespaces are not logged, but even path shapes can reveal operational activity. Deployments with strict path-confidentiality requirements should suppress debug-level openbao.request spans, for example with EnvFilter::new("openbao=info"), or install a tracing layer that omits the path field.

Re-exports

pub use compatibility::OpenBaoCapabilityAvailability;

pub use compatibility::OpenBaoCapabilityEvidence;

pub use compatibility::OpenBaoCapabilityProfile;

pub use compatibility::OpenBaoCapabilityRange;

pub use compatibility::OpenBaoCapabilityStatus;

pub use compatibility::OpenBaoCompatibilityPolicy;

pub use compatibility::OpenBaoCompatibilityPolicyKind;

pub use compatibility::OpenBaoCompatibilityReport;

pub use compatibility::OpenBaoCompatibilityStatus;

pub use compatibility::OpenBaoHttpMethod;

pub use compatibility::OpenBaoOperation;

pub use compatibility::OpenBaoOperationDisposition;

pub use compatibility::OpenBaoVersion;

pub use compatibility::OpenBaoVersionRequirement;

pub use compatibility::UnknownNewerOpenBaoAcknowledgement;

pub use compatibility::openbao_operation;

pub use compatibility::openbao_operations;

pub use compatibility::openbao_profile_versions;

pub use duration::RenewalHint;

pub use duration::duration_to_bao_string;

pub use plugin::PluginMount;

pub use policy::AclCapability;

pub use policy::AclPolicyBuilder;

pub use posture::FipsPosture;

pub use posture::FipsPostureFinding;

pub use posture::FipsPostureNote;

pub use posture::FipsPostureReport;

pub use posture::FipsPostureSeverity;

pub use timestamp::OptionalTimestampExt;

pub use timestamp::TimestampExt;

pub use timestamp::parse_optional_rfc3339_timestamp;

pub use timestamp::parse_rfc3339_timestamp;

pub use futures_core;

pub use reqwest;

pub use sanitization;

pub use secrecy;

pub use serde_json;

pub use time;

Modules

auth

Authentication methods.

bootstrap

Idempotent administration bootstrap helpers.

compatibility

OpenBao server-version compatibility value types.

duration

Helpers for OpenBao duration strings.

plugin

Safe building blocks for typed custom OpenBao plugin wrappers.

policy

Helpers for building small OpenBao ACL policy documents.

posture

Best-effort posture helpers for crate-visible OpenBao configuration.

prelude

Common imports for application code using the OpenBao SDK.

secrets

Secret engine handles.

sys

System backend helpers.

timestamp

Optional RFC3339 timestamp parsing helpers.

tls

TLS configuration and types

Structs

Authenticated

Marker state for clients that carry an authentication token.

BoundedStringList

Bounded string list for custom plugin responses.

Certificate

Represents a server X509 certificate.

CertificateRevocationList

Represents a X509 certificate revocation list.

Client

Typed OpenBao HTTP client.

ClientBuilder

Builder for Client.

Empty

Empty JSON payload used for endpoints that do not require a body.

Identity

Represents a private key and X509 cert as a client certificate.

ListPageOptions

Shared pagination options for non-secret OpenBao string-list endpoints.

Method

The Request Method (VERB)

OffsetDateTime

A PlainDateTime with a UtcOffset.

OpenBaoConfig

Validated OpenBao client configuration.

ResponseEnvelope

Standard OpenBao response envelope for endpoints that return data.

RetryPolicy

Explicit retry policy for caller-approved idempotent requests.

SecretVec

Heap-allocated secret bytes with clear-on-drop behavior.

StatusCode

An HTTP status code (status-code in RFC 9110 et al.).

Unauthenticated

Marker state for clients that do not yet have an authentication token.

Enums

Error

Errors returned by OpenBao client operations.

HeaderMode

Authentication header strategy.

HttpPolicy

Policy for non-TLS HTTP base URLs.

JsonValue

Represents any valid JSON value.

RetryableMethod

HTTP methods that are safe to use with Client::request_json_with_retry.

RootCertificateMode

TLS trust root handling.

TlsBackend

TLS implementation selected for an OpenBao client.

Constants

MAX_RESPONSE_STRINGS

Maximum number of strings accepted by the crate’s bounded list helpers.

Traits

ExposeSecret

Expose a reference to an inner secret

ListEntries

Shared accessor trait for OpenBao list responses.

SecureSanitize

Clear the currently reachable sensitive contents owned by a value.

Functions

deserialize_bounded_string_vec

Deserializes a bounded vector of strings.

sanitize_bytes

Clear a mutable byte slice.

validate_endpoint_path

Validates an OpenBao endpoint-style path and returns normalized segments.

validate_mount_path

Validates an OpenBao mount-style path and returns normalized path segments.

Type Aliases

OpenBao

Backwards-friendly public name for the OpenBao client.

Result

Result alias used by this crate.

SecretString

Secret string type.

SharedClient

Authenticated client wrapped in std::sync::Arc for sharing across tasks.