Seal/unseal mechanism in OpenBao
Overview
One of OpenBao’s foundational security concepts is the seal/unseal mechanism, which ensures that the system remains cryptographically inaccessible unless a sufficient quorum of trusted parties participates in the unsealing process. This article demonstrates the theoretical groundwork of this mechanism, focusing on cryptographic principles and key management strategies that enable secure, distributed control over the master encryption key.
At a high level, the sealing/unsealing mechanism in OpenBao exists to protect the confidentiality and integrity of all stored secrets, even when the storage backend (e.g. files, network-attached storage) is compromised. The major goals are:
-
Data (secrets, policies, key shares) must remain encrypted, so someone with access to raw storage cannot simply read sensitive info.
-
Secrets shouldn’t be available until authorized operators/mechanisms provide key shares, even if the service process is restarted or replicas are down.
Work principles
Shamir’s Secret Sharing
OpenBao uses Shamir’s Secret Sharing (SSS), a threshold-based cryptographic algorithm. SSS allows a secret to be divided into shares such that:
-
Any subset of (threshold) or more shares ( ) can reconstruct .
-
Any subset of fewer than shares reveals zero information about .
If , all shares are needed to reconstruct the secret .
The secret is encoded as the constant term of a random polynomial of degree :
where are randomly chosen coefficients. Each share is a point computed as .
A secret can be reconstructed using the following formula:
This approach offers various advantages, such as:
-
Information-theoretic security. This means that the algorithm remains secure against adversaries with infinite computing power.
-
Scalability. The amount shareholders can be increased up to the dimension of the field where the computations are performed, while may remain the same.
-
Dynamism. The secret can remain unchanged while the polynomial may be changed occasionally to construct a new share for each participant.
-
Flexibility. In hierarchal systems, each participant can be given different number of shares based on their importance. For example, with , a leader could reconstruct a secret alone with 4 shares, while four of their employees with one share each must combine their shares to reconstruct the secret.
However, there is also a weakness — a single point of failure. The secret has to exist in one place before being split into shares and when it is reassembled. This produces two possible attack points.
In OpenBao context, the secret being encrypted by SSS is the unseal key, which is used to decrypt the root key (master key).
Seal
When sealing is initiated, the root key is removed from memory. The system enters a sealed state, where it refuses to perform any operations involving decryption or secret access. Only minimal API remains active, such as unseal endpoints. This simplicity allows quickly sealing a cluster if an adversary intrusion is detected.
To restore the root key, it is required to complete the unsealing process.
Unseal
When unsealing is initiated, nodes submit their shares to a specific endpoint. Once valid shares are received, OpenBao reconstructs the unseal key. After that, the root key gets decrypted and the cluster transitions into the unsealed state. It will remain in such state until one of the following things happen:
-
It is resealed via the API.
-
The server is restarted.
-
The OpenBao’s storage layer encounters an unrecoverable error.
Auto Unseal
Manually unsealing the cluster using SSS is a daunting task, so Auto Unseal was introduced to offer a better experience. The idea is to delegate the responsibility of securing the unseal key from users to a trusted device (HSM) or service (KMS). At startup, OpenBao will request that service or device to decrypt the root key received from storage.
Apart from unsealing, there are other operations that require a quorum of users. With Auto Unseal enabled, these operation require recovery key fragments instead of the unseal key shares. While the initialization process with SSS produces the unseal key shares, initialization with Auto Unseal produces the recovery key fragments.
The recovery key fragments are generated from an internal recovery key that is split via SSS just like the unseal key. In ADPS, the Auto Unseal mechanism is implemented for PKCS 11.
|
IMPORTANT
Recovery keys act as a mean of authorization, hence they cannot decrypt the root key and unseal the cluster if the Auto Unseal mechanism isn’t working. If the seal mechanism or its keys are permanently deleted, then the OpenBao cluster cannot be recovered, even from backups.
|