Vaultx.Sys.Tools (Vaultx v0.7.0)

View Source

HashiCorp Vault tools operations.

This module provides a general set of cryptographic and utility tools available through Vault's system backend. These tools leverage Vault's cryptographic capabilities for various operations without requiring secrets storage.

Tools Features

Random Byte Generation

  • High-Quality Entropy: Generate cryptographically secure random bytes
  • Multiple Sources: Platform entropy, seal entropy, or mixed sources
  • Flexible Output: Configurable byte count and encoding formats
  • Enterprise Features: Entropy augmentation support in Vault Enterprise

Data Hashing

  • Multiple Algorithms: Support for SHA-2 and SHA-3 hash families
  • Flexible Input: Base64 encoded input data processing
  • Output Formats: Hex or Base64 encoded hash outputs
  • Cryptographic Security: Industry-standard hash algorithms

Important Notes

Authentication Required

  • All tools endpoints require valid authentication
  • Appropriate permissions needed for tool access
  • Some features may be restricted based on policy

Enterprise Features

  • Seal entropy source requires Vault Enterprise
  • Mixed entropy sources available in Enterprise editions
  • Platform entropy available in all editions

Input Validation

  • Hash input must be base64 encoded
  • Random byte counts have reasonable limits
  • Invalid parameters will return appropriate errors

API Compliance

Fully implements HashiCorp Vault Tools API:

Usage Examples

Random Byte Generation

# Generate 32 random bytes (default)
{:ok, random_data} = Vaultx.Sys.Tools.generate_random()
IO.puts("Random bytes: #{random_data.random_bytes}")

# Generate 64 bytes in hex format
{:ok, random_data} = Vaultx.Sys.Tools.generate_random(
  bytes: 64,
  format: "hex"
)

# Use platform entropy source
{:ok, random_data} = Vaultx.Sys.Tools.generate_random(
  bytes: 128,
  source: "platform"
)

Data Hashing

# Hash data with SHA-256 (default)
input_data = Base.encode64("Hello, World!")
{:ok, hash_result} = Vaultx.Sys.Tools.hash_data(input_data)
IO.puts("SHA-256 hash: #{hash_result.sum}")

# Hash with SHA-512 in base64 format
{:ok, hash_result} = Vaultx.Sys.Tools.hash_data(
  input_data,
  algorithm: "sha2-512",
  format: "base64"
)

# Hash with SHA-3
{:ok, hash_result} = Vaultx.Sys.Tools.hash_data(
  input_data,
  algorithm: "sha3-256"
)

Random Generation

Supported Sources

  • "platform": Platform's entropy source (default)
  • "seal": Entropy augmentation (Enterprise only)
  • "all": Mixed bytes from all available sources

Output Formats

  • "base64": Base64 encoded output (default)
  • "hex": Hexadecimal encoded output

Hash Algorithms

SHA-2 Family

  • "sha2-224": SHA-224 hash algorithm
  • "sha2-256": SHA-256 hash algorithm (default)
  • "sha2-384": SHA-384 hash algorithm
  • "sha2-512": SHA-512 hash algorithm

SHA-3 Family

  • "sha3-224": SHA3-224 hash algorithm
  • "sha3-256": SHA3-256 hash algorithm
  • "sha3-384": SHA3-384 hash algorithm
  • "sha3-512": SHA3-512 hash algorithm

Use Cases

Security Operations

  • Generate secure random tokens and keys
  • Create cryptographic nonces and salts
  • Hash sensitive data for comparison
  • Implement secure random number generation

Application Integration

  • Generate session tokens and identifiers
  • Create secure random passwords
  • Hash user inputs for verification
  • Implement cryptographic protocols

Development and Testing

  • Generate test data and fixtures
  • Create mock cryptographic values
  • Validate hash implementations
  • Test random number generation

Summary

Types

hash_result()

Hash computation result.

random_result()

Random bytes generation result.

Functions

generate_random(opts \\ [])

Generate high-quality random bytes.

generate_token(bytes \\ 32, opts \\ [])

Generate random bytes with automatic base64 encoding.

hash_data(input, opts \\ [])

Hash data using specified algorithm.

hash_string(data, opts \\ [])

Hash a string with automatic base64 encoding.

Types

hash_result()

@type hash_result() :: %{sum: String.t()}

Hash computation result.

random_result()

@type random_result() :: %{random_bytes: String.t()}

Random bytes generation result.

Functions

generate_random(opts \\ [])

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

Generate high-quality random bytes.

This endpoint returns high-quality random bytes of the specified length.

Parameters

  • opts - Options for random generation
    • :bytes - Number of bytes to return (default: 32)
    • :format - Output encoding: "base64" or "hex" (default: "base64")
    • :source - Entropy source: "platform", "seal", or "all" (default: "platform")
    • Other HTTP request options

Returns

Returns {:ok, random_result()} with random bytes, or {:error, Error.t()} on failure.

Examples

# Generate 32 random bytes (default)
{:ok, result} = Vaultx.Sys.Tools.generate_random()

# Generate 64 bytes in hex format
{:ok, result} = Vaultx.Sys.Tools.generate_random(
  bytes: 64,
  format: "hex"
)

# Use seal entropy (Enterprise)
{:ok, result} = Vaultx.Sys.Tools.generate_random(
  bytes: 128,
  source: "seal"
)

generate_token(bytes \\ 32, opts \\ [])

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

Generate random bytes with automatic base64 encoding.

This is a convenience function that generates random bytes and returns them as a base64 encoded string, suitable for use as tokens or keys.

Parameters

  • bytes - Number of bytes to generate (default: 32)
  • opts - Additional options (passed to generate_random/1)

Returns

Returns {:ok, String.t()} with base64 encoded random bytes, or {:error, Error.t()} on failure.

Examples

# Generate 32-byte token
{:ok, token} = Vaultx.Sys.Tools.generate_token()

# Generate 64-byte key
{:ok, key} = Vaultx.Sys.Tools.generate_token(64)

hash_data(input, opts \\ [])

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

Hash data using specified algorithm.

This endpoint returns the cryptographic hash of given data using the specified algorithm.

Parameters

  • input - Base64 encoded input data to hash
  • opts - Options for hashing
    • :algorithm - Hash algorithm to use (default: "sha2-256")
    • :format - Output encoding: "hex" or "base64" (default: "hex")
    • Other HTTP request options

Returns

Returns {:ok, hash_result()} with computed hash, or {:error, Error.t()} on failure.

Examples

# Hash with SHA-256 (default)
input = Base.encode64("Hello, World!")
{:ok, result} = Vaultx.Sys.Tools.hash_data(input)

# Hash with SHA-512 in base64 format
{:ok, result} = Vaultx.Sys.Tools.hash_data(
  input,
  algorithm: "sha2-512",
  format: "base64"
)

# Hash with SHA-3
{:ok, result} = Vaultx.Sys.Tools.hash_data(
  input,
  algorithm: "sha3-256"
)

hash_string(data, opts \\ [])

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

Hash a string with automatic base64 encoding.

This is a convenience function that automatically base64 encodes the input string before hashing, suitable for hashing plain text data.

Parameters

  • data - String data to hash
  • opts - Options for hashing (same as hash_data/2)

Returns

Returns {:ok, String.t()} with computed hash, or {:error, Error.t()} on failure.

Examples

# Hash a password
{:ok, hash} = Vaultx.Sys.Tools.hash_string("my-password")

# Hash with SHA-512
{:ok, hash} = Vaultx.Sys.Tools.hash_string(
  "sensitive-data",
  algorithm: "sha2-512"
)