public final class Hmac

Object
Hmac

Keyed-hash message authentication (HMAC, RFC 2104) on top of any hash algorithm supported by Hash. Use HMAC whenever you need to prove that a message came from somebody who shares a secret key with you and has not been modified in transit (signatures of API requests, session cookies, JWTs with the HS family, TOTP tokens, etc.).

Quick example

byte[] tag = Hmac.sha256(secret, message);

// streaming
Hmac h = Hmac.create(Hash.SHA256, secret);
h.update(part1);
h.update(part2);
byte[] tag2 = h.doFinal();

Compare authentication tags with [#constantTimeEquals(byte[], byte[])] – using java.util.Arrays.equals or == opens you up to timing attacks.

Methods

`public static` `Hmac create(String algorithm, byte[] key)`	Creates a streaming HMAC.
`public void reset()`	Resets the running HMAC so the instance can be reused with the same key.
`public void update(byte[] data)`	Appends bytes to the message being authenticated.
`public void update(byte[] data, int offset, int length)`	Appends a slice of bytes to the message being authenticated.
`public byte[] doFinal()`	Finalises and returns the authentication tag.
`public byte[] doFinal(byte[] data)`	One-shot convenience.
`public int tagLength()`	Number of bytes in the authentication tag produced by this HMAC.
`public static byte[] md5(byte[] key, byte[] data)`	One-shot HMAC-MD5.
`public static byte[] sha1(byte[] key, byte[] data)`	One-shot HMAC-SHA-1.
`public static byte[] sha224(byte[] key, byte[] data)`	One-shot HMAC-SHA-224.
`public static byte[] sha256(byte[] key, byte[] data)`	One-shot HMAC-SHA-256 (recommended default).
`public static byte[] sha384(byte[] key, byte[] data)`	One-shot HMAC-SHA-384.
`public static byte[] sha512(byte[] key, byte[] data)`	One-shot HMAC-SHA-512.
`public static boolean constantTimeEquals(byte[] a, byte[] b)`	Constant-time comparison of two byte arrays.

Inherited methods

From Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait, clone

Method details

create

public static Hmac create(String algorithm, byte[] key)

Creates a streaming HMAC.

Parameters

algorithm String: any algorithm accepted by Hash.create(String)
key byte[]: secret key. Keys longer than the hash block size are hashed down per RFC 2104; keys shorter than the block are zero-padded. There is no enforced minimum but for security 128-256 bits of entropy is recommended.

reset

public void reset()

Resets the running HMAC so the instance can be reused with the same key.

update

public void update(byte[] data)

Appends bytes to the message being authenticated.

update

public void update(byte[] data, int offset, int length)

Appends a slice of bytes to the message being authenticated.

doFinal

public byte[] doFinal()

Finalises and returns the authentication tag. The instance is reset and can be reused for another message with the same key.

doFinal

public byte[] doFinal(byte[] data)

One-shot convenience.

tagLength

public int tagLength()

Number of bytes in the authentication tag produced by this HMAC.

md5

public static byte[] md5(byte[] key, byte[] data)

One-shot HMAC-MD5. Legacy interop only – prefer HMAC-SHA-256.

sha1

public static byte[] sha1(byte[] key, byte[] data)

One-shot HMAC-SHA-1. Legacy interop only – prefer HMAC-SHA-256.

sha224

public static byte[] sha224(byte[] key, byte[] data)

One-shot HMAC-SHA-224.

sha256

public static byte[] sha256(byte[] key, byte[] data)

One-shot HMAC-SHA-256 (recommended default).

sha384

public static byte[] sha384(byte[] key, byte[] data)

One-shot HMAC-SHA-384.

sha512

public static byte[] sha512(byte[] key, byte[] data)

One-shot HMAC-SHA-512.

constantTimeEquals

public static boolean constantTimeEquals(byte[] a, byte[] b)

Constant-time comparison of two byte arrays. Returns false if the arrays differ in length. Use this when comparing authentication tags, session tokens, or any other secret value – Arrays.equals short circuits and is vulnerable to timing attacks.