Vaultx.Secrets.Transit.Keys (Vaultx v0.7.0)

Enterprise key management for HashiCorp Vault Transit secrets engine.

This module provides comprehensive cryptographic key management functionality for enterprise applications, including key creation, configuration, rotation, import/export, and complete lifecycle management operations. It supports industry-standard algorithms with enterprise-grade security and compliance.

Enterprise Key Management Capabilities

Create keys with advanced algorithms and enterprise configurations
Read comprehensive key information and security metadata
Update key configurations and security policies
Automated and manual key rotation to new versions
Secure key material import and export with HSM integration
Safe key deletion with comprehensive safety checks
List and audit all available cryptographic keys
Enterprise backup and disaster recovery for key data

Supported Key Types

Symmetric Encryption Keys

aes128-gcm96 - AES-128 with GCM (96-bit nonce)
aes256-gcm96 - AES-256 with GCM (96-bit nonce, default)
chacha20-poly1305 - ChaCha20-Poly1305 AEAD

Asymmetric Keys

rsa-2048, rsa-3072, rsa-4096 - RSA keys
ecdsa-p256, ecdsa-p384, ecdsa-p521 - ECDSA keys
ed25519 - Ed25519 keys

Special Purpose Keys

hmac - HMAC key generation and verification
managed_key - External managed keys (Enterprise)

Usage Examples

# Create a new AES key
{:ok, _} = Vaultx.Secrets.Transit.Keys.create("my-app-key", "aes256-gcm96")

# Create a derived key for multi-tenant encryption
{:ok, _} = Vaultx.Secrets.Transit.Keys.create("tenant-key", "aes256-gcm96",
  derived: true, convergent_encryption: true)

# Read key information
{:ok, key_info} = Vaultx.Secrets.Transit.Keys.read("my-app-key")

# Update key configuration
:ok = Vaultx.Secrets.Transit.Keys.update_config("my-app-key", %{
  deletion_allowed: true,
  min_encryption_version: 2
})

# Rotate key to new version
:ok = Vaultx.Secrets.Transit.Keys.rotate("my-app-key")

# List all keys
{:ok, keys} = Vaultx.Secrets.Transit.Keys.list()

# Export key material (if exportable)
{:ok, key_data} = Vaultx.Secrets.Transit.Keys.export("my-key", "encryption-key")

# Delete key (if deletion allowed)
:ok = Vaultx.Secrets.Transit.Keys.delete("old-key")

Key Configuration Options

Creation Options

:derived - Enable key derivation for multi-tenant use
:convergent_encryption - Enable deterministic encryption
:exportable - Allow key material export
:allow_plaintext_backup - Allow plaintext key backup
:auto_rotate_period - Automatic rotation period
:key_size - Key size for variable-size algorithms

Update Options

:min_decryption_version - Minimum version for decryption
:min_encryption_version - Minimum version for encryption
:deletion_allowed - Allow key deletion
:auto_rotate_period - Update rotation period

Security Considerations

Keys cannot be deleted by default (must enable deletion_allowed)
Exported keys should be handled with extreme care
Key rotation creates new versions without invalidating old ones
Minimum version settings can prevent use of compromised key versions
Convergent encryption requires careful nonce management

API Compliance

Fully implements HashiCorp Vault Transit key management:

Summary

Types

config_opts()

Key configuration options.

create_opts()

Key creation options.

key_info()

Key information structure.

Functions

create(name, key_type \\ "aes256-gcm96", opts \\ [])

Creates a new named encryption key.

delete(name, opts \\ [])

Deletes a named encryption key.

list(opts \\ [])

Lists all available encryption keys.

read(name, opts \\ [])

Reads information about a named encryption key.

rotate(name, opts \\ [])

Rotates a named encryption key to create a new version.

update_config(name, config, opts \\ [])

Updates configuration for a named encryption key.

Types

config_opts()

@type config_opts() :: [
  min_decryption_version: non_neg_integer(),
  min_encryption_version: non_neg_integer(),
  deletion_allowed: boolean(),
  exportable: boolean(),
  allow_plaintext_backup: boolean(),
  auto_rotate_period: String.t()
]

Key configuration options.

create_opts()

@type create_opts() :: [
  derived: boolean(),
  convergent_encryption: boolean(),
  exportable: boolean(),
  allow_plaintext_backup: boolean(),
  auto_rotate_period: String.t(),
  key_size: pos_integer(),
  managed_key_name: String.t(),
  managed_key_id: String.t()
]

Key creation options.

key_info()

@type key_info() :: %{
  name: String.t(),
  type: String.t(),
  derived: boolean(),
  exportable: boolean(),
  allow_plaintext_backup: boolean(),
  keys: map(),
  min_decryption_version: non_neg_integer(),
  min_encryption_version: non_neg_integer(),
  deletion_allowed: boolean(),
  supports_encryption: boolean(),
  supports_decryption: boolean(),
  supports_derivation: boolean(),
  supports_signing: boolean(),
  imported: boolean(),
  auto_rotate_period: String.t()
}

Key information structure.

Functions

create(name, key_type \\ "aes256-gcm96", opts \\ [])

@spec create(String.t(), String.t(), keyword()) :: :ok | {:error, term()}

Creates a new named encryption key.

Parameters

name - The name of the encryption key to create
key_type - The type of key to create (default: "aes256-gcm96")
opts - Key creation options

Options

:mount_path - Transit engine mount path (default: "transit")
:derived - Enable key derivation (default: false)
:convergent_encryption - Enable convergent encryption (default: false)
:exportable - Allow key export (default: false)
:allow_plaintext_backup - Allow plaintext backup (default: false)
:auto_rotate_period - Automatic rotation period (default: "0")
:key_size - Key size for variable-size algorithms
:managed_key_name - Name of managed key (for managed_key type)
:managed_key_id - UUID of managed key (for managed_key type)

Returns

:ok - Key created successfully
{:error, reason} - Key creation failed

Examples

iex> create("my-app-key", "aes256-gcm96")
:ok

iex> create("tenant-key", "aes256-gcm96", derived: true, convergent_encryption: true)
:ok

iex> create("signing-key", "ed25519", exportable: true)
:ok

delete(name, opts \\ [])

@spec delete(
  String.t(),
  keyword()
) :: :ok | {:error, term()}

Deletes a named encryption key.

Note: The key must have deletion_allowed set to true before it can be deleted.

Parameters

name - The name of the encryption key to delete
opts - Additional options

Options

:mount_path - Transit engine mount path (default: "transit")

Returns

:ok - Key deleted successfully
{:error, reason} - Key deletion failed

Examples

iex> delete("old-key")
:ok

list(opts \\ [])

@spec list(keyword()) :: {:ok, [String.t()]} | {:error, term()}

Lists all available encryption keys.

Parameters

opts - Additional options

Options

:mount_path - Transit engine mount path (default: "transit")

Returns

{:ok, keys} - List of key names
{:error, reason} - List operation failed

Examples

iex> list()
{:ok, ["key1", "key2", "key3"]}

read(name, opts \\ [])

@spec read(
  String.t(),
  keyword()
) :: {:ok, key_info()} | {:error, term()}

Reads information about a named encryption key.

Parameters

name - The name of the encryption key to read
opts - Additional options

Options

:mount_path - Transit engine mount path (default: "transit")

Returns

{:ok, key_info} - Key information retrieved successfully
{:error, reason} - Key read failed

Examples

iex> read("my-app-key")
{:ok, %{name: "my-app-key", type: "aes256-gcm96", ...}}

rotate(name, opts \\ [])

@spec rotate(
  String.t(),
  keyword()
) :: :ok | {:error, term()}

Rotates a named encryption key to create a new version.

Parameters

name - The name of the encryption key to rotate
opts - Additional options

Options

:mount_path - Transit engine mount path (default: "transit")

Returns

:ok - Key rotated successfully
{:error, reason} - Key rotation failed

Examples

iex> rotate("my-app-key")
:ok

update_config(name, config, opts \\ [])

@spec update_config(String.t(), map(), keyword()) :: :ok | {:error, term()}

Updates configuration for a named encryption key.

Parameters

name - The name of the encryption key to update
config - Configuration updates to apply
opts - Additional options

Options

:mount_path - Transit engine mount path (default: "transit")

Configuration Options

:min_decryption_version - Minimum version for decryption
:min_encryption_version - Minimum version for encryption
:deletion_allowed - Allow key deletion
:exportable - Allow key export (cannot be disabled once set)
:allow_plaintext_backup - Allow plaintext backup (cannot be disabled once set)
:auto_rotate_period - Automatic rotation period

Returns

:ok - Key configuration updated successfully
{:error, reason} - Key update failed

Examples

iex> update_config("my-app-key", %{deletion_allowed: true})
:ok

iex> update_config("my-app-key", %{min_encryption_version: 2, auto_rotate_period: "24h"})
:ok