How to sign and verify a message with HMAC-SHA256 in Kotlin

1import java.security.MessageDigest
2import javax.crypto.Mac
3import javax.crypto.spec.SecretKeySpec
4 
5/** Sender: HMAC-SHA256 over the exact body bytes, sent as "sha256=<hex>". */
6fun sign(secret: ByteArray, rawBody: ByteArray): String = "sha256=" + hmacSha256(secret, rawBody).toHexString()
7 
8/** Receiver: recompute over the raw body and compare in constant time. */
9fun verify(secret: ByteArray, rawBody: ByteArray, header: String?): Boolean {
10    if (header == null || !header.startsWith("sha256=")) return false // a missing header fails
11    val received = runCatching { header.substring(7).hexToByteArray() }.getOrElse { return false }
12    return MessageDigest.isEqual(received, hmacSha256(secret, rawBody)) // not contentEquals
13}
14 
15private fun hmacSha256(secret: ByteArray, data: ByteArray): ByteArray =
16    Mac.getInstance("HmacSHA256").run { // a Mac is not thread-safe: one per call
17        init(SecretKeySpec(secret, "HmacSHA256"))
18        doFinal(data)
19    }
20 

How it works

1. Mac.getInstance("HmacSHA256") with SecretKeySpec(secret, "HmacSHA256") computes the MAC; ByteArray.toHexString() from the Kotlin standard library prints it in lower case after sha256=.
2. verify rejects a header without the sha256= prefix, decodes the rest with hexToByteArray() inside runCatching, and returns false for anything that does not decode.
3. MessageDigest.isEqual compares in constant time; ByteArray.contentEquals stops at the first difference and is the wrong tool for MACs.
4. A Mac keeps state and is not thread-safe, so hmacSha256 creates one per call — safe to call from concurrent request handlers. Compute the MAC over the request body bytes exactly as received, before any conversion to a string or a JSON object.
5. The run checks GitHub's example: Hello, World! with the secret It's a Secret to Everybody gives sha256=757107ea…3e17, and a tampered body, a wrong secret, a truncated or a missing header all fail.

Gotchas

• "757".hexToByteArray() throws NumberFormatException for an odd number of digits. Without runCatching (or a try/catch), a garbled header turns into a server error instead of a rejected request.
• hexToByteArray() accepts upper-case digits too — the run verifies sha256=757107EA… — so the comparison happens on bytes, not on hex strings whose case may differ between senders.
• MessageDigest.isEqual returns false for arrays of different lengths, so a truncated header is rejected (truncated header: false) without a separate length check — never trim the computed MAC to the received length.

Related recipes

• How to sign and verify a message with HMAC-SHA256 in Java
• How to sign and verify a message with HMAC-SHA256 in Swift
• How to sign and verify a message with HMAC-SHA256 in Go
• How to sign and verify a message with HMAC-SHA256 in Python
• How to verify an ES256 JWT in Kotlin