Class ApiKeyUtil

java.lang.Object
ai.pipestream.connector.util.ApiKeyUtil
@ApplicationScoped public class ApiKeyUtil extends Object
Utilities for API key generation and hashing.

API keys are:

  • Generated as secure random Base64 strings
  • Hashed with Argon2id before storage (current best practice)
  • Never stored in plaintext
  • Only returned once at creation/rotation time

Uses password4j library with Argon2id algorithm, which provides:

  • Resistance to GPU cracking attacks
  • Protection against side-channel attacks
  • Memory-hard algorithm (configurable memory cost)
  • Winner of Password Hashing Competition

  • Constructor Details

    • ApiKeyUtil

      public ApiKeyUtil()
      Default constructor for CDI proxying.

  • Method Details

    • generateApiKey

      public String generateApiKey()
      Generate a new secure random API key.

      Generates a cryptographically secure random byte array and encodes it as Base64. The result is URL-safe and suitable for HTTP headers.

      Returns:
      Base64-encoded API key (plaintext - must be hashed before storage)

    • hashApiKey

      public String hashApiKey(String plaintextApiKey)
      Hash an API key for secure storage.

      Uses Argon2id with the following parameters:

      • Memory cost: 64 MB
      • Iterations: 3
      • Parallelism: 4 threads
      • Hash length: 256 bits

      The hash includes a randomly generated salt and is stored in PHC string format.

      Parameters:
      plaintextApiKey - The plaintext API key
      Returns:
      Argon2id hash in PHC format suitable for database storage

    • verifyApiKey

      public boolean verifyApiKey(String plaintextApiKey, String storedHash)
      Verify an API key against a stored hash.

      Uses constant-time comparison to prevent timing attacks. Automatically detects the hashing algorithm from the PHC format.

      Parameters:
      plaintextApiKey - The plaintext API key to verify
      storedHash - The Argon2id hash from database (PHC format)
      Returns:
      true if the key matches the hash, false otherwise