rework an API key hashing and validation logic - make it more secure

Author: sergejsvisockis

ApiKeyGenerator.java

@@ -0,0 +1,39 @@
+import javax.crypto.SecretKeyFactory;
+import javax.crypto.spec.PBEKeySpec;
+import java.security.SecureRandom;
+import java.util.Base64;
+
+/**
+ * Use these tool to generate an API keys locally.
+ */
+public class ApiKeyGenerator {
+
+    public static String generateApiKey() {
+        byte[] randomBytes = new byte[32]; // 256 bits
+        new SecureRandom().nextBytes(randomBytes);
+        return Base64.getUrlEncoder().withoutPadding().encodeToString(randomBytes);
+    }
+
+    public static byte[] generateSalt() {
+        byte[] salt = new byte[16]; // 128-bit salt
+        new SecureRandom().nextBytes(salt);
+        return salt;
+    }
+
+    public static String hashApiKey(String apiKey, byte[] salt) throws Exception {
+        PBEKeySpec spec = new PBEKeySpec(apiKey.toCharArray(), salt, 100_000, 256); // iterations, key length
+        SecretKeyFactory skf = SecretKeyFactory.getInstance("PBKDF2WithHmacSHA256");
+        byte[] hash = skf.generateSecret(spec).getEncoded();
+        return Base64.getEncoder().encodeToString(hash);
+    }
+
+    public static void main(String[] args) throws Exception {
+        String apiKey = generateApiKey();
+        byte[] salt = generateSalt();
+        String hashedKey = hashApiKey(apiKey, salt);
+
+        System.out.println("API Key: " + apiKey);
+        System.out.println("Salt (Base64): " + Base64.getEncoder().encodeToString(salt));
+        System.out.println("Hashed Key (Base64): " + hashedKey);
+    }
+}

README.md

@@ -81,7 +81,15 @@ aws dynamodb create-table \
 ```
 
 For the sake of simplicity an API key is inserted manually into the DynamoDB.
-An API key must be Base64 encoded string.
+An API key must be CSPRNG 256-bit key while being PBKDF2 encoded prior to being stored in the database.
+
+The util class is called 'ApiKeyGenerator.java' and is located in the root of the project.
+To get the key just run:
+
+```shell
+java ApiKeyGenerator.java
+```
+
 In real production-grade application the same approach could be followed as well, when more manual approach is
 acceptable.
 However, it also could be that an API key is generated by the 3rd party service as well.
@@ -98,10 +106,10 @@ Here is an example:
 aws dynamodb put-item \
     --table-name api_key  \
     --item \
-        '{"apiKeyId": {"S": "c09e472f-08ad-42a8-8e72-22205bc4d262"}, "apiKey": {"S": "NjZhMTkwMzEtZjdmNC00YWU2LTk0ZTctODllOWQ3OWZkNDAx"}, "assignee": {"S": "Sergejs Visockis"}, "assigneeContactDetails": {"S": "[email protected]"}, "expirationDate": {"S": "2026-08-16T14:14:14.627646"}}'
+        '{"apiKeyId": {"S": "c09e472f-08ad-42a8-8e72-22205bc4d262"}, "apiKey": {"S": "bFw/JX/Pb7Cg5h9f+2SzU2jq4i2UtaxExGZvBA3C1n4="}, "salt": {"S": "DSB/V/61ng9kxukgr1FEnQ=="}, "assignee": {"S": "Sergejs Visockis"}, "assigneeContactDetails": {"S": "[email protected]"}, "expirationDate": {"S": "2026-08-16T14:14:14.627646"}}'
 ```
 
-An API key is - 66a19031-f7f4-4ae6-94e7-89e9d79fd401
+An API key is - c09e472f-08ad-42a8-8e72-22205bc4d262.vQKdiCGDJFyhXZJsvZ_M_0FOOLgBN4L77vm-xDZdglE
 
 Make an SNS topic:
 

service/src/main/java/io/github/sergejsvisockis/documentservice/auth/AuthenticationService.java

@@ -11,9 +11,11 @@
 import org.springframework.stereotype.Service;
 
 import java.time.LocalDateTime;
-import java.util.Base64;
 import java.util.concurrent.TimeUnit;
 
+import static io.github.sergejsvisockis.documentservice.utils.ApiKeyUtil.decodeSalt;
+import static io.github.sergejsvisockis.documentservice.utils.ApiKeyUtil.hashApiKey;
+
 @Service
 public class AuthenticationService {
 
@@ -40,39 +42,46 @@ public Authentication getAuthentication(HttpServletRequest request) {
             throw new BadCredentialsException(INCORRECT_API_KEY_MESSAGE);
         }
 
-        ApiKey apiAuthKey = findApiAuthKey(apiKey);
+        String[] splitHeader = apiKey.split("\\.");
+        String keyId = splitHeader[0];
+        String headerApiKey = splitHeader[1];
 
-        if (!isValid(apiAuthKey)) {
-            throw new BadCredentialsException(API_KEY_EXPIRED_MESSAGE);
-        }
+        ApiKey apiAuthKey = findApiAuthKey(keyId);
+        isValid(apiAuthKey, headerApiKey);
 
         return new ApiKeyAuthentication(apiKey, AuthorityUtils.NO_AUTHORITIES);
     }
 
-    private boolean isValid(ApiKey apiKey) {
+    private void isValid(ApiKey apiKey, String headerApiKey) {
+        byte[] decodedSalt = decodeSalt(apiKey.getSalt());
+
+        String hashedApiKey = hashApiKey(headerApiKey, decodedSalt);
+
+        if (!hashedApiKey.equals(apiKey.getApiKey())) {
+            throw new BadCredentialsException(INCORRECT_API_KEY_MESSAGE);
+        }
+
         LocalDateTime validTo = LocalDateTime.parse(apiKey.getExpirationDate());
-        return LocalDateTime.now().isBefore(validTo);
+        if (LocalDateTime.now().isEqual(validTo)) {
+            throw new BadCredentialsException(API_KEY_EXPIRED_MESSAGE);
+        }
     }
 
-    private ApiKey findApiAuthKey(String key) {
-        ApiKey fromCache = cache.getIfPresent(key);
+    private ApiKey findApiAuthKey(String keyId) {
+        ApiKey fromCache = cache.getIfPresent(keyId);
 
         if (fromCache != null) {
             return fromCache;
         }
 
-        ApiKey apiKey = apiKeyRepository.findApiKey(encodeApiKey(key));
+        ApiKey apiKey = apiKeyRepository.findApiKey(keyId);
 
         if (apiKey == null) {
             throw new BadCredentialsException(NO_API_KEY_FOUND_MESSAGE);
         }
 
-        cache.put(key, apiKey);
+        cache.put(keyId, apiKey);
         return apiKey;
     }
 
-    private String encodeApiKey(String key) {
-        return Base64.getEncoder().encodeToString(key.getBytes());
-    }
-
 }

service/src/main/java/io/github/sergejsvisockis/documentservice/repository/ApiKey.java

@@ -17,6 +17,7 @@ public class ApiKey {
 
     private String apiKeyId;
     private String apiKey;
+    private String salt;
     private String assignee;
     private String assigneeContactDetails;
     private String expirationDate;
@@ -31,6 +32,11 @@ public String getApiKey() {
         return apiKey;
     }
 
+    @DynamoDbAttribute("salt")
+    public String getSalt() {
+        return salt;
+    }
+
     @DynamoDbAttribute("assignee")
     public String getAssignee() {
         return assignee;

service/src/main/java/io/github/sergejsvisockis/documentservice/repository/ApiKeyRepository.java

@@ -15,11 +15,11 @@ public class ApiKeyRepository {
 
     private final DynamoDbTemplate dynamoDbTemplate;
 
-    public ApiKey findApiKey(String key) {
+    public ApiKey findApiKey(String keyId) {
         ScanEnhancedRequest request = ScanEnhancedRequest.builder()
                 .filterExpression(Expression.builder()
-                        .expression("apiKey = :key")
-                        .expressionValues(Map.of(":key", AttributeValue.fromS(key)))
+                        .expression("apiKeyId = :keyId")
+                        .expressionValues(Map.of(":keyId", AttributeValue.fromS(keyId)))
                         .build())
                 .build();
         return dynamoDbTemplate.scan(request, ApiKey.class)

service/src/main/java/io/github/sergejsvisockis/documentservice/utils/ApiKeyUtil.java

@@ -0,0 +1,31 @@
+package io.github.sergejsvisockis.documentservice.utils;
+
+import javax.crypto.SecretKeyFactory;
+import javax.crypto.spec.PBEKeySpec;
+import java.util.Arrays;
+import java.util.Base64;
+
+public final class ApiKeyUtil {
+
+    private ApiKeyUtil() {
+    }
+
+    private static final String ALGORITHM = "PBKDF2WithHmacSHA256";
+
+    public static String hashApiKey(String apiKey, byte[] salt) {
+        try {
+            PBEKeySpec spec = new PBEKeySpec(apiKey.toCharArray(), salt, 100_000, 256); // iterations, key length
+            SecretKeyFactory skf = SecretKeyFactory.getInstance(ALGORITHM);
+            byte[] hash = skf.generateSecret(spec).getEncoded();
+            return Base64.getEncoder().encodeToString(hash);
+        } catch (Exception e) {
+            throw new IllegalStateException("Failed to hash an API key=" + apiKey
+                    + "and salt=" + Arrays.toString(salt), e);
+        }
+    }
+
+    public static byte[] decodeSalt(String salt) {
+        return Base64.getDecoder().decode(salt);
+    }
+
+}

service/src/test/java/io/github/sergejsvisockis/documentservice/auth/AuthenticationServiceTest.java

@@ -2,32 +2,47 @@
 
 import io.github.sergejsvisockis.documentservice.repository.ApiKey;
 import io.github.sergejsvisockis.documentservice.repository.ApiKeyRepository;
+import io.github.sergejsvisockis.documentservice.utils.ApiKeyUtil;
 import jakarta.servlet.http.HttpServletRequest;
+import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
 import org.mockito.InjectMocks;
 import org.mockito.Mock;
-import org.mockito.Mockito;
+import org.mockito.MockedStatic;
 import org.mockito.junit.jupiter.MockitoExtension;
 import org.springframework.security.authentication.BadCredentialsException;
 import org.springframework.security.core.Authentication;
 
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+
 import java.time.LocalDateTime;
 import java.util.Base64;
 
 import static io.github.sergejsvisockis.documentservice.auth.AuthenticationService.API_KEY_EXPIRED_MESSAGE;
+import static io.github.sergejsvisockis.documentservice.auth.AuthenticationService.AUTH_TOKEN_HEADER_NAME;
 import static io.github.sergejsvisockis.documentservice.auth.AuthenticationService.INCORRECT_API_KEY_MESSAGE;
 import static io.github.sergejsvisockis.documentservice.auth.AuthenticationService.NO_API_KEY_FOUND_MESSAGE;
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assertions.fail;
+import static org.mockito.Mockito.mockStatic;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
 
 @ExtendWith(MockitoExtension.class)
 class AuthenticationServiceTest {
 
-    private static final String AUTH_TOKEN_HEADER_NAME = "x-api-key";
-    private static final String VALID_API_KEY = "valid-api-key";
-    private static final String ENCODED_API_KEY = Base64.getEncoder().encodeToString(VALID_API_KEY.getBytes());
+    private static final String KEY_ID = "test-key-id";
+    private static final String API_KEY = "test-api-key";
+    private static final String VALID_HEADER_API_KEY = KEY_ID + "." + API_KEY;
+    private static final String HASHED_API_KEY = "hashedApiKey123";
+    private static final String ENCODED_SALT = Base64.getEncoder().encodeToString("test-salt".getBytes());
+    private static final byte[] DECODED_SALT = "test-salt".getBytes();
 
     @Mock
     private ApiKeyRepository apiKeyRepository;
@@ -38,58 +53,104 @@ class AuthenticationServiceTest {
     @InjectMocks
     private AuthenticationService authenticationService;
 
+    private ApiKey validApiKey;
+
+    @BeforeEach
+    void setUp() {
+        validApiKey = new ApiKey();
+        validApiKey.setApiKeyId(KEY_ID);
+        validApiKey.setApiKey(HASHED_API_KEY);
+        validApiKey.setSalt(ENCODED_SALT);
+        validApiKey.setExpirationDate(LocalDateTime.now().plusDays(1).toString());
+    }
+
     @Test
     void shouldReturnAuthenticationWhenApiKeyIsValid() {
         // given
-        ApiKey apiKey = new ApiKey();
-        apiKey.setApiKey(ENCODED_API_KEY);
-        apiKey.setExpirationDate(LocalDateTime.now().plusDays(1).toString());
-
-        when(request.getHeader(AUTH_TOKEN_HEADER_NAME)).thenReturn(VALID_API_KEY);
-        when(apiKeyRepository.findApiKey(ENCODED_API_KEY)).thenReturn(apiKey);
-
-        // when
-        Authentication authentication = authenticationService.getAuthentication(request);
-
-        // then
-        assertEquals(VALID_API_KEY, authentication.getPrincipal());
+        when(request.getHeader(AUTH_TOKEN_HEADER_NAME)).thenReturn(VALID_HEADER_API_KEY);
+        when(apiKeyRepository.findApiKey(KEY_ID)).thenReturn(validApiKey);
+        
+        try (MockedStatic<ApiKeyUtil> apiKeyUtilMock = mockStatic(ApiKeyUtil.class)) {
+            apiKeyUtilMock.when(() -> ApiKeyUtil.decodeSalt(ENCODED_SALT)).thenReturn(DECODED_SALT);
+            apiKeyUtilMock.when(() -> ApiKeyUtil.hashApiKey(API_KEY, DECODED_SALT)).thenReturn(HASHED_API_KEY);
+            
+            // when
+            Authentication authentication = authenticationService.getAuthentication(request);
+            
+            // then
+            assertNotNull(authentication);
+            assertEquals(VALID_HEADER_API_KEY, authentication.getPrincipal());
+            apiKeyUtilMock.verify(() -> ApiKeyUtil.decodeSalt(ENCODED_SALT));
+            apiKeyUtilMock.verify(() -> ApiKeyUtil.hashApiKey(API_KEY, DECODED_SALT));
+        }
     }
 
     @Test
-    void shouldThrowExceptionWhenApiKeyIsNotFound() {
+    void shouldThrowExceptionWhenApiKeyHeaderIsMissing() {
         // given
-        when(request.getHeader(AUTH_TOKEN_HEADER_NAME)).thenReturn(VALID_API_KEY);
-        when(apiKeyRepository.findApiKey(ENCODED_API_KEY)).thenReturn(null);
+        when(request.getHeader(AUTH_TOKEN_HEADER_NAME)).thenReturn(null);
 
         // when & then
         BadCredentialsException exception = assertThrows(BadCredentialsException.class,
                 () -> authenticationService.getAuthentication(request));
-        assertEquals(NO_API_KEY_FOUND_MESSAGE, exception.getMessage());
+        assertEquals(INCORRECT_API_KEY_MESSAGE, exception.getMessage());
     }
 
     @Test
-    void shouldThrowExceptionWhenApiKeyIsNull() {
+    void shouldThrowExceptionWhenApiKeyFormatIsInvalid() {
         // given
-        when(request.getHeader(AUTH_TOKEN_HEADER_NAME)).thenReturn(null);
+        when(request.getHeader(AUTH_TOKEN_HEADER_NAME)).thenReturn("invalid-format");
 
         // when & then
-        BadCredentialsException exception = assertThrows(BadCredentialsException.class,
+        assertThrows(ArrayIndexOutOfBoundsException.class,
                 () -> authenticationService.getAuthentication(request));
-        assertEquals(INCORRECT_API_KEY_MESSAGE, exception.getMessage());
     }
 
     @Test
-    void shouldThrowExceptionWhenApiKeyHasExpired() {
+    void shouldThrowExceptionWhenApiKeyIsNotFound() {
         // given
-        ApiKey apiKey = Mockito.mock(ApiKey.class);
-        when(apiKey.getExpirationDate()).thenReturn(LocalDateTime.now().minusDays(1).toString());
-        when(request.getHeader(AUTH_TOKEN_HEADER_NAME)).thenReturn(VALID_API_KEY);
-        when(apiKeyRepository.findApiKey(ENCODED_API_KEY)).thenReturn(apiKey);
-
+        when(request.getHeader(AUTH_TOKEN_HEADER_NAME)).thenReturn(VALID_HEADER_API_KEY);
+        when(apiKeyRepository.findApiKey(KEY_ID)).thenReturn(null);
 
         // when & then
         BadCredentialsException exception = assertThrows(BadCredentialsException.class,
                 () -> authenticationService.getAuthentication(request));
-        assertEquals(API_KEY_EXPIRED_MESSAGE, exception.getMessage());
+        assertEquals(NO_API_KEY_FOUND_MESSAGE, exception.getMessage());
+    }
+
+    @Test
+    void shouldThrowExceptionWhenApiKeyHashDoesNotMatch() {
+        // given
+        when(request.getHeader(AUTH_TOKEN_HEADER_NAME)).thenReturn(VALID_HEADER_API_KEY);
+        when(apiKeyRepository.findApiKey(KEY_ID)).thenReturn(validApiKey);
+        
+        try (MockedStatic<ApiKeyUtil> apiKeyUtilMock = mockStatic(ApiKeyUtil.class)) {
+            apiKeyUtilMock.when(() -> ApiKeyUtil.decodeSalt(ENCODED_SALT)).thenReturn(DECODED_SALT);
+            apiKeyUtilMock.when(() -> ApiKeyUtil.hashApiKey(API_KEY, DECODED_SALT)).thenReturn("different-hash");
+            
+            // when & then
+            BadCredentialsException exception = assertThrows(BadCredentialsException.class,
+                    () -> authenticationService.getAuthentication(request));
+            assertEquals(INCORRECT_API_KEY_MESSAGE, exception.getMessage());
+        }
+    }
+
+    @Test
+    void shouldUseCacheForRepeatedRequests() {
+        // given
+        when(request.getHeader(AUTH_TOKEN_HEADER_NAME)).thenReturn(VALID_HEADER_API_KEY);
+        when(apiKeyRepository.findApiKey(KEY_ID)).thenReturn(validApiKey);
+        
+        try (MockedStatic<ApiKeyUtil> apiKeyUtilMock = mockStatic(ApiKeyUtil.class)) {
+            apiKeyUtilMock.when(() -> ApiKeyUtil.decodeSalt(ENCODED_SALT)).thenReturn(DECODED_SALT);
+            apiKeyUtilMock.when(() -> ApiKeyUtil.hashApiKey(API_KEY, DECODED_SALT)).thenReturn(HASHED_API_KEY);
+            
+            // when
+            authenticationService.getAuthentication(request);
+            authenticationService.getAuthentication(request);
+            
+            // then
+            verify(apiKeyRepository, times(1)).findApiKey(KEY_ID);
+        }
     }
 }