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; 021import static java.util.Objects.requireNonNull; 022 023/** An application-owned, 32-byte Argon2id secret-input key identified by a non-secret ID. Keep the 024 * key outside the password-hash database. The supplied array is copied and remains caller-owned. 025 * @since 1.0.0 */ 026@Immutable 027public final class PasswordPepperKey { 028 private final @NonNull String keyId; 029 private final byte @NonNull [] key; 030 031 private PasswordPepperKey(@NonNull String keyId, byte @NonNull [] key) { 032 this.keyId = keyId; 033 this.key = key; 034 } 035 036 /** Constructs a pepper key from 32 cryptographically random bytes. 037 * @param keyId stable 1–64 character ASCII key ID 038 * @param keyBytes 32 secret bytes; borrowed only for this call and not modified 039 * @return a retained defensive copy 040 * @since 1.0.0 */ 041 public static @NonNull PasswordPepperKey fromBytes(@NonNull String keyId, byte @NonNull [] keyBytes) { 042 requireNonNull(keyId); requireNonNull(keyBytes); 043 if (keyId.length() < 1 || keyId.length() > 64 || !keyId.chars().allMatch(ch -> 044 (ch >= 'A' && ch <= 'Z') || (ch >= 'a' && ch <= 'z') 045 || (ch >= '0' && ch <= '9') || ch == '.' || ch == '_' || ch == '~' || ch == '-')) { 046 throw new IllegalArgumentException("Invalid pepper key ID"); 047 } 048 if (keyBytes.length != 32) throw new IllegalArgumentException("Pepper key must be 32 bytes"); 049 int difference = 0; 050 for (int i = 1; i < keyBytes.length; i++) difference |= keyBytes[0] ^ keyBytes[i]; 051 if (difference == 0) throw new IllegalArgumentException("Uniform pepper key is not allowed"); 052 return new PasswordPepperKey(keyId, keyBytes.clone()); 053 } 054 055 /** Returns the identifier used to select this pepper key. 056 * @return non-secret key ID 057 * @since 1.0.0 */ 058 public @NonNull String getKeyId() { return keyId; } 059 060 byte @NonNull [] copyKeyBytes() { return key.clone(); } 061 062 /** @return a fixed redacted description 063 * @since 1.0.0 */ 064 @Override public @NonNull String toString() { return "PasswordPepperKey{<redacted>}"; } 065 066 // Intentionally identity-based: comparing key bytes is not a supported operation. 067}