Vaultx.Sys.Seal (Vaultx v0.7.0)

View Source

HashiCorp Vault seal operations.

This module provides seal management capabilities for Vault, allowing you to seal the Vault instance. Sealing a Vault prevents access to all secrets and requires unsealing before the Vault can be used again.

Seal Operations

Core Functionality

  • Seal Vault: Immediately seal the Vault instance
  • Security Control: Prevent access to all secrets
  • Emergency Response: Quickly secure Vault in emergency situations
  • HA Mode Support: Seal active nodes in High Availability configurations

Security Features

  • Immediate Effect: Sealing takes effect immediately
  • Complete Protection: All secrets become inaccessible
  • Authentication Required: Requires root policy or sudo capability
  • Audit Trail: Seal operations are logged in audit devices

Important Security Notes

Restricted Endpoint

  • Must be called from the root namespace
  • Requires root policy or sudo capability on the path
  • Cannot be undone without unsealing process

High Availability Considerations

  • Only active nodes can be sealed via API
  • Standby nodes should be restarted to achieve same effect
  • Sealing active node may trigger failover to standby

Operational Impact

  • All client requests will fail after sealing
  • Vault must be unsealed before normal operations can resume
  • Consider impact on dependent applications and services

API Compliance

Fully implements HashiCorp Vault Seal API:

Usage Examples

Basic Seal Operation

{:ok, _} = Vaultx.Sys.Seal.seal()

Seal with Custom Options

{:ok, _} = Vaultx.Sys.Seal.seal(timeout: 30_000)

Error Handling

case Vaultx.Sys.Seal.seal() do
  {:ok, _} ->
    IO.puts("Vault successfully sealed")
  {:error, error} ->
    IO.puts("Failed to seal Vault: #{error.message}")
end

Seal Process

When a seal operation is performed:

  1. Immediate Effect: Vault stops serving requests immediately
  2. Memory Clearing: Encryption keys are removed from memory
  3. State Change: Vault transitions to sealed state
  4. Client Impact: All subsequent requests return sealed errors
  5. Audit Logging: Seal operation is recorded in audit logs

Recovery Process

After sealing, Vault must be unsealed using:

  • Unseal keys (Shamir's Secret Sharing)
  • Auto-unseal mechanisms (Cloud KMS, HSM, etc.)
  • Recovery keys (for auto-unseal configurations)

Use Cases

Emergency Response

  • Security incident response
  • Suspected compromise
  • Maintenance windows
  • Compliance requirements

Operational Scenarios

  • Planned maintenance
  • Infrastructure changes
  • Security audits
  • Testing procedures

High Availability Operations

  • Controlled failover
  • Node maintenance
  • Cluster rebalancing
  • Disaster recovery testing

Summary

Functions

check_seal_permission(opts \\ [])

Checks if the current token has permission to seal the Vault.

safe_seal(opts \\ [])

Performs a safe seal operation with pre-flight checks.

seal(opts \\ [])

Seals the Vault.

Functions

check_seal_permission(opts \\ [])

@spec check_seal_permission(Vaultx.Types.options()) ::
  :ok | {:error, Vaultx.Base.Error.t()}

Checks if the current token has permission to seal the Vault.

This is a convenience function that attempts to determine if the seal operation would succeed based on current authentication and authorization.

Parameters

  • opts - Request options (optional)

Returns

Returns :ok if seal permission is available, or {:error, Error.t()} if permission is denied or cannot be determined.

Examples

case Vaultx.Sys.Seal.check_seal_permission() do
  :ok ->
    IO.puts("Seal permission available")
  {:error, error} ->
    IO.puts("Seal permission denied: #{error.message}")
end

Important Notes

  • This is a best-effort check and may not be 100% accurate
  • Actual seal operation may still fail due to various factors
  • Use this for pre-flight checks in automation scenarios

safe_seal(opts \\ [])

@spec safe_seal(Vaultx.Types.options()) ::
  {:ok, Vaultx.Types.response()} | {:error, Vaultx.Base.Error.t()}

Performs a safe seal operation with pre-flight checks.

This function performs additional safety checks before sealing the Vault, including permission verification and optional confirmation prompts.

Parameters

  • opts - Options for the safe seal operation
    • :skip_permission_check - Skip permission verification (default: false)
    • :force - Skip all safety checks (default: false)
    • Other HTTP request options

Returns

Returns {:ok, response} on successful seal operation, or {:error, Error.t()} on failure or safety check failure.

Examples

# Safe seal with all checks
{:ok, _} = Vaultx.Sys.Seal.safe_seal()

# Skip permission check
{:ok, _} = Vaultx.Sys.Seal.safe_seal(skip_permission_check: true)

# Force seal (skip all checks)
{:ok, _} = Vaultx.Sys.Seal.safe_seal(force: true)

Safety Checks

  1. Permission Check: Verifies seal capability
  2. Operational State: Ensures Vault is in appropriate state
  3. Confirmation: Optional confirmation for interactive use

seal(opts \\ [])

@spec seal(Vaultx.Types.options()) ::
  {:ok, Vaultx.Types.response()} | {:error, Vaultx.Base.Error.t()}

Seals the Vault.

This endpoint seals the Vault. In HA mode, only an active node can be sealed. Standby nodes should be restarted to get the same effect. Requires a token with root policy or sudo capability on the path.

Parameters

  • opts - Request options (optional)

Returns

Returns {:ok, response} on successful seal operation, or {:error, Error.t()} on failure.

Examples

{:ok, _} = Vaultx.Sys.Seal.seal()

# With custom timeout
{:ok, _} = Vaultx.Sys.Seal.seal(timeout: 30_000)

Important Notes

  • Sealing takes effect immediately
  • All subsequent requests will fail until Vault is unsealed
  • In HA mode, only the active node can be sealed via API
  • Standby nodes should be restarted to achieve the same effect