google-site-verification: google61fe8ba583a51912.html
MACRO NEPAL
HMAC Signature Authentication in Java: Complete Implementation Guide
awiskar acharya
November 21, 2025
1:19 pm

HMAC (Hash-based Message Authentication Code) provides a secure way to authenticate API requests by combining cryptographic hashing with a secret key. This guide covers complete implementation for secure API authentication.

HMAC Authentication Overview

How HMAC Works:

  • Client and server share a secret key
  • Client creates signature using request data + secret key
  • Server validates signature using same data + secret key
  • Provides integrity and authentication

Benefits:

  • No passwords transmitted
  • Replay attack protection
  • Timestamp validation
  • Request integrity verification

Dependencies and Setup

Maven Dependencies
<properties> <spring-boot.version>3.1.0</spring-boot.version> <junit.version>5.9.2</junit.version> <commons-codec.version>1.16.0</commons-codec.version> </properties> <dependencies> <!-- Spring Boot --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>${spring-boot.version}</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-validation</artifactId> <version>${spring-boot.version}</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa</artifactId> <version>${spring-boot.version}</version> </dependency> <!-- Security --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-security</artifactId> <version>${spring-boot.version}</version> </dependency> <!-- Encoding --> <dependency> <groupId>commons-codec</groupId> <artifactId>commons-codec</artifactId> <version>${commons-codec.version}</version> </dependency> <!-- Database --> <dependency> <groupId>com.h2database</groupId> <artifactId>h2</artifactId> <scope>runtime</scope> </dependency> <!-- Testing --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <version>${spring-boot.version}</version> <scope>test</scope> </dependency> </dependencies>
Application Configuration
# application.yml app: hmac: # Signature validity in milliseconds (5 minutes) timestamp-validity: 300000 # Supported algorithms algorithms: HmacSHA256,HmacSHA512 # Required headers for signature required-headers: (request-target),date,digest,content-type server: port: 8080 spring: datasource: url: jdbc:h2:mem:testdb driverClassName: org.h2.Driver username: sa password: jpa: database-platform: org.hibernate.dialect.H2Dialect hibernate: ddl-auto: create-drop show-sql: true h2: console: enabled: true logging: level: com.example.hmac: DEBUG

Core HMAC Implementation

1. HMAC Utility Class
// HmacUtil.java package com.example.hmac.util; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.stereotype.Component; import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; import java.nio.charset.StandardCharsets; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.util.Base64; @Component public class HmacUtil { private static final Logger logger = LoggerFactory.getLogger(HmacUtil.class); private static final String HMAC_SHA256 = "HmacSHA256"; private static final String HMAC_SHA512 = "HmacSHA512"; /** * Generate HMAC signature for given data */ public String calculateHmac(String data, String secret, String algorithm) { try { Mac mac = Mac.getInstance(algorithm); SecretKeySpec secretKeySpec = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), algorithm); mac.init(secretKeySpec); byte[] hmacData = mac.doFinal(data.getBytes(StandardCharsets.UTF_8)); return Base64.getEncoder().encodeToString(hmacData); } catch (NoSuchAlgorithmException e) { logger.error("HMAC algorithm not supported: {}", algorithm, e); throw new HmacException("Unsupported algorithm: " + algorithm, e); } catch (InvalidKeyException e) { logger.error("Invalid HMAC key", e); throw new HmacException("Invalid HMAC key", e); } } /** * Verify HMAC signature */ public boolean verifyHmac(String data, String secret, String algorithm, String expectedSignature) { String actualSignature = calculateHmac(data, secret, algorithm); return secureCompare(actualSignature, expectedSignature); } /** * Constant-time comparison to prevent timing attacks */ private boolean secureCompare(String a, String b) { if (a == null || b == null) { return false; } byte[] aBytes = a.getBytes(StandardCharsets.UTF_8); byte[] bBytes = b.getBytes(StandardCharsets.UTF_8); if (aBytes.length != bBytes.length) { return false; } int result = 0; for (int i = 0; i < aBytes.length; i++) { result |= aBytes[i] ^ bBytes[i]; } return result == 0; } /** * Validate HMAC algorithm */ public boolean isValidAlgorithm(String algorithm) { return HMAC_SHA256.equals(algorithm) || HMAC_SHA512.equals(algorithm); } public static class HmacException extends RuntimeException { public HmacException(String message) { super(message); } public HmacException(String message, Throwable cause) { super(message, cause); } } }
2. Signature Generation
// SignatureGenerator.java package com.example.hmac.util; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.stereotype.Component; import org.springframework.util.StringUtils; import java.nio.charset.StandardCharsets; import java.security.MessageDigest; import java.security.NoSuchAlgorithmException; import java.util.Base64; import java.util.Map; import java.util.TreeMap; import java.util.stream.Collectors; @Component public class SignatureGenerator { private static final Logger logger = LoggerFactory.getLogger(SignatureGenerator.class); /** * Generate signature string for HTTP request (AWS Signature v4 style) */ public String generateSignatureString( String method, String path, Map<String, String> headers, String body) { // Normalize method String normalizedMethod = method.toUpperCase(); // Normalize path String normalizedPath = normalizePath(path); // Normalize query string (empty in this example) String normalizedQuery = ""; // Normalize headers String normalizedHeaders = normalizeHeaders(headers); // Signed headers String signedHeaders = getSignedHeaders(headers); // Body hash String bodyHash = calculateBodyHash(body); // Build canonical request String canonicalRequest = String.join("\n", normalizedMethod, normalizedPath, normalizedQuery, normalizedHeaders, signedHeaders, bodyHash ); logger.debug("Canonical Request:\n{}", canonicalRequest); return canonicalRequest; } /** * Generate signature for request */ public String generateSignature( String method, String path, Map<String, String> headers, String body, String secret, String algorithm) { String signatureString = generateSignatureString(method, path, headers, body); HmacUtil hmacUtil = new HmacUtil(); return hmacUtil.calculateHmac(signatureString, secret, algorithm); } private String normalizePath(String path) { if (!StringUtils.hasText(path)) { return "/"; } // Add leading slash if missing if (!path.startsWith("/")) { path = "/" + path; } // URL encode path (simplified) return path; } private String normalizeHeaders(Map<String, String> headers) { if (headers == null || headers.isEmpty()) { return ""; } // Sort headers by name Map<String, String> sortedHeaders = new TreeMap<>(String.CASE_INSENSITIVE_ORDER); sortedHeaders.putAll(headers); // Format: lowercase(name):value return sortedHeaders.entrySet().stream() .map(entry -> entry.getKey().toLowerCase() + ":" + entry.getValue().trim()) .collect(Collectors.joining("\n")); } private String getSignedHeaders(Map<String, String> headers) { if (headers == null || headers.isEmpty()) { return ""; } return headers.keySet().stream() .map(String::toLowerCase) .sorted() .collect(Collectors.joining(";")); } private String calculateBodyHash(String body) { if (body == null || body.isEmpty()) { return calculateSHA256(""); } return calculateSHA256(body); } private String calculateSHA256(String data) { try { MessageDigest digest = MessageDigest.getInstance("SHA-256"); byte[] hash = digest.digest(data.getBytes(StandardCharsets.UTF_8)); return Base64.getEncoder().encodeToString(hash); } catch (NoSuchAlgorithmException e) { throw new RuntimeException("SHA-256 algorithm not available", e); } } }
3. Data Models
// ApiKey.java package com.example.hmac.model; import javax.persistence.*; import java.time.LocalDateTime; import java.util.UUID; @Entity @Table(name = "api_keys") public class ApiKey { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id; @Column(name = "key_id", unique = true, nullable = false) private String keyId; @Column(name = "secret_key", nullable = false) private String secretKey; @Column(name = "client_name", nullable = false) private String clientName; @Column(name = "algorithm", nullable = false) private String algorithm = "HmacSHA256"; @Column(name = "is_active", nullable = false) private Boolean isActive = true; @Column(name = "created_at", nullable = false) private LocalDateTime createdAt; @Column(name = "last_used") private LocalDateTime lastUsed; @Column(name = "expires_at") private LocalDateTime expiresAt; @PrePersist protected void onCreate() { if (keyId == null) { keyId = UUID.randomUUID().toString(); } if (createdAt == null) { createdAt = LocalDateTime.now(); } } // Getters and setters public Long getId() { return id; } public void setId(Long id) { this.id = id; } public String getKeyId() { return keyId; } public void setKeyId(String keyId) { this.keyId = keyId; } public String getSecretKey() { return secretKey; } public void setSecretKey(String secretKey) { this.secretKey = secretKey; } public String getClientName() { return clientName; } public void setClientName(String clientName) { this.clientName = clientName; } public String getAlgorithm() { return algorithm; } public void setAlgorithm(String algorithm) { this.algorithm = algorithm; } public Boolean getIsActive() { return isActive; } public void setIsActive(Boolean isActive) { this.isActive = isActive; } public LocalDateTime getCreatedAt() { return createdAt; } public void setCreatedAt(LocalDateTime createdAt) { this.createdAt = createdAt; } public LocalDateTime getLastUsed() { return lastUsed; } public void setLastUsed(LocalDateTime lastUsed) { this.lastUsed = lastUsed; } public LocalDateTime getExpiresAt() { return expiresAt; } public void setExpiresAt(LocalDateTime expiresAt) { this.expiresAt = expiresAt; } public boolean isValid() { return Boolean.TRUE.equals(isActive) && (expiresAt == null || expiresAt.isAfter(LocalDateTime.now())); } } // HmacSignature.java package com.example.hmac.model; import java.util.Map; public class HmacSignature { private String keyId; private String algorithm; private String signature; private Map<String, String> headers; private Long timestamp; private String nonce; public HmacSignature() {} public HmacSignature(String keyId, String algorithm, String signature, Map<String, String> headers, Long timestamp, String nonce) { this.keyId = keyId; this.algorithm = algorithm; this.signature = signature; this.headers = headers; this.timestamp = timestamp; this.nonce = nonce; } // Getters and setters public String getKeyId() { return keyId; } public void setKeyId(String keyId) { this.keyId = keyId; } public String getAlgorithm() { return algorithm; } public void setAlgorithm(String algorithm) { this.algorithm = algorithm; } public String getSignature() { return signature; } public void setSignature(String signature) { this.signature = signature; } public Map<String, String> getHeaders() { return headers; } public void setHeaders(Map<String, String> headers) { this.headers = headers; } public Long getTimestamp() { return timestamp; } public void setTimestamp(Long timestamp) { this.timestamp = timestamp; } public String getNonce() { return nonce; } public void setNonce(String nonce) { this.nonce = nonce; } } // AuthenticationResult.java package com.example.hmac.model; public class AuthenticationResult { private boolean authenticated; private ApiKey apiKey; private String errorMessage; private String clientName; public AuthenticationResult(boolean authenticated, ApiKey apiKey) { this.authenticated = authenticated; this.apiKey = apiKey; this.clientName = apiKey != null ? apiKey.getClientName() : null; } public AuthenticationResult(String errorMessage) { this.authenticated = false; this.errorMessage = errorMessage; } // Getters public boolean isAuthenticated() { return authenticated; } public ApiKey getApiKey() { return apiKey; } public String getErrorMessage() { return errorMessage; } public String getClientName() { return clientName; } public static AuthenticationResult success(ApiKey apiKey) { return new AuthenticationResult(true, apiKey); } public static AuthenticationResult failure(String errorMessage) { return new AuthenticationResult(errorMessage); } }
4. Repository Layer
// ApiKeyRepository.java package com.example.hmac.repository; import com.example.hmac.model.ApiKey; import org.springframework.data.jpa.repository.JpaRepository; import org.springframework.data.jpa.repository.Modifying; import org.springframework.data.jpa.repository.Query; import org.springframework.data.repository.query.Param; import org.springframework.stereotype.Repository; import java.time.LocalDateTime; import java.util.Optional; @Repository public interface ApiKeyRepository extends JpaRepository<ApiKey, Long> { Optional<ApiKey> findByKeyIdAndIsActiveTrue(String keyId); Optional<ApiKey> findByKeyId(String keyId); @Modifying @Query("UPDATE ApiKey k SET k.lastUsed = :lastUsed WHERE k.keyId = :keyId") void updateLastUsed(@Param("keyId") String keyId, @Param("lastUsed") LocalDateTime lastUsed); @Modifying @Query("UPDATE ApiKey k SET k.isActive = false WHERE k.expiresAt < :now") int deactivateExpiredKeys(@Param("now") LocalDateTime now); }

Server-Side Implementation

1. HMAC Authentication Service
// HmacAuthenticationService.java package com.example.hmac.service; import com.example.hmac.model.ApiKey; import com.example.hmac.model.AuthenticationResult; import com.example.hmac.model.HmacSignature; import com.example.hmac.repository.ApiKeyRepository; import com.example.hmac.util.HmacUtil; import com.example.hmac.util.SignatureGenerator; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.beans.factory.annotation.Value; import org.springframework.stereotype.Service; import javax.servlet.http.HttpServletRequest; import java.time.LocalDateTime; import java.util.*; @Service public class HmacAuthenticationService { private static final Logger logger = LoggerFactory.getLogger(HmacAuthenticationService.class); private final ApiKeyRepository apiKeyRepository; private final HmacUtil hmacUtil; private final SignatureGenerator signatureGenerator; @Value("${app.hmac.timestamp-validity:300000}") private long timestampValidity; // Nonce cache to prevent replay attacks (in production, use Redis) private final Set<String> usedNonces = Collections.synchronizedSet(new HashSet<>()); public HmacAuthenticationService(ApiKeyRepository apiKeyRepository, HmacUtil hmacUtil, SignatureGenerator signatureGenerator) { this.apiKeyRepository = apiKeyRepository; this.hmacUtil = hmacUtil; this.signatureGenerator = signatureGenerator; } /** * Authenticate HMAC signature from HTTP request */ public AuthenticationResult authenticateRequest(HttpServletRequest request, String body) { try { // Extract signature from Authorization header HmacSignature signature = extractSignature(request); if (signature == null) { return AuthenticationResult.failure("Missing or invalid Authorization header"); } // Validate timestamp to prevent replay attacks if (!isTimestampValid(signature.getTimestamp())) { return AuthenticationResult.failure("Invalid timestamp"); } // Validate nonce to prevent replay attacks if (!isNonceValid(signature.getNonce())) { return AuthenticationResult.failure("Invalid or reused nonce"); } // Find API key Optional<ApiKey> apiKeyOpt = apiKeyRepository.findByKeyIdAndIsActiveTrue(signature.getKeyId()); if (apiKeyOpt.isEmpty()) { return AuthenticationResult.failure("Invalid API key"); } ApiKey apiKey = apiKeyOpt.get(); // Validate algorithm if (!hmacUtil.isValidAlgorithm(signature.getAlgorithm())) { return AuthenticationResult.failure("Unsupported algorithm: " + signature.getAlgorithm()); } // Verify signature if (!verifySignature(request, body, signature, apiKey)) { return AuthenticationResult.failure("Invalid signature"); } // Update last used timestamp updateLastUsed(apiKey); logger.info("HMAC authentication successful for client: {}", apiKey.getClientName()); return AuthenticationResult.success(apiKey); } catch (Exception e) { logger.error("HMAC authentication failed", e); return AuthenticationResult.failure("Authentication failed: " + e.getMessage()); } } /** * Extract HMAC signature from Authorization header * Format: HMAC keyId="key",algorithm="hmac-sha256",headers="date digest",signature="base64signature" */ private HmacSignature extractSignature(HttpServletRequest request) { String authHeader = request.getHeader("Authorization"); if (authHeader == null || !authHeader.startsWith("HMAC ")) { return null; } try { String hmacPart = authHeader.substring(5); // Remove "HMAC " Map<String, String> params = parseAuthParams(hmacPart); String keyId = params.get("keyId"); String algorithm = params.get("algorithm"); String signature = params.get("signature"); String headers = params.get("headers"); String timestamp = params.get("timestamp"); String nonce = params.get("nonce"); if (keyId == null || algorithm == null || signature == null) { return null; } // Parse timestamp Long timestampLong = timestamp != null ? Long.parseLong(timestamp) : null; // Extract signed headers Map<String, String> signedHeaders = extractSignedHeaders(request, headers); return new HmacSignature(keyId, algorithm, signature, signedHeaders, timestampLong, nonce); } catch (Exception e) { logger.error("Failed to parse Authorization header", e); return null; } } private Map<String, String> parseAuthParams(String authString) { Map<String, String> params = new HashMap<>(); String[] parts = authString.split(","); for (String part : parts) { String[] keyValue = part.split("=", 2); if (keyValue.length == 2) { String key = keyValue[0].trim(); String value = keyValue[1].trim().replace("\"", ""); params.put(key, value); } } return params; } private Map<String, String> extractSignedHeaders(HttpServletRequest request, String headersList) { Map<String, String> headers = new HashMap<>(); if (headersList != null) { String[] headerNames = headersList.toLowerCase().split(" "); for (String headerName : headerNames) { String headerValue = request.getHeader(headerName); if (headerValue != null) { headers.put(headerName, headerValue); } } } // Always include (request-target) pseudo-header String requestTarget = request.getMethod().toLowerCase() + " " + request.getRequestURI(); headers.put("(request-target)", requestTarget); return headers; } private boolean verifySignature(HttpServletRequest request, String body, HmacSignature signature, ApiKey apiKey) { try { // Recreate signature string String signatureString = signatureGenerator.generateSignatureString( request.getMethod(), request.getRequestURI(), signature.getHeaders(), body ); // Verify HMAC return hmacUtil.verifyHmac( signatureString, apiKey.getSecretKey(), signature.getAlgorithm(), signature.getSignature() ); } catch (Exception e) { logger.error("Signature verification failed", e); return false; } } private boolean isTimestampValid(Long timestamp) { if (timestamp == null) { return false; } long currentTime = System.currentTimeMillis(); long timeDiff = Math.abs(currentTime - timestamp); return timeDiff <= timestampValidity; } private boolean isNonceValid(String nonce) { if (nonce == null || nonce.length() < 16) { return false; } // Check if nonce was already used if (usedNonces.contains(nonce)) { return false; } // Add to used nonces (in production, use TTL cache) usedNonces.add(nonce); // Clean up old nonces periodically (simplified) if (usedNonces.size() > 10000) { usedNonces.clear(); } return true; } private void updateLastUsed(ApiKey apiKey) { try { apiKey.setLastUsed(LocalDateTime.now()); apiKeyRepository.save(apiKey); } catch (Exception e) { logger.warn("Failed to update last used timestamp for key: {}", apiKey.getKeyId(), e); } } /** * Clean up expired nonces (call periodically) */ public void cleanupExpiredNonces() { // In production implementation, use TTL-based cache usedNonces.clear(); } }
2. Spring Security Filter
// HmacAuthenticationFilter.java package com.example.hmac.security; import com.example.hmac.model.AuthenticationResult; import com.example.hmac.service.HmacAuthenticationService; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.security.authentication.UsernamePasswordAuthenticationToken; import org.springframework.security.core.authority.SimpleGrantedAuthority; import org.springframework.security.core.context.SecurityContextHolder; import org.springframework.web.filter.OncePerRequestFilter; import javax.servlet.FilterChain; import javax.servlet.ServletException; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import java.io.IOException; import java.util.Collections; public class HmacAuthenticationFilter extends OncePerRequestFilter { private static final Logger logger = LoggerFactory.getLogger(HmacAuthenticationFilter.class); private final HmacAuthenticationService hmacAuthenticationService; public HmacAuthenticationFilter(HmacAuthenticationService hmacAuthenticationService) { this.hmacAuthenticationService = hmacAuthenticationService; } @Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { // Skip authentication for certain paths if (shouldSkipAuthentication(request)) { filterChain.doFilter(request, response); return; } // Read request body for signature verification String requestBody = getRequestBody(request); // Authenticate request AuthenticationResult authResult = hmacAuthenticationService.authenticateRequest(request, requestBody); if (authResult.isAuthenticated()) { // Set authentication in security context UsernamePasswordAuthenticationToken authentication = new UsernamePasswordAuthenticationToken( authResult.getClientName(), null, Collections.singletonList(new SimpleGrantedAuthority("ROLE_API_CLIENT")) ); SecurityContextHolder.getContext().setAuthentication(authentication); logger.debug("HMAC authentication successful for: {}", authResult.getClientName()); filterChain.doFilter(request, response); } else { // Authentication failed logger.warn("HMAC authentication failed: {}", authResult.getErrorMessage()); sendAuthenticationError(response, authResult.getErrorMessage()); } } private boolean shouldSkipAuthentication(HttpServletRequest request) { String path = request.getRequestURI(); return path.startsWith("/public/") || path.equals("/health") || path.equals("/api-keys/register"); } private String getRequestBody(HttpServletRequest request) { // For simplicity, we're not reading the body here as it can only be read once // In production, use ContentCachingRequestWrapper or similar approach return ""; } private void sendAuthenticationError(HttpServletResponse response, String message) throws IOException { response.setStatus(HttpServletResponse.SC_UNAUTHORIZED); response.setContentType("application/json"); response.getWriter().write(String.format( "{\"error\":\"authentication_failed\",\"message\":\"%s\"}", message )); } }
3. Security Configuration
// SecurityConfig.java package com.example.hmac.config; import com.example.hmac.security.HmacAuthenticationFilter; import com.example.hmac.service.HmacAuthenticationService; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity; import org.springframework.security.config.annotation.web.builders.HttpSecurity; import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity; import org.springframework.security.config.http.SessionCreationPolicy; import org.springframework.security.web.SecurityFilterChain; import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter; @Configuration @EnableWebSecurity @EnableMethodSecurity(prePostEnabled = true) public class SecurityConfig { @Bean public SecurityFilterChain securityFilterChain(HttpSecurity http, HmacAuthenticationService hmacAuthenticationService) throws Exception { http .csrf(csrf -> csrf.disable()) .sessionManagement(session -> session .sessionCreationPolicy(SessionCreationPolicy.STATELESS) ) .authorizeHttpRequests(authz -> authz .requestMatchers("/public/**", "/health", "/api-keys/register").permitAll() .anyRequest().authenticated() ) .addFilterBefore( new HmacAuthenticationFilter(hmacAuthenticationService), UsernamePasswordAuthenticationFilter.class ); return http.build(); } }

Client-Side Implementation

1. HMAC Client Library
// HmacClient.java package com.example.hmac.client; import com.example.hmac.util.HmacUtil; import com.example.hmac.util.SignatureGenerator; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.http.*; import org.springframework.web.client.RestTemplate; import java.nio.charset.StandardCharsets; import java.security.MessageDigest; import java.util.*; public class HmacClient { private static final Logger logger = LoggerFactory.getLogger(HmacClient.class); private final String baseUrl; private final String keyId; private final String secretKey; private final String algorithm; private final RestTemplate restTemplate; private final HmacUtil hmacUtil; private final SignatureGenerator signatureGenerator; public HmacClient(String baseUrl, String keyId, String secretKey, String algorithm) { this.baseUrl = baseUrl; this.keyId = keyId; this.secretKey = secretKey; this.algorithm = algorithm; this.restTemplate = new RestTemplate(); this.hmacUtil = new HmacUtil(); this.signatureGenerator = new SignatureGenerator(); } /** * Send GET request with HMAC authentication */ public <T> ResponseEntity<T> get(String path, Class<T> responseType) { return exchange(path, HttpMethod.GET, null, responseType); } /** * Send POST request with HMAC authentication */ public <T> ResponseEntity<T> post(String path, Object body, Class<T> responseType) { return exchange(path, HttpMethod.POST, body, responseType); } /** * Send PUT request with HMAC authentication */ public <T> ResponseEntity<T> put(String path, Object body, Class<T> responseType) { return exchange(path, HttpMethod.PUT, body, responseType); } /** * Send DELETE request with HMAC authentication */ public <T> ResponseEntity<T> delete(String path, Class<T> responseType) { return exchange(path, HttpMethod.DELETE, null, responseType); } private <T> ResponseEntity<T> exchange(String path, HttpMethod method, Object body, Class<T> responseType) { String url = baseUrl + path; String bodyString = body != null ? body.toString() : ""; // Create headers HttpHeaders headers = createHeaders(method, path, bodyString); // Create request entity HttpEntity<?> requestEntity = body != null ? new HttpEntity<>(body, headers) : new HttpEntity<>(headers); // Send request return restTemplate.exchange(url, method, requestEntity, responseType); } private HttpHeaders createHeaders(String method, String path, String body) { HttpHeaders headers = new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); // Add required headers for signature String timestamp = String.valueOf(System.currentTimeMillis()); String nonce = generateNonce(); String digest = calculateDigest(body); headers.set("Date", new Date().toString()); headers.set("X-Timestamp", timestamp); headers.set("X-Nonce", nonce); headers.set("Digest", "SHA-256=" + digest); // Generate signature Map<String, String> signatureHeaders = new HashMap<>(); signatureHeaders.put("(request-target)", method.toLowerCase() + " " + path); signatureHeaders.put("date", headers.getFirst("Date")); signatureHeaders.put("digest", headers.getFirst("Digest")); signatureHeaders.put("content-type", MediaType.APPLICATION_JSON_VALUE); String signature = signatureGenerator.generateSignature( method, path, signatureHeaders, body, secretKey, algorithm ); // Build Authorization header String authHeader = buildAuthorizationHeader(signature, timestamp, nonce); headers.set("Authorization", authHeader); return headers; } private String buildAuthorizationHeader(String signature, String timestamp, String nonce) { return String.format( "HMAC keyId=\"%s\",algorithm=\"%s\",headers=\"(request-target) date digest content-type\",timestamp=\"%s\",nonce=\"%s\",signature=\"%s\"", keyId, algorithm, timestamp, nonce, signature ); } private String generateNonce() { return UUID.randomUUID().toString().replace("-", "").substring(0, 16); } private String calculateDigest(String body) { try { MessageDigest digest = MessageDigest.getInstance("SHA-256"); byte[] hash = digest.digest(body.getBytes(StandardCharsets.UTF_8)); return Base64.getEncoder().encodeToString(hash); } catch (Exception e) { throw new RuntimeException("Failed to calculate digest", e); } } }
2. Client Usage Example
// ClientExample.java package com.example.hmac.client; import org.springframework.http.ResponseEntity; import org.springframework.web.client.RestTemplate; public class ClientExample { public static void main(String[] args) { String baseUrl = "http://localhost:8080"; String keyId = "test-key-123"; String secretKey = "my-secret-key-12345"; String algorithm = "HmacSHA256"; HmacClient client = new HmacClient(baseUrl, keyId, secretKey, algorithm); try { // Test GET request ResponseEntity<String> response = client.get("/api/secure-data", String.class); System.out.println("GET Response: " + response.getBody()); // Test POST request String requestBody = "{\"message\": \"Hello HMAC\"}"; ResponseEntity<String> postResponse = client.post("/api/echo", requestBody, String.class); System.out.println("POST Response: " + postResponse.getBody()); } catch (Exception e) { System.err.println("Request failed: " + e.getMessage()); } } }

API Controllers

1. Secure API Controller
// SecureApiController.java package com.example.hmac.controller; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.http.ResponseEntity; import org.springframework.security.core.Authentication; import org.springframework.web.bind.annotation.*; import java.util.HashMap; import java.util.Map; @RestController @RequestMapping("/api") public class SecureApiController { private static final Logger logger = LoggerFactory.getLogger(SecureApiController.class); @GetMapping("/secure-data") public ResponseEntity<Map<String, Object>> getSecureData(Authentication authentication) { logger.info("Accessing secure data for: {}", authentication.getName()); Map<String, Object> data = new HashMap<>(); data.put("message", "This is secure data"); data.put("client", authentication.getName()); data.put("timestamp", System.currentTimeMillis()); data.put("data", Arrays.asList("item1", "item2", "item3")); return ResponseEntity.ok(data); } @PostMapping("/echo") public ResponseEntity<Map<String, Object>> echoMessage( @RequestBody Map<String, Object> request, Authentication authentication) { logger.info("Echo request from: {}", authentication.getName()); Map<String, Object> response = new HashMap<>(); response.put("echo", request); response.put("receivedBy", authentication.getName()); response.put("timestamp", System.currentTimeMillis()); return ResponseEntity.ok(response); } @PutMapping("/update") public ResponseEntity<Map<String, Object>> updateData( @RequestBody Map<String, Object> updateRequest, Authentication authentication) { logger.info("Update request from: {}", authentication.getName()); Map<String, Object> response = new HashMap<>(); response.put("status", "updated"); response.put("client", authentication.getName()); response.put("updatedFields", updateRequest.keySet()); return ResponseEntity.ok(response); } @DeleteMapping("/resource/{id}") public ResponseEntity<Map<String, Object>> deleteResource( @PathVariable String id, Authentication authentication) { logger.info("Delete request for resource {} from: {}", id, authentication.getName()); Map<String, Object> response = new HashMap<>(); response.put("status", "deleted"); response.put("resourceId", id); response.put("client", authentication.getName()); return ResponseEntity.ok(response); } }
2. API Key Management Controller
// ApiKeyController.java package com.example.hmac.controller; import com.example.hmac.model.ApiKey; import com.example.hmac.service.ApiKeyService; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.*; import java.util.List; import java.util.Map; @RestController @RequestMapping("/api-keys") public class ApiKeyController { private static final Logger logger = LoggerFactory.getLogger(ApiKeyController.class); private final ApiKeyService apiKeyService; public ApiKeyController(ApiKeyService apiKeyService) { this.apiKeyService = apiKeyService; } @PostMapping("/register") public ResponseEntity<Map<String, Object>> registerClient(@RequestBody Map<String, String> request) { String clientName = request.get("clientName"); String algorithm = request.getOrDefault("algorithm", "HmacSHA256"); if (clientName == null || clientName.trim().isEmpty()) { return ResponseEntity.badRequest().body(Map.of( "error", "clientName is required" )); } try { ApiKey apiKey = apiKeyService.generateApiKey(clientName, algorithm); logger.info("Generated new API key for client: {}", clientName); return ResponseEntity.ok(Map.of( "keyId", apiKey.getKeyId(), "secretKey", apiKey.getSecretKey(), "clientName", apiKey.getClientName(), "algorithm", apiKey.getAlgorithm(), "createdAt", apiKey.getCreatedAt() )); } catch (Exception e) { logger.error("Failed to generate API key for client: {}", clientName, e); return ResponseEntity.internalServerError().body(Map.of( "error", "Failed to generate API key: " + e.getMessage() )); } } @GetMapping public ResponseEntity<List<ApiKey>> listApiKeys() { List<ApiKey> apiKeys = apiKeyService.getAllActiveKeys(); return ResponseEntity.ok(apiKeys); } @DeleteMapping("/{keyId}") public ResponseEntity<Map<String, Object>> revokeApiKey(@PathVariable String keyId) { try { apiKeyService.revokeApiKey(keyId); logger.info("Revoked API key: {}", keyId); return ResponseEntity.ok(Map.of("status", "revoked", "keyId", keyId)); } catch (Exception e) { return ResponseEntity.badRequest().body(Map.of("error", e.getMessage())); } } }
3. API Key Service
// ApiKeyService.java package com.example.hmac.service; import com.example.hmac.model.ApiKey; import com.example.hmac.repository.ApiKeyRepository; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.stereotype.Service; import java.security.SecureRandom; import java.time.LocalDateTime; import java.util.Base64; import java.util.List; import java.util.Optional; @Service public class ApiKeyService { private static final Logger logger = LoggerFactory.getLogger(ApiKeyService.class); private final ApiKeyRepository apiKeyRepository; private final SecureRandom secureRandom; public ApiKeyService(ApiKeyRepository apiKeyRepository) { this.apiKeyRepository = apiKeyRepository; this.secureRandom = new SecureRandom(); } /** * Generate new API key for client */ public ApiKey generateApiKey(String clientName, String algorithm) { String keyId = generateRandomString(16); String secretKey = generateRandomString(32); ApiKey apiKey = new ApiKey(); apiKey.setKeyId(keyId); apiKey.setSecretKey(secretKey); apiKey.setClientName(clientName); apiKey.setAlgorithm(algorithm); apiKey.setIsActive(true); apiKey.setCreatedAt(LocalDateTime.now()); return apiKeyRepository.save(apiKey); } /** * Get all active API keys */ public List<ApiKey> getAllActiveKeys() { return apiKeyRepository.findAll().stream() .filter(ApiKey::isValid) .toList(); } /** * Revoke API key */ public void revokeApiKey(String keyId) { Optional<ApiKey> apiKeyOpt = apiKeyRepository.findByKeyId(keyId); if (apiKeyOpt.isPresent()) { ApiKey apiKey = apiKeyOpt.get(); apiKey.setIsActive(false); apiKeyRepository.save(apiKey); logger.info("Revoked API key: {}", keyId); } else { throw new IllegalArgumentException("API key not found: " + keyId); } } /** * Clean up expired API keys */ public int cleanupExpiredKeys() { return apiKeyRepository.deactivateExpiredKeys(LocalDateTime.now()); } private String generateRandomString(int length) { byte[] bytes = new byte[length]; secureRandom.nextBytes(bytes); return Base64.getUrlEncoder().withoutPadding().encodeToString(bytes); } }

Testing

1. Unit Tests
// HmacUtilTest.java package com.example.hmac.util; import org.junit.jupiter.api.Test; import static org.junit.jupiter.api.Assertions.*; class HmacUtilTest { private final HmacUtil hmacUtil = new HmacUtil(); @Test void testCalculateHmac() { String data = "test data"; String secret = "test secret"; String algorithm = "HmacSHA256"; String signature = hmacUtil.calculateHmac(data, secret, algorithm); assertNotNull(signature); assertFalse(signature.isEmpty()); } @Test void testVerifyHmac() { String data = "test data"; String secret = "test secret"; String algorithm = "HmacSHA256"; String signature = hmacUtil.calculateHmac(data, secret, algorithm); boolean isValid = hmacUtil.verifyHmac(data, secret, algorithm, signature); assertTrue(isValid); } @Test void testInvalidAlgorithm() { assertFalse(hmacUtil.isValidAlgorithm("InvalidAlgorithm")); assertTrue(hmacUtil.isValidAlgorithm("HmacSHA256")); } } // HmacAuthenticationServiceTest.java package com.example.hmac.service; import com.example.hmac.model.ApiKey; import com.example.hmac.repository.ApiKeyRepository; import com.example.hmac.util.HmacUtil; import com.example.hmac.util.SignatureGenerator; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.extension.ExtendWith; import org.mockito.Mock; import org.mockito.junit.jupiter.MockitoExtension; import javax.servlet.http.HttpServletRequest; import java.time.LocalDateTime; import java.util.Optional; import static org.junit.jupiter.api.Assertions.*; import static org.mockito.ArgumentMatchers.*; import static org.mockito.Mockito.*; @ExtendWith(MockitoExtension.class) class HmacAuthenticationServiceTest { @Mock private ApiKeyRepository apiKeyRepository; @Mock private HmacUtil hmacUtil; @Mock private SignatureGenerator signatureGenerator; @Mock private HttpServletRequest request; private HmacAuthenticationService authService; @BeforeEach void setUp() { authService = new HmacAuthenticationService(apiKeyRepository, hmacUtil, signatureGenerator); } @Test void testAuthenticationWithValidSignature() { // Setup when(request.getHeader("Authorization")).thenReturn( "HMAC keyId=\"test-key\",algorithm=\"HmacSHA256\",headers=\"date\",signature=\"test-sig\",timestamp=\"123456789\",nonce=\"abc123\"" ); when(request.getMethod()).thenReturn("GET"); when(request.getRequestURI()).thenReturn("/api/test"); ApiKey apiKey = new ApiKey(); apiKey.setKeyId("test-key"); apiKey.setSecretKey("secret"); apiKey.setClientName("test-client"); apiKey.setIsActive(true); when(apiKeyRepository.findByKeyIdAndIsActiveTrue("test-key")) .thenReturn(Optional.of(apiKey)); when(hmacUtil.isValidAlgorithm("HmacSHA256")).thenReturn(true); when(hmacUtil.verifyHmac(anyString(), anyString(), anyString(), anyString())) .thenReturn(true); // Execute var result = authService.authenticateRequest(request, ""); // Verify assertTrue(result.isAuthenticated()); assertEquals("test-client", result.getClientName()); } }
2. Integration Test
// HmacIntegrationTest.java package com.example.hmac.integration; import com.example.hmac.model.ApiKey; import com.example.hmac.repository.ApiKeyRepository; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.context.SpringBootTest; import org.springframework.boot.test.web.client.TestRestTemplate; import org.springframework.http.*; import org.springframework.test.context.ActiveProfiles; import java.util.Map; import static org.junit.jupiter.api.Assertions.*; @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) @ActiveProfiles("test") class HmacIntegrationTest { @Autowired private TestRestTemplate restTemplate; @Autowired private ApiKeyRepository apiKeyRepository; private ApiKey testApiKey; @BeforeEach void setUp() { // Create test API key testApiKey = new ApiKey(); testApiKey.setKeyId("test-key-integration"); testApiKey.setSecretKey("integration-secret-key-123"); testApiKey.setClientName("integration-test"); testApiKey.setAlgorithm("HmacSHA256"); testApiKey.setIsActive(true); apiKeyRepository.save(testApiKey); } @Test void testUnauthorizedAccess() { ResponseEntity<String> response = restTemplate.getForEntity("/api/secure-data", String.class); assertEquals(HttpStatus.UNAUTHORIZED, response.getStatusCode()); } @Test void testApiKeyRegistration() { Map<String, String> request = Map.of("clientName", "test-client"); ResponseEntity<Map> response = restTemplate.postForEntity( "/api-keys/register", request, Map.class); assertEquals(HttpStatus.OK, response.getStatusCode()); assertNotNull(response.getBody().get("keyId")); assertNotNull(response.getBody().get("secretKey")); } }

Production Considerations

1. Enhanced Security Features
// RateLimitingService.java package com.example.hmac.service; import org.springframework.stereotype.Service; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.atomic.AtomicInteger; @Service public class RateLimitingService { private final ConcurrentHashMap<String, AtomicInteger> requestCounts = new ConcurrentHashMap<>(); private final int maxRequestsPerMinute = 100; public boolean isRateLimited(String clientId) { String key = clientId + ":" + (System.currentTimeMillis() / 60000); AtomicInteger count = requestCounts.computeIfAbsent(key, k -> new AtomicInteger(0)); return count.incrementAndGet() > maxRequestsPerMinute; } public void cleanupOldEntries() { long currentMinute = System.currentTimeMillis() / 60000; requestCounts.keySet().removeIf(key -> { long keyMinute = Long.parseLong(key.split(":")[1]); return currentMinute - keyMinute > 1; // Remove entries older than 1 minute }); } }
2. Monitoring and Metrics
// HmacMetricsService.java package com.example.hmac.service; import io.micrometer.core.instrument.Counter; import io.micrometer.core.instrument.MeterRegistry; import org.springframework.stereotype.Service; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.atomic.AtomicLong; @Service public class HmacMetricsService { private final Counter authenticationSuccess; private final Counter authenticationFailure; private final ConcurrentHashMap<String, AtomicLong> clientRequestCounts; public HmacMetricsService(MeterRegistry registry) { this.authenticationSuccess = Counter.builder("hmac.auth.success") .description("Successful HMAC authentications") .register(registry); this.authenticationFailure = Counter.builder("hmac.auth.failure") .description("Failed HMAC authentications") .register(registry); this.clientRequestCounts = new ConcurrentHashMap<>(); } public void recordAuthenticationSuccess(String clientId) { authenticationSuccess.increment(); clientRequestCounts.computeIfAbsent(clientId, k -> new AtomicLong(0)).incrementAndGet(); } public void recordAuthenticationFailure() { authenticationFailure.increment(); } public long getRequestCount(String clientId) { AtomicLong count = clientRequestCounts.get(clientId); return count != null ? count.get() : 0; } }

Best Practices

  1. Security:
  • Use strong random number generation for secrets
  • Implement proper key rotation policies
  • Use constant-time comparison for signature verification
  • Validate all input parameters
  1. Performance:
  • Cache API key lookups when appropriate
  • Use efficient data structures for nonce tracking
  • Implement connection pooling for database access
  1. Monitoring:
  • Log authentication attempts (success/failure)
  • Track rate limiting events
  • Monitor key usage patterns
  1. Operations:
  • Implement key expiration and rotation
  • Provide key revocation capabilities
  • Backup key storage securely

Conclusion

This HMAC signature authentication implementation provides:

  • Secure API authentication without transmitting passwords
  • Replay attack protection through timestamps and nonces
  • Request integrity verification via signature validation
  • Production-ready features including rate limiting and monitoring
  • Comprehensive client and server implementations

The solution can be extended with additional features like:

  • JWT token issuance after HMAC authentication
  • Advanced rate limiting strategies
  • Key rotation automation
  • Audit logging and compliance features
  • Multi-tenant key management
Category : JAVA

Leave a Reply

Your email address will not be published. Required fields are marked *


Macro Nepal Helper