balloon_hashing 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4d752a3421f8ab1942af7d85563993197f1980819b91cce288264e8bb2876e2d
+  data.tar.gz: 741d2a2ee1ce2a9963f3eccf0e3dbe9afdb1f6f649dd11e539b38341f97fd332
+SHA512:
+  metadata.gz: 35da97b6c18a7d8d956d89aba3cb8a38a61d200c9558bd384cff9e3d53abf530731f20bfd92ae9153b97d3c00a9f86514e4f23085588cb26f2bb1189d8e41914
+  data.tar.gz: 0bc74dc54f864811908e7e96a25d3e6ec282ce3fc65d3dbe5161a99cbb890c2be30994923338f8500b54571cdae243f0a197cc567b982b296969b781c8a10182

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suleyman Musayev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,242 @@
+# Balloon Hashing
+
+Pure Ruby implementation of the [Balloon Hashing](https://crypto.stanford.edu/balloon/) algorithm (Boneh, Corrigan-Gibbs, Schechter 2016) — a memory-hard password hashing function with provable security guarantees against sequential attacks.
+
+## Why Balloon Hashing?
+
+- **Memory-hard** — resistant to GPU and ASIC attacks by requiring large amounts of memory to compute
+- **Provably secure** — the only password hashing function with formal proofs of memory-hardness
+- **Simple design** — built on standard cryptographic primitives (SHA-256, SHA-512, BLAKE2b) with no custom block ciphers
+- **Tunable** — independent space cost (`s_cost`) and time cost (`t_cost`) parameters let you balance security against performance
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "balloon_hashing"
+```
+
+Or install directly:
+
+```
+gem install balloon_hashing
+```
+
+**Requirements:** Ruby >= 2.7.0, OpenSSL
+
+## Quick Start
+
+```ruby
+require "balloon_hashing"
+
+# Hash a password
+hash = BalloonHashing.create("my password")
+# => "$balloon$v=1$alg=sha256,s=1024,t=3$..."
+
+# Verify a password
+BalloonHashing.verify("my password", hash)  #=> true
+BalloonHashing.verify("wrong password", hash) #=> false
+```
+
+## Usage
+
+### Basic API
+
+The simplest way to use the gem — module-level convenience methods with sensible defaults:
+
+```ruby
+hash = BalloonHashing.create("password")
+BalloonHashing.verify("password", hash) #=> true
+```
+
+### Custom Parameters
+
+Adjust the cost parameters and algorithm to fit your security requirements:
+
+```ruby
+hash = BalloonHashing.create(
+  "password",
+  s_cost: 2048,          # space cost — number of blocks in memory (default: 1024)
+  t_cost: 4,             # time cost — number of mixing rounds (default: 3)
+  algorithm: "sha512"    # hash algorithm (default: "sha256")
+)
+
+BalloonHashing.verify("password", hash) #=> true
+```
+
+### Supported Algorithms
+
+| Algorithm | Output Size | Notes |
+|-----------|------------|-------|
+| `sha256`  | 32 bytes   | Default, widely available |
+| `sha512`  | 64 bytes   | Larger output, slightly slower |
+| `blake2b` | 64 bytes   | Fast, requires OpenSSL with BLAKE2 support |
+
+### Instance-Based API with `Hasher`
+
+For applications that need a configured hasher instance (e.g. different cost settings for different user roles):
+
+```ruby
+hasher = BalloonHashing::Hasher.new(
+  s_cost: 2048,
+  t_cost: 4,
+  algorithm: "sha512"
+)
+
+hash = hasher.create("password")
+hasher.verify("password", hash)   #=> true
+hasher.cost_matches?(hash)        #=> true
+```
+
+### Upgrading Cost Parameters (Rehash on Login)
+
+When you increase cost parameters, existing hashes still verify but use the old settings. Use `needs_rehash?` to transparently upgrade hashes when users log in:
+
+```ruby
+hasher = BalloonHashing::Hasher.new(s_cost: 2048, t_cost: 4)
+
+if hasher.verify(password, stored_hash)
+  if hasher.needs_rehash?(stored_hash)
+    # Re-hash with current (stronger) parameters
+    stored_hash = hasher.create(password)
+    save_to_database(stored_hash)
+  end
+
+  log_user_in
+end
+```
+
+### Strict Verification with `verify!`
+
+If you want to ensure the hash was created with the hasher's exact configuration:
+
+```ruby
+hasher = BalloonHashing::Hasher.new(s_cost: 2048, t_cost: 4)
+
+hasher.verify("password", hash)   # Works regardless of hash parameters
+hasher.verify!("password", hash)  # Raises BalloonHashing::InvalidHash if parameters don't match
+```
+
+### Pepper (Server-Side Secret)
+
+Add an optional server-side secret that is mixed into the hash via HMAC but never stored in the output string. This means a leaked database alone is not enough to crack passwords:
+
+```ruby
+# Module-level API
+hash = BalloonHashing.create("password", pepper: ENV["PASSWORD_PEPPER"])
+BalloonHashing.verify("password", hash, pepper: ENV["PASSWORD_PEPPER"])
+
+# Instance-based API — pepper is set once at construction
+hasher = BalloonHashing::Hasher.new(s_cost: 2048, t_cost: 4, pepper: ENV["PASSWORD_PEPPER"])
+hash = hasher.create("password")
+hasher.verify("password", hash) #=> true
+```
+
+> **Note:** The pepper must be the same for both `create` and `verify`. If you lose the pepper, all existing hashes become unverifiable. Store it securely (e.g. environment variable, secrets manager) separate from the database.
+
+### Low-Level Core API
+
+For advanced use cases, you can call the core algorithm directly:
+
+```ruby
+raw_hash = BalloonHashing::Core.balloon(
+  "password",       # password (String)
+  salt,             # salt (String, random bytes)
+  1024,             # s_cost (Integer)
+  3,                # t_cost (Integer)
+  "sha256"          # algorithm (String)
+)
+# => raw binary hash bytes
+```
+
+This returns raw bytes and does not generate salts or produce encoded strings.
+
+## Hash Format
+
+Encoded hashes follow a structured, self-describing format:
+
+```
+$balloon$v=1$alg=sha256,s=1024,t=3$<base64_salt>$<base64_hash>
+```
+
+| Field | Description |
+|-------|-------------|
+| `$balloon$` | Identifier prefix |
+| `v=1` | Format version |
+| `alg=sha256` | Hash algorithm |
+| `s=1024` | Space cost |
+| `t=3` | Time cost |
+| `<base64_salt>` | Base64-encoded salt |
+| `<base64_hash>` | Base64-encoded hash output |
+
+The format is forward-compatible — unknown parameter keys are ignored during decoding, so future versions can add new parameters without breaking existing hashes.
+
+## Cost Parameter Guidance
+
+The right cost parameters depend on your hardware and latency budget. As a starting point:
+
+| Use Case | `s_cost` | `t_cost` | Notes |
+|----------|----------|----------|-------|
+| Interactive login | 1024 | 3 | ~default, suitable for web apps |
+| Higher security | 2048–4096 | 3–4 | More memory, similar latency |
+| Offline/batch | 8192+ | 4+ | When latency is not a concern |
+
+**`s_cost`** (space cost) controls the number of hash-sized blocks held in memory. Each block is 32 bytes (SHA-256) or 64 bytes (SHA-512/BLAKE2b), so `s_cost: 1024` with SHA-256 uses ~32 KB of memory.
+
+**`t_cost`** (time cost) controls the number of mixing rounds over the buffer. Higher values increase computation time linearly.
+
+Benchmark on your target hardware and choose the highest values that stay within your latency budget.
+
+## Safety Limits
+
+To prevent accidental denial-of-service from misconfigured parameters:
+
+- `s_cost` is capped at `2^24` (~16 million blocks)
+- `t_cost` is capped at `2^20` (~1 million rounds)
+
+These limits apply to both direct calls and when decoding stored hashes, protecting against crafted hash strings with extreme values.
+
+## Error Handling
+
+```ruby
+BalloonHashing::Error        # Base error class (inherits StandardError)
+BalloonHashing::InvalidHash  # Raised for malformed or invalid encoded hash strings
+```
+
+`verify` and `cost_matches?` return `false` for invalid hashes rather than raising. If you need to distinguish "wrong password" from "corrupted hash", call the `Hasher#verify!` variant which raises `InvalidHash` on parameter mismatch.
+
+`create` raises `ArgumentError` for invalid input (non-String password, unsupported algorithm, invalid cost values).
+
+## Thread Safety
+
+All public APIs are thread-safe:
+
+- **`BalloonHashing::Core`** — each call allocates its own digest and buffer; no shared state
+- **`BalloonHashing::Password`** — all methods are stateless module functions
+- **`BalloonHashing::Hasher`** — instances are effectively immutable after construction
+
+`Hasher` instances can be safely shared across threads and stored as constants or in application configuration.
+
+## Security Notes
+
+- **Constant-time comparison** — password verification uses `OpenSSL.fixed_length_secure_compare` to prevent timing attacks
+- **Buffer zeroing** — the in-memory hash buffer is zeroed after use on a best-effort basis. Ruby's garbage collector may retain copies of intermediate data. For applications requiring stronger memory protection guarantees, consider a C extension wrapping `OPENSSL_cleanse` or `sodium_memzero`
+- **Pepper via HMAC** — when a pepper is provided, it is mixed using HMAC-SHA256 (not simple concatenation), eliminating length-ambiguity attacks. The pepper is never included in the encoded hash output
+
+## Development
+
+```bash
+git clone https://github.com/msuliq/balloon_hashing.git
+cd balloon_hashing
+bundle install
+bundle exec rake test
+```
+
+## References
+
+- Boneh, D., Corrigan-Gibbs, H., & Schechter, S. (2016). [Balloon Hashing: A Memory-Hard Function Providing Provable Protection Against Sequential Attacks](https://eprint.iacr.org/2016/027.pdf). IACR Cryptology ePrint Archive.
+
+## License
+
+Released under the [MIT License](LICENSE).

data/lib/balloon_hashing/base.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module BalloonHashing
+  class Error < StandardError; end
+  class InvalidHash < Error; end
+
+  DEFAULT_S_COST = 1024
+  DEFAULT_T_COST = 3
+  DEFAULT_ALGORITHM = "sha256"
+  DEFAULT_SALT_LENGTH = 16 # bytes
+end

data/lib/balloon_hashing/core.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module BalloonHashing
+  # Core implementation of the Balloon Hashing algorithm.
+  #
+  # Reference: Boneh, Corrigan-Gibbs, Schechter (2016)
+  # "Balloon Hashing: A Memory-Hard Function Providing Provable
+  # Protection Against Sequential Attacks"
+  #
+  # Thread safety: all public methods are stateless and safe to call
+  # concurrently from multiple threads. Each invocation allocates its
+  # own digest and buffer with no shared mutable state.
+  module Core
+    DELTA = 3 # Number of dependencies per block (from the paper)
+    MAX_S_COST = 2**24 # ~16M blocks — safety ceiling to prevent accidental OOM
+    MAX_T_COST = 2**20 # ~1M rounds — safety ceiling to prevent CPU freeze
+
+    SUPPORTED_ALGORITHMS = {
+      "sha256" => "SHA256",
+      "sha512" => "SHA512",
+      "blake2b" => "BLAKE2b512"
+    }.freeze
+
+    module_function
+
+    # Check whether an algorithm name is supported.
+    #
+    # @param algorithm [String]
+    # @return [Boolean]
+    def valid_algorithm?(algorithm)
+      SUPPORTED_ALGORITHMS.key?(algorithm.to_s.downcase)
+    end
+
+    # Validate an algorithm name, raising if unsupported.
+    #
+    # @param algorithm [String]
+    # @raise [ArgumentError] if the algorithm is not supported
+    # @return [void]
+    def validate_algorithm!(algorithm)
+      return if valid_algorithm?(algorithm)
+
+      raise ArgumentError,
+        "Unsupported algorithm: #{algorithm}. " \
+        "Supported: #{SUPPORTED_ALGORITHMS.keys.join(', ')}"
+    end
+
+    # Compute a Balloon hash.
+    #
+    # @param password [String] the password to hash
+    # @param salt [String] the salt (random bytes)
+    # @param s_cost [Integer] space cost (number of blocks in buffer)
+    # @param t_cost [Integer] time cost (number of mixing rounds)
+    # @param algorithm [String] hash algorithm ("sha256", "sha512", "blake2b")
+    # @return [String] raw hash bytes
+    def balloon(password, salt, s_cost, t_cost, algorithm = DEFAULT_ALGORITHM)
+      raise ArgumentError, "s_cost must be >= 1" if s_cost < 1
+      raise ArgumentError, "t_cost must be >= 1" if t_cost < 1
+      raise ArgumentError, "s_cost must be <= #{MAX_S_COST}" if s_cost > MAX_S_COST
+      raise ArgumentError, "t_cost must be <= #{MAX_T_COST}" if t_cost > MAX_T_COST
+
+      digest_name = resolve_algorithm(algorithm)
+      digest = OpenSSL::Digest.new(digest_name)
+      block_size = digest.digest_length
+      password = password.to_s.b
+      salt = salt.b
+
+      cnt = 0
+
+      # Step 1: Expand input into a flat binary buffer
+      buf = "\0".b * (s_cost * block_size)
+
+      buf[0, block_size] = hash_func(digest, int64le(cnt), password, salt)
+      cnt += 1
+
+      (1...s_cost).each do |m|
+        offset = m * block_size
+        prev_offset = (m - 1) * block_size
+        buf[offset, block_size] = hash_func(digest, int64le(cnt), buf[prev_offset, block_size])
+        cnt += 1
+      end
+
+      # Step 2: Mix buffer contents
+      t_cost.times do |t|
+        s_cost.times do |m|
+          offset = m * block_size
+          prev_offset = ((m - 1) % s_cost) * block_size
+
+          buf[offset, block_size] = hash_func(
+            digest, int64le(cnt), buf[prev_offset, block_size], buf[offset, block_size]
+          )
+          cnt += 1
+
+          # Hash in pseudorandomly chosen blocks
+          DELTA.times do |i|
+            idx_block = [t, m, i].pack("Q<Q<Q<")
+            other_index = hash_to_int(
+              hash_func(digest, int64le(cnt), salt, idx_block)
+            ) % s_cost
+            other_offset = other_index * block_size
+            buf[offset, block_size] = hash_func(
+              digest, int64le(cnt), buf[offset, block_size], buf[other_offset, block_size]
+            )
+            cnt += 1
+          end
+        end
+      end
+
+      # Step 3: Extract output from last block
+      result = buf[(s_cost - 1) * block_size, block_size].dup
+
+      # Best-effort buffer zeroing. Ruby's GC may retain copies of
+      # intermediate string slices, and compaction can move memory without
+      # clearing the original location. For stronger guarantees, a C
+      # extension using OPENSSL_cleanse or sodium_memzero would be needed.
+      buf.replace("\0" * buf.bytesize)
+
+      result
+    end
+
+    # Hash arbitrary number of byte string inputs using the given digest.
+    def hash_func(digest, *inputs)
+      digest.reset
+      inputs.each { |input| digest.update(input) }
+      digest.digest
+    end
+
+    # Encode an integer as a little-endian 64-bit byte string.
+    def int64le(n)
+      [n].pack("Q<")
+    end
+
+    # Convert a hash output (byte string) to a non-negative integer.
+    # Uses first 8 bytes to avoid BigInteger allocation.
+    def hash_to_int(bytes)
+      bytes.unpack1("Q>")
+    end
+
+    # Resolve algorithm name to OpenSSL digest name.
+    def resolve_algorithm(algorithm)
+      SUPPORTED_ALGORITHMS.fetch(algorithm.to_s.downcase) do
+        raise ArgumentError,
+          "Unsupported algorithm: #{algorithm}. " \
+          "Supported: #{SUPPORTED_ALGORITHMS.keys.join(', ')}"
+      end
+    end
+
+    private_class_method :hash_func, :int64le, :hash_to_int, :resolve_algorithm
+  end
+end

data/lib/balloon_hashing/hasher.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module BalloonHashing
+  # Instance-based API with configurable defaults.
+  #
+  # Thread safety: instances are effectively immutable after construction.
+  # All instance variables are frozen, and the public methods delegate to
+  # the stateless Password module. Safe to share across threads.
+  #
+  # Example:
+  #   hasher = BalloonHashing::Hasher.new(s_cost: 2048, t_cost: 4, algorithm: "sha512")
+  #   hash = hasher.create("password")
+  #   hasher.verify("password", hash)  #=> true
+  #   hasher.cost_matches?(hash)       #=> true
+  class Hasher
+    attr_reader :s_cost, :t_cost, :algorithm, :salt_length
+
+    def initialize(s_cost: DEFAULT_S_COST, t_cost: DEFAULT_T_COST,
+                   algorithm: DEFAULT_ALGORITHM,
+                   salt_length: DEFAULT_SALT_LENGTH, pepper: nil)
+      Core.validate_algorithm!(algorithm)
+      raise ArgumentError, "s_cost must be >= 1" if s_cost < 1
+      raise ArgumentError, "t_cost must be >= 1" if t_cost < 1
+      raise ArgumentError, "salt_length must be a positive Integer" unless salt_length.is_a?(Integer) && salt_length > 0
+
+      @s_cost = s_cost
+      @t_cost = t_cost
+      @algorithm = algorithm.to_s.downcase.freeze
+      @salt_length = salt_length
+      @pepper = pepper.freeze
+    end
+
+    def create(password, salt: nil)
+      Password.create(
+        password,
+        s_cost: @s_cost,
+        t_cost: @t_cost,
+        algorithm: @algorithm,
+        salt: salt,
+        salt_length: @salt_length,
+        pepper: @pepper
+      )
+    end
+
+    # Verify a password against an encoded hash string.
+    # This verifies using the parameters stored in the encoded hash,
+    # regardless of this hasher's configuration. A hash created with
+    # sha256 will verify correctly even if this hasher is configured
+    # for sha512. Use verify! if you want to enforce that the hash
+    # matches this hasher's configuration.
+    def verify(password, encoded)
+      Password.verify(password, encoded, pepper: @pepper)
+    end
+
+    # Like verify, but also raises if the encoded hash does not match
+    # this hasher's cost configuration.
+    #
+    # @raise [BalloonHashing::InvalidHash] if the hash params don't match
+    # @return [Boolean] true if password matches
+    def verify!(password, encoded)
+      unless cost_matches?(encoded)
+        raise InvalidHash, "encoded hash does not match this hasher's configuration"
+      end
+
+      verify(password, encoded)
+    end
+
+    # Check if the encoded hash matches this hasher's configuration.
+    def cost_matches?(encoded)
+      Password.cost_matches?(
+        encoded,
+        s_cost: @s_cost,
+        t_cost: @t_cost,
+        algorithm: @algorithm
+      )
+    end
+
+    # Check if the encoded hash uses outdated parameters compared to
+    # this hasher's configuration. Useful for the rehash-on-login pattern:
+    #
+    #   if hasher.verify(password, stored_hash) && hasher.needs_rehash?(stored_hash)
+    #     stored_hash = hasher.create(password)
+    #   end
+    def needs_rehash?(encoded)
+      !cost_matches?(encoded)
+    end
+
+    def inspect
+      "#<#{self.class} s_cost=#{@s_cost} t_cost=#{@t_cost}" \
+        " algorithm=#{@algorithm} salt_length=#{@salt_length}>"
+    end
+  end
+end

data/lib/balloon_hashing/password.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "base64"
+
+module BalloonHashing
+  # High-level password hashing API with salt generation and
+  # encoded hash string output.
+  #
+  # Hash format (v=1):
+  #   $balloon$v=1$alg=sha256,s=1024,t=3$<base64_salt>$<base64_hash>
+  #
+  # Unknown parameter keys are ignored during decoding for forward
+  # compatibility — new parameters (e.g. parallelism) can be added in
+  # future versions without breaking existing hashes.
+  #
+  # Thread safety: all public methods are stateless and safe to call
+  # concurrently from multiple threads.
+  #
+  # Example:
+  #   hash = BalloonHashing::Password.create("my password")
+  #   BalloonHashing::Password.verify("my password", hash)  #=> true
+  #   BalloonHashing::Password.verify("wrong", hash)         #=> false
+  module Password
+    PREFIX = "$balloon$"
+    FORMAT_VERSION = 1
+
+    module_function
+
+    # Hash a password with Balloon Hashing.
+    #
+    # @param password [String] the plaintext password
+    # @param s_cost [Integer] space cost (default: 1024)
+    # @param t_cost [Integer] time cost (default: 3)
+    # @param algorithm [String] "sha256", "sha512", or "blake2b"
+    # @param salt [String, nil] raw salt bytes, or nil to generate random
+    # @param salt_length [Integer] salt length in bytes if generating
+    # @param pepper [String, nil] optional server-side secret; mixed via
+    #   HMAC so it is never stored in the encoded output
+    # @return [String] encoded hash string
+    # @raise [ArgumentError] if password is not a string or parameters are invalid
+    def create(password, s_cost: DEFAULT_S_COST, t_cost: DEFAULT_T_COST,
+               algorithm: DEFAULT_ALGORITHM, salt: nil,
+               salt_length: DEFAULT_SALT_LENGTH, pepper: nil)
+      validate_password!(password)
+      Core.validate_algorithm!(algorithm)
+      validate_salt_length!(salt_length) unless salt
+
+      salt ||= SecureRandom.random_bytes(salt_length)
+      input = peppered(password, pepper)
+
+      raw_hash = Core.balloon(input, salt, s_cost, t_cost, algorithm)
+
+      encode(algorithm, s_cost, t_cost, salt, raw_hash)
+    end
+
+    # Verify a password against an encoded hash string.
+    #
+    # @param password [String] the plaintext password to check
+    # @param encoded [String] the encoded hash string from .create
+    # @param pepper [String, nil] the same pepper used during .create
+    # @return [Boolean] true if the password matches
+    def verify(password, encoded, pepper: nil)
+      validate_password!(password)
+      params = decode(encoded)
+      input = peppered(password, pepper)
+
+      raw_hash = Core.balloon(
+        input,
+        params[:salt],
+        params[:s_cost],
+        params[:t_cost],
+        params[:algorithm]
+      )
+
+      secure_compare(raw_hash, params[:hash])
+    rescue InvalidHash
+      false
+    end
+
+    # Check whether the encoded hash uses the given cost parameters.
+    # Useful for deciding whether to re-hash on next login.
+    #
+    # @param encoded [String] the encoded hash string
+    # @param s_cost [Integer] expected space cost
+    # @param t_cost [Integer] expected time cost
+    # @param algorithm [String] expected algorithm
+    # @return [Boolean]
+    def cost_matches?(encoded, s_cost: DEFAULT_S_COST, t_cost: DEFAULT_T_COST,
+                      algorithm: DEFAULT_ALGORITHM)
+      params = decode(encoded)
+
+      params[:s_cost] == s_cost &&
+        params[:t_cost] == t_cost &&
+        params[:algorithm] == algorithm.to_s.downcase
+    rescue InvalidHash
+      false
+    end
+
+    # Encode hash parameters and output into a string.
+    def encode(algorithm, s_cost, t_cost, salt, hash)
+      salt_b64 = Base64.strict_encode64(salt)
+      hash_b64 = Base64.strict_encode64(hash)
+      params = "alg=#{algorithm},s=#{s_cost},t=#{t_cost}"
+      "#{PREFIX}v=#{FORMAT_VERSION}$#{params}$#{salt_b64}$#{hash_b64}"
+    end
+
+    # Decode an encoded hash string into its components.
+    #
+    # @param encoded [String]
+    # @return [Hash] parsed parameters
+    # @raise [BalloonHashing::InvalidHash] if the string cannot be decoded
+    def decode(encoded)
+      raise InvalidHash, "expected a String, got #{encoded.class}" unless encoded.is_a?(String)
+      raise InvalidHash, "missing balloon prefix" unless encoded.start_with?(PREFIX)
+
+      parts = encoded.split("$")
+      # Parts: ["", "balloon", "v=1", "alg=sha256,s=1024,t=3", "<salt>", "<hash>"]
+      raise InvalidHash, "malformed hash string" unless parts.length == 6
+
+      version_str = parts[2]
+      raise InvalidHash, "unsupported version: #{version_str}" unless version_str == "v=#{FORMAT_VERSION}"
+
+      # Parse key=value pairs; unknown keys are ignored for forward compatibility
+      param_pairs = parts[3].split(",").each_with_object({}) do |pair, h|
+        k, v = pair.split("=", 2)
+        h[k] = v if k && v
+      end
+
+      unless param_pairs.key?("alg") && param_pairs.key?("s") && param_pairs.key?("t")
+        raise InvalidHash, "missing required parameters in hash string"
+      end
+
+      begin
+        s_cost = Integer(param_pairs["s"])
+        t_cost = Integer(param_pairs["t"])
+      rescue ArgumentError, TypeError => e
+        raise InvalidHash, "invalid cost parameter: #{e.message}"
+      end
+      algorithm = param_pairs["alg"]
+
+      validate_decoded_costs!(s_cost, t_cost)
+      unless Core.valid_algorithm?(algorithm)
+        raise InvalidHash, "unsupported algorithm in hash string: #{algorithm}"
+      end
+
+      begin
+        salt = Base64.strict_decode64(parts[4])
+        hash = Base64.strict_decode64(parts[5])
+      rescue ArgumentError => e
+        raise InvalidHash, "invalid base64: #{e.message}"
+      end
+
+      {
+        algorithm: algorithm,
+        s_cost: s_cost,
+        t_cost: t_cost,
+        salt: salt,
+        hash: hash
+      }
+    end
+
+    # Constant-time comparison to prevent timing attacks.
+    def secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      OpenSSL.fixed_length_secure_compare(a, b)
+    end
+
+    def validate_password!(password)
+      raise ArgumentError, "password must be a String" unless password.is_a?(String)
+    end
+
+    def validate_salt_length!(salt_length)
+      raise ArgumentError, "salt_length must be a positive Integer" unless salt_length.is_a?(Integer) && salt_length > 0
+    end
+
+    def validate_decoded_costs!(s_cost, t_cost)
+      raise InvalidHash, "decoded s_cost must be >= 1" if s_cost < 1
+      raise InvalidHash, "decoded s_cost exceeds maximum (#{Core::MAX_S_COST})" if s_cost > Core::MAX_S_COST
+      raise InvalidHash, "decoded t_cost must be >= 1" if t_cost < 1
+      raise InvalidHash, "decoded t_cost exceeds maximum (#{Core::MAX_T_COST})" if t_cost > Core::MAX_T_COST
+    end
+
+    # Derive a peppered password using HMAC to avoid length-ambiguity
+    # issues with simple concatenation. The pepper is the HMAC key and
+    # the password is the message, producing a fixed-length binary output
+    # that is then used as the input to the balloon hash.
+    #
+    # HMAC-SHA256 is used regardless of the balloon algorithm choice.
+    # This is intentional: the HMAC here is a pre-mixing step, not the
+    # memory-hard hash itself. SHA256 provides a 256-bit output which is
+    # sufficient for all supported balloon algorithms.
+    def peppered(password, pepper)
+      return password unless pepper
+
+      OpenSSL::HMAC.digest("SHA256", pepper.to_s.b, password.to_s.b)
+    end
+
+    private_class_method :encode, :decode, :secure_compare, :validate_password!,
+                         :validate_salt_length!, :validate_decoded_costs!, :peppered
+  end
+end

data/lib/balloon_hashing/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module BalloonHashing
+  VERSION = "0.1.0"
+end

data/lib/balloon_hashing.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "balloon_hashing/version"
+require_relative "balloon_hashing/base"
+require_relative "balloon_hashing/core"
+require_relative "balloon_hashing/password"
+require_relative "balloon_hashing/hasher"
+
+module BalloonHashing
+  # Convenience method to hash a password.
+  #
+  # @see BalloonHashing::Password.create
+  def self.create(password, **options)
+    Password.create(password, **options)
+  end
+
+  # Convenience method to verify a password.
+  #
+  # @see BalloonHashing::Password.verify
+  def self.verify(password, encoded, **options)
+    Password.verify(password, encoded, **options)
+  end
+end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: balloon_hashing
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Suleyman Musayev
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Pure Ruby implementation of the Balloon Hashing algorithm (Boneh, Corrigan-Gibbs,
+  Schechter 2016). Supports SHA-256, SHA-512, and BLAKE2b. Memory-hard with provable
+  protection against sequential attacks.
+email:
+- slmusayev@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/balloon_hashing.rb
+- lib/balloon_hashing/base.rb
+- lib/balloon_hashing/core.rb
+- lib/balloon_hashing/hasher.rb
+- lib/balloon_hashing/password.rb
+- lib/balloon_hashing/version.rb
+homepage: https://github.com/msuliq/balloon_hashing
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/msuliq/balloon_hashing
+  source_code_uri: https://github.com/msuliq/balloon_hashing
+  changelog_uri: https://github.com/msuliq/balloon_hashing/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: 'Balloon Hashing: a memory-hard password hashing function with provable security
+  guarantees.'
+test_files: []