HashiCorp Vault Ops: Practical Steps for Rekeying Unseal Keys

Vault Unseal Keys are critical material that should be refreshed whenever you rotate operators or revisit the threshold. Rekey is a standard procedure you can run against a live cluster, but it comes with several operational pitfalls.

This article walks through the differences between Shamir-based manual unseal and Auto Unseal environments, with representative CLI procedures, a comparison table, and key exam takeaways.

Rekey Fundamentals and Terminology

A Vault Rekey updates the configuration of the Unseal Key (the N-of-M Shamir shares). Specifically, it changes the share count (M) or threshold (N), or introduces/updates PGP encryption for distribution. Rekey is distinct from vault operator rotate, which rotates the encryption key (data encryption key) itself.

In Auto Unseal setups (auto-unsealing via cloud KMS, etc.), the Unseal Key is not used in day-to-day operations. Instead, a Recovery Key is provisioned, and Rekey targets the Recovery Key (pass the -recovery flag to the command).

Rekey can be performed while the cluster is running and usually does not interrupt service. However, while it is in flight, strict handling of the nonce and share submissions is required.

• Typical goals: operator turnover, threshold review, increasing/decreasing share count, introducing PGP for distribution protection
• Target differences: manual unseal = Unseal Key; Auto Unseal = Recovery Key (-recovery)
• Impact on operations: typically no downtime needed (but reserve a window anyway)
• Security: do not hold old and new shares simultaneously; transfer over a secure channel

Conceptual flow of a Rekey (Shamir manual unseal)

┌───────────────────────┐           ┌─────────────────────┐
│  Operators (旧 Unseal Keys 保有) │           │    Vault Leader     │
└───────────────┬──────────┘           └───────────┬─────────┘
                 │ 旧 Unseal Key を N-of-M で入力 + Nonce            │
                 ▼                                              │
          ┌──────────────────┐                                 │
          │ 旧マスターキー復元 │  ←――――――――――――――――――――――――――――――┘
          └─────────┬──────┘
                    │ 新構成(M', N')で分割（Shamir）
                    ▼
          ┌──────────────────┐
          │ 新しい share 群   │  → PGP で暗号化して各オーナーへ返却
          └──────────────────┘

Minimal pre-checks (perform within a safe maintenance window)

vault status
# コマンド仕様の再確認（バージョンによりオプション差異があるため）
vault operator rekey -help

Pre-execution Planning and Prerequisite Checks

Once Rekey starts, the transaction is identified by a nonce, and new shares are issued once the required number of old shares have been submitted. The nonce is also required to cancel or resume mid-flight, so a handling plan is essential.

Encrypting new shares with PGP for distribution is the recommended practice. Confirm both the public-key collection method (Keybase integration or per-user public key files) and that the count matches the new share count.

• Participants and roles: members holding the old Unseal/Recovery Keys, the executor, and the approver
• PGP preparation: gather Keybase usernames or base64-encoded public keys in advance
• Maintenance window: leave headroom for cases where share submissions drag on
• Audit and evidence: execution logs, who received which share, storage and disposal procedures
• Risk reduction: avoid long-term simultaneous possession of old and new shares; collect and destroy old shares immediately after distribution

Example of preparing PGP public keys

# Keybase を使う場合（新しい share 数と同数のユーザーを列挙）
# 例: alice, bob, carol の3名に配布
# 後続の -pgp-keys で keybase:alice のように指定

# ローカル公開鍵を使う場合（ASCII でエクスポートし base64 化）
# 各受領者の公開鍵をエクスポートして base64 ファイルに
# alice の例
gpg --export -a [email protected] | base64 > alice.pub.b64
# 受領者分を縦に並べたファイルを作成
cat alice.pub.b64 bob.pub.b64 carol.pub.b64 > pgp_keys.b64

Procedure: Rekey in a Manual Unseal (Shamir) Environment

In Shamir-based environments, use vault operator rekey to update the Unseal Key. Pass -init at the start to declare the new configuration (-key-shares and -key-threshold) and retain the returned nonce. Then submit N-of-M old Unseal Keys in sequence; the new shares will be returned.

When combining with PGP, use -pgp-keys (Keybase identifiers) or -pgp-keys-file (a file listing base64-encoded public keys). Vault encrypts each share with the matching public key before emitting it.

• Confirm availability of the old share owners before starting (mid-process dropouts are the biggest source of delay)
• Share the nonce, but do not post it in public locations (use a secure channel with limited membership)
• Distribute new shares as soon as they are emitted and confirm receipt; dispose of old shares appropriately
• Avoid distributing without PGP whenever possible (risk of misdelivery and eavesdropping)

Representative CLI sequence (Shamir)

# 1) Start the Rekey (e.g. new config = 5 shares / threshold 3, using Keybase)
vault operator rekey -init \
  -key-shares=5 -key-threshold=3 \
  -pgp-keys="keybase:alice,keybase:bob,keybase:carol,keybase:dave,keybase:erin"
# The output includes a Nonce. Record it securely.
# Nonce: 7f4b9c1a-... (example)

# 2) Submit the old Unseal Keys N times (e.g. 3) to advance progress
vault operator rekey -nonce=7f4b9c1a-... -key=<old_unseal_key_1>
vault operator rekey -nonce=7f4b9c1a-... -key=<old_unseal_key_2>
vault operator rekey -nonce=7f4b9c1a-... -key=<old_unseal_key_3>
# Once the threshold is reached, the new shares (PGP-encrypted) are emitted

# Check progress (subcommand availability varies by version)
vault operator rekey -status -nonce=7f4b9c1a-...

# To cancel (nonce required)
vault operator rekey -cancel -nonce=7f4b9c1a-...

Procedure: Rekey the Recovery Key in an Auto Unseal Environment

In Auto Unseal configurations, day-to-day unsealing is delegated to KMS (or HSM), so the Rekey target is the Recovery Key. The conceptual flow is the same as Shamir; execute with the -recovery flag.

Because the Recovery Key is used for emergency recovery and certain operations, distribution and storage demand the same strictness as the Unseal Key. Rotation on the cloud KMS side is a separate procedure and independent of Rekey.

• Use the -recovery flag for start, progress, and cancel commands
• Revisit the threshold and share count to fit your operational design
• Do not confuse this with KMS-side key rotation (Vault's Recovery Key is a separate concern)

Representative CLI sequence (Auto Unseal / Recovery Key)

# 1) Start the Recovery Key Rekey
vault operator rekey -recovery -init \
  -key-shares=5 -key-threshold=3 \
  -pgp-keys-file=pgp_keys.b64
# Record the Nonce

# 2) Submit threshold-many old Recovery Keys
vault operator rekey -recovery -nonce=<Nonce> -key=<old_recovery_key_1>
vault operator rekey -recovery -nonce=<Nonce> -key=<old_recovery_key_2>
vault operator rekey -recovery -nonce=<Nonce> -key=<old_recovery_key_3>

# Check status or cancel as needed
vault operator rekey -recovery -status -nonce=<Nonce>
vault operator rekey -recovery -cancel -nonce=<Nonce>

Comparing Rekey with Related Operations (Selection Guide)

These operations have similar-sounding names and are easy to confuse, so it helps to compare purpose, impact, and command side by side. This is also a frequently tested topic on the exam.

In particular, Rekey (re-splitting the Unseal/Recovery Key) and Rotate (rotating the data encryption key) are different operations.

• Rekey reconfigures shares (number of holders, threshold, PGP distribution)
• Rotate advances the generation of the data encryption key (storage re-encryption proceeds in the background)
• In Auto Unseal environments, rekey targets the Recovery Key (-recovery)

Example: rotating the data encryption key (reference)

# Take care not to confuse with Rekey
vault operator rotate
# Check progress and key generation via audit logs or metrics (environment-dependent)

Troubleshooting and Exam Perspective

The most common stumbling blocks are losing the nonce and PGP key mismatches. If the start-time configuration (share count, threshold, PGP key count) is misaligned, the final outputs will not line up and you will have to redo the operation. The nonce is required for resume and cancel as well, so store it both securely and reliably.

On the exam, expect questions on which key is the target for each configuration (manual unseal = Unseal, Auto Unseal = Recovery), what the purpose is (the Rekey vs. Rotate distinction), and the value of secure distribution via PGP.

• Nonce management: losing it makes resume and cancel difficult. Share via a secure channel and finish the operation quickly.
• PGP count alignment: match the new share count with the number of public keys (for Keybase, the user count)
• Participant time commitment: plan to avoid timeouts or rollovers into the next day while waiting for input
• Logging: enable audit logs and record who performed which operation
• Drills: simulate the procedure in a staging environment before doing it in production

Decryption of a PGP-encrypted share (performed locally by each recipient)

# Example assuming the received share is PGP-encrypted
# Actual output format depends on environment and options

echo "<encrypted_share_base64>" | base64 -d | gpg --decrypt
# Store the decrypted plaintext share securely; never forward or redistribute it

Check Your Understanding

Frequently Asked Questions