001/* 002 * Copyright 2026 Revetware LLC. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016package com.revetsec.password; 017 018import org.jspecify.annotations.NonNull; 019import org.jspecify.annotations.Nullable; 020 021import javax.annotation.concurrent.ThreadSafe; 022import java.util.concurrent.atomic.AtomicBoolean; 023import java.util.concurrent.locks.ReentrantLock; 024 025import static java.util.Objects.requireNonNull; 026 027/** Explicit in-memory, process-local admission for expensive password work. Share one instance 028 * across every hasher in a process; each JVM needs its own gate to bound that JVM's CPU and memory. 029 * Its temporary counters are discarded on restart and are never shared across nodes. 030 * Admission waits interruptibly for short reservation-counter updates. The gate never queues 031 * for KDF capacity or starts worker threads; exhausted capacity yields an operation result. 032 * Password preparation, hashing and application callbacks run outside the accounting lock. 033 * One permit covers normalization/encoding, pepper lookup and KDF cleanup; it is not released 034 * between those phases. Input length caps do not guarantee a normalization wall-time bound. 035 * Applications separately own shared per-account/edge attempt admission and durable credential storage. 036 * @since 1.0.0 */ 037@ThreadSafe 038public final class PasswordWorkGate { 039 private final int maximumConcurrentCalls; 040 private final int maximumMemoryKiB; 041 private final @NonNull ReentrantLock lock = new ReentrantLock(); 042 private int activeCalls; 043 private int reservedMemoryKiB; 044 045 private PasswordWorkGate(int maximumConcurrentCalls, int maximumMemoryKiB) { 046 this.maximumConcurrentCalls = maximumConcurrentCalls; 047 this.maximumMemoryKiB = maximumMemoryKiB; 048 } 049 050 /** Creates a bounded in-memory work gate for one JVM. Reuse the returned instance across all 051 * hashers in that JVM. Separate calls create independent gates; this factory supplies no 052 * default concurrency or memory budget and performs no distributed attempt throttling. 053 * @param maximumConcurrentCalls maximum simultaneous password operations, from 1 through 256 054 * @param maximumMemoryKiB aggregate Argon2id memory reservation in KiB, from 19,456 through 4,194,304 055 * @return the gate 056 * @throws IllegalArgumentException if either limit is outside its supported range 057 * @since 1.0.0 */ 058 public static @NonNull PasswordWorkGate fromInMemoryLimits(@NonNull Integer maximumConcurrentCalls, 059 @NonNull Integer maximumMemoryKiB) { 060 requireNonNull(maximumConcurrentCalls); 061 requireNonNull(maximumMemoryKiB); 062 if (maximumConcurrentCalls < 1 || maximumConcurrentCalls > 256 063 || maximumMemoryKiB < 19_456 || maximumMemoryKiB > 4_194_304) { 064 throw new IllegalArgumentException("Invalid password work limits"); 065 } 066 return new PasswordWorkGate(maximumConcurrentCalls, maximumMemoryKiB); 067 } 068 069 /** Returns the concurrency limit for admitted password operations. 070 * @return the maximum simultaneous password operations 071 * @since 1.0.0 */ 072 public @NonNull Integer getMaximumConcurrentCalls() { return maximumConcurrentCalls; } 073 074 /** Returns the shared memory reservation limit. 075 * @return the aggregate Argon2id memory reservation in KiB 076 * @since 1.0.0 */ 077 public @NonNull Integer getMaximumMemoryKiB() { return maximumMemoryKiB; } 078 079 @Nullable Permit tryAcquire(int memoryKiB) { 080 try { 081 lock.lockInterruptibly(); 082 } catch (InterruptedException e) { 083 Thread.currentThread().interrupt(); 084 return null; 085 } 086 try { 087 if (memoryKiB < 0 || memoryKiB > maximumMemoryKiB || activeCalls >= maximumConcurrentCalls 088 || reservedMemoryKiB > maximumMemoryKiB - memoryKiB) return null; 089 activeCalls++; 090 reservedMemoryKiB += memoryKiB; 091 return new Permit(this, memoryKiB); 092 } finally { 093 lock.unlock(); 094 } 095 } 096 097 private void release(int memoryKiB) { 098 lock.lock(); 099 try { 100 activeCalls--; 101 reservedMemoryKiB -= memoryKiB; 102 } finally { 103 lock.unlock(); 104 } 105 } 106 107 @ThreadSafe 108 static final class Permit implements AutoCloseable { 109 private final @NonNull PasswordWorkGate gate; 110 private final int memoryKiB; 111 private final @NonNull AtomicBoolean closed = new AtomicBoolean(); 112 113 private Permit(@NonNull PasswordWorkGate gate, int memoryKiB) { 114 this.gate = gate; 115 this.memoryKiB = memoryKiB; 116 } 117 118 @Override public void close() { 119 if (closed.compareAndSet(false, true)) gate.release(memoryKiB); 120 } 121 } 122}