Learn Secret Management - Core Architecture & Initialization Operations (Raft Storage & Unsealing)

#Introduction

In episode 1 you understood why OpenBao is the choice: open source, compatible with Vault, and feature-rich. Episode 2 dives into the most fundamental and simultaneously most misunderstood part: what happens inside OpenBao the first time it is run.

The two concepts you must understand here are the storage backend (where data is placed) and seal/unseal (how data is unlocked). After this episode, you will know why a newly initialized OpenBao server always starts in a sealed state, and why the unseal keys must be held by the right people.

#OpenBao's Core Architecture

#Storage Backend: Raft Integrated Storage vs Consul

The storage backend is where OpenBao stores its persistent data — but it should be emphasized from the start: this storage never stores plaintext data. Everything that enters passes through the barrier encryption layer before being written. The main storage backend options in production:

Raft is the most sensible choice for most teams because OpenBao handles consistency and replication itself. Consul remains relevant in organizations that already operate a well-maintained Consul infrastructure. We will examine this choice more deeply in episode 15 on high availability.

#OpenBao Core & the Barrier Engine

At the center of OpenBao's architecture is the core — the main engine that processes every API request. One of its most important components is the barrier, the encryption layer that protects all data entering and leaving storage.

Here is the flow in short: a request arrives at the core, is loaded with a token and policy, and when data is written, the barrier encrypts the data with the master key before storing it in the storage backend. When read, the barrier decrypts it again. Because encryption happens at the barrier, not at storage, no matter how compromised the storage backend is, data never leaks in its original form.

#The Initialization Process

When a server is first run, OpenBao is in an uninitialized state — it has no master key at all. This is where bao operator init comes in.

#Shamir's Secret Sharing: The Master Key Becomes Unseal Keys

Initialization produces the master key — the key that locks the barrier. The problem is that storing the master key intact in one place creates a single point of failure. If it is lost, all data can never be unlocked again. The solution is Shamir's Secret Sharing.

Shamir's principle is simple yet elegant: the master key is split into N pieces called unseal keys, and reassembling it requires at least K pieces. This scheme is written as K-of-N:

The higher K is, the more secure — but the harder it is when you actually need to unseal. Common production practice: 3-of-5, distributed to five different people. No single person can unseal OpenBao alone, but a majority always can.

Run initialization with your desired scheme:

bao operator init -key-shares=5 -key-threshold=3

The output will display five unseal keys and one root token. Store them all securely — for example, distributed among team members in separate locations — because this output will never be shown again.

#Manual Unsealing

After initialization, every time the server is restarted, OpenBao enters a sealed state — the barrier is locked and data cannot be accessed. To unlock it, you must enter unseal keys until the threshold is reached:

bao operator unseal
bao operator unseal
bao operator unseal
bao status

Each bao operator unseal asks for one unseal key. Once K correct unseal keys have been entered, the status changes to Unsealed: true and the server is ready to serve requests. Until the threshold is reached, the data remains safe — no single key is enough on its own.

Note that a sealed server is not dead — the status endpoint still responds, which is how you know the server's condition. What is locked is the barrier inside it.

#The Auto-Unseal Mechanism

Manually unsealing every time the server reboots is a real operational burden — and dangerous, because it forces unseal keys to be brought onto the server machine. The solution is auto-unseal: the master key is wrapped with a key from a cloud KMS, so when the server boots, OpenBao can unseal itself without human intervention.

storage "raft" {
  path = "/data/openbao"
}
 
seal "awskms" {
  region     = "ap-southeast-1"
  kms_key_id = "alias/openbao-unseal"
}
 
listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = true
}
 
disable_mlock = false

Supported providers include AWS KMS, GCP Cloud KMS, and Azure Key Vault. The benefit is not just convenience: because unseal keys are no longer stored on the server, the risk of key theft also drops dramatically. We will go deeper into this auto-unseal concept with full configuration in episode 16.

#Root Token Management

At initialization, OpenBao also prints the root token — a token with unlimited privileges (superuser). In dev mode, the root token is indeed used for practice. In production, the root token is a threat that must be handled seriously.

#Root Token Risks

• Absolute privileges — the holder can do anything, including deleting all secrets and disabling engines.
• Unlimited — no TTL, so it never expires automatically.
• A prime target for attackers — one leaked token means full control over the system.

#Revocation Best Practices in Production

• Revoke it as soon as setup is complete — use bao token revoke <root-token-id> once all initial operations are done. Normal operations never need the root token.
• Use dedicated policies and tokens for each task — admins, operators, and developers get rights matching their roles.
• Store the root token encrypted if it truly must be archived — for example, in a vault opened through a multi-approval process.
• Test recovery periodically — make sure the team can still unseal without the root token before actually deleting it.

#Conclusion

In this episode 2, you understood OpenBao's core architecture: storage backends with Raft and Consul, the barrier engine that encrypts all data, initialization with K-of-N Shamir secret sharing, manual unsealing with bao operator unseal, KMS-based auto-unseal, and strict root token management.

Key takeaways:

• The storage backend never stores plaintext — all data is protected by the barrier before entering storage.
• Shamir K-of-N is a guarantee of collective security — 3-of-5 is the commonly used balance point.
• Unseal keys are only printed once — distribute and protect them as if your life depended on it.
• The root token is revoked after setup — production operations run with policy-based tokens, not superuser.

In the next episode, episode 3, we start using OpenBao for the most basic thing: the KV Secrets Engine — how to store and read secrets with bao kv put, bao kv get, and bao kv list, plus a full comparison of KV v1 versus KV v2, including versioning, metadata, soft delete, and permanent destroy. Get your dev-mode server ready, because from this episode on there will be secrets actually stored!