HashiCorp Vault initialization operations.

This module provides initialization capabilities for Vault, allowing you to initialize a new Vault server and generate the initial root token and unseal keys. Vault must be initialized before it can be unsealed and used.

Initialization Operations

Core Functionality

• Initialize Vault: Set up a new Vault server with root token and unseal keys
• Check Status: Determine if Vault has been initialized
• Shamir Secret Sharing: Configure threshold-based unsealing
• PGP Encryption: Encrypt unseal keys and root token with PGP keys

Initialization Process

• One-time Operation: Can only be performed once per Vault server
• Root Token Generation: Creates the initial root token for administration
• Unseal Key Generation: Creates key shares for unsealing Vault
• Threshold Configuration: Sets minimum number of keys required to unseal

Important Security Notes

Critical Security Considerations

• Initialization is a one-time operation that cannot be repeated
• Root token has unlimited privileges and should be secured immediately
• Unseal keys should be distributed among trusted operators
• Consider using PGP encryption for key protection

Key Management

• Store unseal keys securely and separately
• Distribute keys among multiple trusted operators
• Consider using auto-unseal mechanisms for production
• Revoke and regenerate root token after initial setup

API Compliance

Fully implements HashiCorp Vault Init API:

• Init API
• Vault Concepts

Usage Examples

Basic Initialization

{:ok, init_result} = Vaultx.Sys.Init.initialize(%{
  secret_shares: 5,
  secret_threshold: 3
})

# Store these securely!
root_token = init_result.root_token
unseal_keys = init_result.keys

PGP-Encrypted Initialization

pgp_keys = [
  "-----BEGIN PGP PUBLIC KEY BLOCK-----...",
  "-----BEGIN PGP PUBLIC KEY BLOCK-----..."
]

{:ok, init_result} = Vaultx.Sys.Init.initialize(%{
  secret_shares: 3,
  secret_threshold: 2,
  pgp_keys: pgp_keys,
  root_token_pgp_key: "-----BEGIN PGP PUBLIC KEY BLOCK-----..."
})

Check Initialization Status

case Vaultx.Sys.Init.status() do
  {:ok, %{initialized: true}} ->
    IO.puts("Vault is already initialized")
  {:ok, %{initialized: false}} ->
    IO.puts("Vault needs to be initialized")
  {:error, error} ->
    IO.puts("Error checking status: #{error.message}")
end

Initialization Response

The initialization operation returns:

• keys: Array of unseal key shares (encrypted if PGP keys provided)
• keys_base64: Base64-encoded unseal keys
• root_token: Initial root token (encrypted if PGP key provided)
• recovery_keys: Recovery keys (for auto-unseal configurations)
• recovery_keys_base64: Base64-encoded recovery keys

Security Best Practices

Immediate Actions After Initialization

1. Securely store the root token and unseal keys
2. Distribute unseal keys among trusted operators
3. Unseal Vault using the required threshold of keys
4. Create initial policies and authentication methods
5. Revoke the initial root token and use policy-based access

Production Considerations

• Use auto-unseal mechanisms (Cloud KMS, HSM) when possible
• Implement proper key rotation procedures
• Monitor and audit all initialization activities
• Use PGP encryption for additional key protection