Phase 1: Add PasswordSecurityUtil with secure password handling

Copilot · devondragon · Copilot · commit 44906bb356ef · 2025-10-26T19:24:10.000Z
Co-authored-by: devondragon &lt;1254537+devondragon@users.noreply.github.com&gt;
diff --git a/src/main/java/com/digitalsanctuary/spring/user/util/PasswordSecurityUtil.java b/src/main/java/com/digitalsanctuary/spring/user/util/PasswordSecurityUtil.java
@@ -0,0 +1,135 @@
+package com.digitalsanctuary.spring.user.util;
+
+import java.util.Arrays;
+
+/**
+ * Utility class for secure password handling to minimize password exposure in memory.
+ * 
+ * <p>This class provides methods for:
+ * <ul>
+ *   <li>Constant-time password comparison to prevent timing attacks</li>
+ *   <li>Safe conversion between char[] and String when required</li>
+ *   <li>Explicit memory clearing of sensitive data</li>
+ * </ul>
+ * 
+ * <p><strong>Security Rationale:</strong>
+ * <ul>
+ *   <li>char[] arrays can be explicitly cleared from memory after use</li>
+ *   <li>String objects are immutable and remain in memory until garbage collected</li>
+ *   <li>Using char[] reduces password exposure time in memory</li>
+ * </ul>
+ * 
+ * @author SpringUserFramework
+ * @since 3.1.0
+ */
+public final class PasswordSecurityUtil {
+
+    /**
+     * Private constructor to prevent instantiation.
+     */
+    private PasswordSecurityUtil() {
+        throw new UnsupportedOperationException("Utility class should not be instantiated");
+    }
+
+    /**
+     * Compares two char[] arrays in constant time to prevent timing attacks.
+     * 
+     * <p>This method always compares the full length of both arrays to avoid
+     * leaking information about password length or content through timing.
+     * 
+     * @param password1 first password array
+     * @param password2 second password array
+     * @return true if both arrays are non-null and contain the same characters
+     */
+    public static boolean constantTimeEquals(char[] password1, char[] password2) {
+        if (password1 == null || password2 == null) {
+            return password1 == password2;
+        }
+
+        // Different lengths - always return false but continue timing to avoid leak
+        if (password1.length != password2.length) {
+            // Still perform a comparison to maintain constant time
+            int diff = 0;
+            for (int i = 0; i < password1.length && i < password2.length; i++) {
+                diff |= password1[i] ^ password2[i];
+            }
+            return false;
+        }
+
+        // Same length - compare all characters
+        int diff = 0;
+        for (int i = 0; i < password1.length; i++) {
+            diff |= password1[i] ^ password2[i];
+        }
+
+        return diff == 0;
+    }
+
+    /**
+     * Securely clears a char[] array by overwriting with zeros.
+     * 
+     * <p>This method should be called in a finally block to ensure
+     * sensitive data is cleared even if an exception occurs.
+     * 
+     * @param password the password array to clear (can be null)
+     */
+    public static void clearPassword(char[] password) {
+        if (password != null) {
+            Arrays.fill(password, '\0');
+        }
+    }
+
+    /**
+     * Converts a char[] to String when required by libraries.
+     * 
+     * <p><strong>Important:</strong> The resulting String cannot be cleared
+     * from memory until garbage collected. Use this method only when necessary
+     * and clear the char[] array immediately after conversion.
+     * 
+     * @param password the password char array
+     * @return String representation of the password, or null if input is null
+     */
+    public static String toString(char[] password) {
+        if (password == null) {
+            return null;
+        }
+        return new String(password);
+    }
+
+    /**
+     * Converts a String to char[] for secure handling.
+     * 
+     * <p>Note: The original String will still remain in memory until
+     * garbage collected. This method is primarily useful for transitioning
+     * existing String-based code to char[]-based handling.
+     * 
+     * @param password the password string
+     * @return char array representation, or null if input is null
+     */
+    public static char[] toCharArray(String password) {
+        if (password == null) {
+            return null;
+        }
+        return password.toCharArray();
+    }
+
+    /**
+     * Validates that a char[] password is not null and not empty.
+     * 
+     * @param password the password to validate
+     * @return true if password is non-null and has length > 0
+     */
+    public static boolean isNotEmpty(char[] password) {
+        return password != null && password.length > 0;
+    }
+
+    /**
+     * Validates that a char[] password is null or empty.
+     * 
+     * @param password the password to validate
+     * @return true if password is null or has length 0
+     */
+    public static boolean isEmpty(char[] password) {
+        return password == null || password.length == 0;
+    }
+}
diff --git a/src/test/java/com/digitalsanctuary/spring/user/util/PasswordSecurityUtilTest.java b/src/test/java/com/digitalsanctuary/spring/user/util/PasswordSecurityUtilTest.java
@@ -0,0 +1,197 @@
+package com.digitalsanctuary.spring.user.util;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * Unit tests for PasswordSecurityUtil.
+ */
+class PasswordSecurityUtilTest {
+
+    @Test
+    void constantTimeEquals_returnsTrue_whenBothNull() {
+        assertTrue(PasswordSecurityUtil.constantTimeEquals(null, null));
+    }
+
+    @Test
+    void constantTimeEquals_returnsFalse_whenOneNull() {
+        assertFalse(PasswordSecurityUtil.constantTimeEquals(null, "password".toCharArray()));
+        assertFalse(PasswordSecurityUtil.constantTimeEquals("password".toCharArray(), null));
+    }
+
+    @Test
+    void constantTimeEquals_returnsTrue_whenIdentical() {
+        char[] password1 = "MySecureP@ssw0rd".toCharArray();
+        char[] password2 = "MySecureP@ssw0rd".toCharArray();
+        assertTrue(PasswordSecurityUtil.constantTimeEquals(password1, password2));
+    }
+
+    @Test
+    void constantTimeEquals_returnsFalse_whenDifferent() {
+        char[] password1 = "MySecureP@ssw0rd".toCharArray();
+        char[] password2 = "DifferentP@ss".toCharArray();
+        assertFalse(PasswordSecurityUtil.constantTimeEquals(password1, password2));
+    }
+
+    @Test
+    void constantTimeEquals_returnsFalse_whenDifferentLength() {
+        char[] password1 = "short".toCharArray();
+        char[] password2 = "muchlongerpassword".toCharArray();
+        assertFalse(PasswordSecurityUtil.constantTimeEquals(password1, password2));
+    }
+
+    @Test
+    void constantTimeEquals_returnsFalse_whenOneCharacterDifferent() {
+        char[] password1 = "MySecureP@ssw0rd".toCharArray();
+        char[] password2 = "MySecureP@ssw0rD".toCharArray(); // last char different
+        assertFalse(PasswordSecurityUtil.constantTimeEquals(password1, password2));
+    }
+
+    @Test
+    void constantTimeEquals_returnsTrue_whenBothEmpty() {
+        char[] password1 = new char[0];
+        char[] password2 = new char[0];
+        assertTrue(PasswordSecurityUtil.constantTimeEquals(password1, password2));
+    }
+
+    @Test
+    void clearPassword_clearsArray() {
+        char[] password = "MySecureP@ssw0rd".toCharArray();
+        PasswordSecurityUtil.clearPassword(password);
+        
+        // Verify all characters are cleared to '\0'
+        for (char c : password) {
+            assertEquals('\0', c, "Password should be cleared to null characters");
+        }
+    }
+
+    @Test
+    void clearPassword_handlesNull() {
+        // Should not throw exception
+        assertDoesNotThrow(() -> PasswordSecurityUtil.clearPassword(null));
+    }
+
+    @Test
+    void clearPassword_handlesEmptyArray() {
+        char[] password = new char[0];
+        assertDoesNotThrow(() -> PasswordSecurityUtil.clearPassword(password));
+    }
+
+    @Test
+    void toString_convertsCorrectly() {
+        char[] password = "MySecureP@ssw0rd".toCharArray();
+        String result = PasswordSecurityUtil.toString(password);
+        assertEquals("MySecureP@ssw0rd", result);
+    }
+
+    @Test
+    void toString_handlesNull() {
+        assertNull(PasswordSecurityUtil.toString(null));
+    }
+
+    @Test
+    void toString_handlesEmptyArray() {
+        char[] password = new char[0];
+        String result = PasswordSecurityUtil.toString(password);
+        assertEquals("", result);
+    }
+
+    @Test
+    void toCharArray_convertsCorrectly() {
+        String password = "MySecureP@ssw0rd";
+        char[] result = PasswordSecurityUtil.toCharArray(password);
+        assertArrayEquals("MySecureP@ssw0rd".toCharArray(), result);
+    }
+
+    @Test
+    void toCharArray_handlesNull() {
+        assertNull(PasswordSecurityUtil.toCharArray(null));
+    }
+
+    @Test
+    void toCharArray_handlesEmptyString() {
+        String password = "";
+        char[] result = PasswordSecurityUtil.toCharArray(password);
+        assertNotNull(result);
+        assertEquals(0, result.length);
+    }
+
+    @Test
+    void isNotEmpty_returnsTrue_whenNotEmpty() {
+        char[] password = "password".toCharArray();
+        assertTrue(PasswordSecurityUtil.isNotEmpty(password));
+    }
+
+    @Test
+    void isNotEmpty_returnsFalse_whenNull() {
+        assertFalse(PasswordSecurityUtil.isNotEmpty(null));
+    }
+
+    @Test
+    void isNotEmpty_returnsFalse_whenEmpty() {
+        char[] password = new char[0];
+        assertFalse(PasswordSecurityUtil.isNotEmpty(password));
+    }
+
+    @Test
+    void isEmpty_returnsTrue_whenNull() {
+        assertTrue(PasswordSecurityUtil.isEmpty(null));
+    }
+
+    @Test
+    void isEmpty_returnsTrue_whenEmpty() {
+        char[] password = new char[0];
+        assertTrue(PasswordSecurityUtil.isEmpty(password));
+    }
+
+    @Test
+    void isEmpty_returnsFalse_whenNotEmpty() {
+        char[] password = "password".toCharArray();
+        assertFalse(PasswordSecurityUtil.isEmpty(password));
+    }
+
+    @Test
+    void constructor_throwsException() {
+        assertThrows(java.lang.reflect.InvocationTargetException.class, () -> {
+            // Use reflection to try to instantiate
+            java.lang.reflect.Constructor<PasswordSecurityUtil> constructor = 
+                PasswordSecurityUtil.class.getDeclaredConstructor();
+            constructor.setAccessible(true);
+            constructor.newInstance();
+        });
+    }
+
+    @Test
+    void integrationTest_securePasswordFlow() {
+        // Simulate a secure password handling flow
+        String userInput = "MySecureP@ssw0rd!";
+        
+        // 1. Convert to char[]
+        char[] password = PasswordSecurityUtil.toCharArray(userInput);
+        assertNotNull(password);
+        
+        // 2. Validate
+        assertTrue(PasswordSecurityUtil.isNotEmpty(password));
+        
+        // 3. Compare with another password
+        char[] matchingPassword = "MySecureP@ssw0rd!".toCharArray();
+        assertTrue(PasswordSecurityUtil.constantTimeEquals(password, matchingPassword));
+        
+        // 4. Convert to String when needed (e.g., for PasswordEncoder)
+        String passwordString = PasswordSecurityUtil.toString(password);
+        assertEquals(userInput, passwordString);
+        
+        // 5. Clear both arrays
+        PasswordSecurityUtil.clearPassword(password);
+        PasswordSecurityUtil.clearPassword(matchingPassword);
+        
+        // 6. Verify cleared
+        for (char c : password) {
+            assertEquals('\0', c);
+        }
+        for (char c : matchingPassword) {
+            assertEquals('\0', c);
+        }
+    }
+}
