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; 019 020import javax.annotation.concurrent.Immutable; 021 022import static java.util.Objects.requireNonNull; 023 024/** Argon2id version 19 parameters for newly created password hashes. 025 * @since 1.0.0 */ 026@Immutable 027public final class Argon2idParameters { 028 private final int memoryKiB; 029 private final int passes; 030 private final int lanes; 031 032 private Argon2idParameters(int memoryKiB, int passes, int lanes) { 033 this.memoryKiB = memoryKiB; 034 this.passes = passes; 035 this.lanes = lanes; 036 } 037 038 /** Selects the total memory, passes, and lanes. New hashes require at least 19 MiB and two 039 * passes, or at least 46 MiB for a single pass. The upper bounds protect the Java process. 040 * @param memoryKiB total memory in KiB 041 * @param passes number of passes 042 * @param lanes degree of parallelism (Argon2 lanes, not library worker threads) 043 * @return validated parameters 044 * @since 1.0.0 */ 045 public static @NonNull Argon2idParameters fromCosts(@NonNull Integer memoryKiB, @NonNull Integer passes, 046 @NonNull Integer lanes) { 047 requireNonNull(memoryKiB); 048 requireNonNull(passes); 049 requireNonNull(lanes); 050 if (lanes < 1 || lanes > 8 || passes < 1 || passes > 10 051 || memoryKiB > 262_144 || memoryKiB < 8 * lanes 052 || (passes == 1 ? memoryKiB < 47_104 : memoryKiB < 19_456)) { 053 throw new IllegalArgumentException("Invalid Argon2id creation parameters"); 054 } 055 return new Argon2idParameters(memoryKiB, passes, lanes); 056 } 057 058 /** Returns the total memory cost. 059 * @return total memory in KiB 060 * @since 1.0.0 */ 061 public @NonNull Integer getMemoryKiB() { return memoryKiB; } 062 063 /** Returns the time cost. 064 * @return number of passes 065 * @since 1.0.0 */ 066 public @NonNull Integer getPasses() { return passes; } 067 068 /** Returns the parallelism setting. 069 * @return number of lanes 070 * @since 1.0.0 */ 071 public @NonNull Integer getLanes() { return lanes; } 072 073 /** @return a non-secret parameter description 074 * @since 1.0.0 */ 075 @Override public @NonNull String toString() { 076 return "Argon2idParameters{memoryKiB=" + memoryKiB + ", passes=" + passes + ", lanes=" + lanes + "}"; 077 } 078}