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 com.google.errorprone.annotations.CheckReturnValue; 019import org.jspecify.annotations.NonNull; 020import org.jspecify.annotations.Nullable; 021 022import javax.annotation.concurrent.Immutable; 023import javax.annotation.concurrent.NotThreadSafe; 024 025/** Input and stored-cost ceilings applied around admitted password preparation/KDF work. 026 * These ceilings are independent of the work gate: an accepted stored memory cost above that 027 * gate's total budget is intentionally unavailable. Configure the memory ceiling at or below 028 * the gate when every accepted cost must be serviceable. 029 * @since 1.0.0 */ 030@Immutable 031public final class PasswordVerificationLimits { 032 private static final int DEFAULT_MAXIMUM_STORED_FORM_CHARS = 512; 033 private static final int DEFAULT_MAXIMUM_PASSWORD_CHARS = 1_024; 034 private static final int DEFAULT_MAXIMUM_PASSWORD_UTF8_BYTES = 4_096; 035 private static final int DEFAULT_MAXIMUM_ARGON2ID_MEMORY_KIB = 131_072; 036 private static final int DEFAULT_MAXIMUM_ARGON2ID_PASSES = 6; 037 private static final int DEFAULT_MAXIMUM_ARGON2ID_LANES = 8; 038 private final int maximumStoredFormChars; 039 private final int maximumPasswordChars; 040 private final int maximumPasswordUtf8Bytes; 041 private final int maximumArgon2idMemoryKiB; 042 private final int maximumArgon2idPasses; 043 private final int maximumArgon2idLanes; 044 045 private PasswordVerificationLimits(@NonNull Builder builder) { 046 this.maximumStoredFormChars = builder.maximumStoredFormChars; 047 this.maximumPasswordChars = builder.maximumPasswordChars; 048 this.maximumPasswordUtf8Bytes = builder.maximumPasswordUtf8Bytes; 049 this.maximumArgon2idMemoryKiB = builder.maximumArgon2idMemoryKiB; 050 this.maximumArgon2idPasses = builder.maximumArgon2idPasses; 051 this.maximumArgon2idLanes = builder.maximumArgon2idLanes; 052 } 053 054 /** Conservative verification ceilings suitable for initial configuration. 055 * @return the limits 056 * @since 1.0.0 */ 057 public static @NonNull PasswordVerificationLimits fromDefaults() { return new Builder().build(); } 058 059 /** Starts a builder from conservative limits. 060 * @return the builder 061 * @since 1.0.0 */ 062 public static @NonNull Builder builder() { return new Builder(); } 063 064 /** Returns the stored-form length limit. 065 * @return maximum stored-form characters 066 * @since 1.0.0 */ 067 public @NonNull Integer getMaximumStoredFormChars() { return maximumStoredFormChars; } 068 069 /** Returns the input length limit before normalization. 070 * @return maximum input UTF-16 code units before normalization 071 * @since 1.0.0 */ 072 public @NonNull Integer getMaximumPasswordChars() { return maximumPasswordChars; } 073 074 /** Returns the password byte length limit after normalization. 075 * @return maximum normalized UTF-8 bytes 076 * @since 1.0.0 */ 077 public @NonNull Integer getMaximumPasswordUtf8Bytes() { return maximumPasswordUtf8Bytes; } 078 079 /** Returns the maximum accepted Argon2id memory cost. 080 * @return maximum Argon2id verification memory in KiB 081 * @since 1.0.0 */ 082 public @NonNull Integer getMaximumArgon2idMemoryKiB() { return maximumArgon2idMemoryKiB; } 083 084 /** Returns the maximum accepted Argon2id time cost. 085 * @return maximum Argon2id verification passes 086 * @since 1.0.0 */ 087 public @NonNull Integer getMaximumArgon2idPasses() { return maximumArgon2idPasses; } 088 089 /** Returns the maximum accepted Argon2id parallelism. 090 * @return maximum Argon2id verification lanes 091 * @since 1.0.0 */ 092 public @NonNull Integer getMaximumArgon2idLanes() { return maximumArgon2idLanes; } 093 094 /** Mutable construction helper; no cryptographic or provider work runs during construction. 095 * @since 1.0.0 */ 096 @NotThreadSafe 097 @CheckReturnValue 098 public static final class Builder { 099 private int maximumStoredFormChars = DEFAULT_MAXIMUM_STORED_FORM_CHARS; 100 private int maximumPasswordChars = DEFAULT_MAXIMUM_PASSWORD_CHARS; 101 private int maximumPasswordUtf8Bytes = DEFAULT_MAXIMUM_PASSWORD_UTF8_BYTES; 102 private int maximumArgon2idMemoryKiB = DEFAULT_MAXIMUM_ARGON2ID_MEMORY_KIB; 103 private int maximumArgon2idPasses = DEFAULT_MAXIMUM_ARGON2ID_PASSES; 104 private int maximumArgon2idLanes = DEFAULT_MAXIMUM_ARGON2ID_LANES; 105 106 private Builder() { } 107 108 /** Sets the stored-form length limit. 109 * @param value maximum stored-form characters, or null to restore the default 110 * @return this builder 111 * @since 1.0.0 */ 112 public @NonNull Builder maximumStoredFormChars(@Nullable Integer value) { 113 maximumStoredFormChars = value == null ? DEFAULT_MAXIMUM_STORED_FORM_CHARS : value; return this; 114 } 115 116 /** Sets the input length limit before normalization. 117 * @param value maximum input UTF-16 code units, or null to restore the default 118 * @return this builder 119 * @since 1.0.0 */ 120 public @NonNull Builder maximumPasswordChars(@Nullable Integer value) { 121 maximumPasswordChars = value == null ? DEFAULT_MAXIMUM_PASSWORD_CHARS : value; return this; 122 } 123 124 /** Sets the password byte length limit after normalization. 125 * @param value maximum normalized UTF-8 bytes, or null to restore the default 126 * @return this builder 127 * @since 1.0.0 */ 128 public @NonNull Builder maximumPasswordUtf8Bytes(@Nullable Integer value) { 129 maximumPasswordUtf8Bytes = value == null ? DEFAULT_MAXIMUM_PASSWORD_UTF8_BYTES : value; return this; 130 } 131 132 /** Sets the maximum accepted Argon2id memory cost. 133 * @param value maximum Argon2id verification memory in KiB, or null to restore the default 134 * @return this builder 135 * @since 1.0.0 */ 136 public @NonNull Builder maximumArgon2idMemoryKiB(@Nullable Integer value) { 137 maximumArgon2idMemoryKiB = value == null ? DEFAULT_MAXIMUM_ARGON2ID_MEMORY_KIB : value; return this; 138 } 139 140 /** Sets the maximum accepted Argon2id time cost. 141 * @param value maximum Argon2id verification passes, or null to restore the default 142 * @return this builder 143 * @since 1.0.0 */ 144 public @NonNull Builder maximumArgon2idPasses(@Nullable Integer value) { 145 maximumArgon2idPasses = value == null ? DEFAULT_MAXIMUM_ARGON2ID_PASSES : value; return this; 146 } 147 148 /** Sets the maximum accepted Argon2id parallelism. 149 * @param value maximum Argon2id verification lanes, or null to restore the default 150 * @return this builder 151 * @since 1.0.0 */ 152 public @NonNull Builder maximumArgon2idLanes(@Nullable Integer value) { 153 maximumArgon2idLanes = value == null ? DEFAULT_MAXIMUM_ARGON2ID_LANES : value; return this; 154 } 155 156 /** Validates the ceilings without performing I/O or allocating KDF memory. 157 * @return immutable limits 158 * @since 1.0.0 */ 159 public @NonNull PasswordVerificationLimits build() { 160 // A native form with a 64-character pepper key ID is at most 184 characters. 161 if (maximumStoredFormChars < 192 || maximumStoredFormChars > 4_096 162 || maximumPasswordChars < 64 || maximumPasswordChars > 16_384 163 || maximumPasswordUtf8Bytes < 256 || maximumPasswordUtf8Bytes > 65_536 164 || maximumArgon2idMemoryKiB < 19_456 || maximumArgon2idMemoryKiB > 262_144 165 || maximumArgon2idPasses < 2 || maximumArgon2idPasses > 10 166 || maximumArgon2idLanes < 1 || maximumArgon2idLanes > 8) { 167 throw new IllegalArgumentException("Invalid password verification limits"); 168 } 169 return new PasswordVerificationLimits(this); 170 } 171 } 172}