An HMAC secret key in Java is the raw byte sequence you pass into a SecretKeySpec so that the javax.crypto.Mac engine can produce a keyed-hash message authentication code. HMAC itself is not encryption; it combines a cryptographic hash (SHA-256, SHA-384 or SHA-512) with a shared secret to produce a fixed-length tag that lets a verifier confirm both the integrity and the authenticity of a message. In Java you set the algorithm on the Mac instance (HmacSHA256, HmacSHA384, HmacSHA512) and hand it the exact same bytes the verifier will use. The hash determines the tag length: SHA-256 returns 32 bytes, SHA-384 returns 48 bytes, and SHA-512 returns 64 bytes, and the tag is conventionally written as lowercase hex or standard padded Base64. Because every byte of the key and every byte of the message feeds into the hash, the encoding choice (UTF-8 text versus hexadecimal bytes) and any stray whitespace can silently produce a different tag. Generating and verifying HMAC tags consistently therefore means fixing the algorithm, the key bytes and the message bytes exactly once, then reproducing them on both sides.
What Is an HMAC Secret Key in Java?
In the Java Cryptography Architecture, an HMAC secret key is any byte array you wrap with javax.crypto.spec.SecretKeySpec. The class does not generate the key for you; it just labels the bytes with an algorithm name so that Mac.getInstance(...) will accept them. The actual key material must come from a source with enough entropy: a KeyGenerator configured for the same HMAC algorithm, a SecureRandom byte sequence, or bytes agreed out-of-band with the verifier. Java's KeyGenerator.getInstance("HmacSHA256") initialized to a key size of 256 bits (32 bytes) is the standard way to obtain a fresh key for HMAC-SHA-256 inside the JVM; the same call with HmacSHA384 returns 384-bit material and HmacSHA512 returns 512-bit material.
A human-readable password is not automatically a strong HMAC key. If the protocol requires turning a password into a key, the password-based KDF (PBKDF2, scrypt, Argon2 or the specific scheme named in the specification) must be used with the exact salt, iteration count and length declared by the protocol. Improvising by hashing or truncating a password produces a key that looks plausible but breaks the threat model, because low-entropy inputs survive KDFs only when the parameters were chosen for that input class.
Once the bytes exist, new SecretKeySpec(keyBytes, "HmacSHA256") hands them to Mac. The algorithm string on the SecretKeySpec must match the algorithm string passed to Mac.getInstance(...), because the Mac engine refuses mismatches. Two different Java programs that both call HmacSHA256 over the same bytes will produce identical tags, and that agreement is the only thing the verifier needs.
Generate an HMAC Tag from the Browser
This is the fastest way to produce a reference tag and to check what your Java program emits. Open the HMAC Generator, enter the key and message the same way the protocol defines them, and copy the rendered tag in the encoding the receiver expects.
- Choose SHA-256, SHA-384 or SHA-512 and confirm the protocol or specification expects a full HMAC tag of that exact length (32, 48 or 64 bytes respectively).
- Select UTF-8 or hex independently for the key and for the message. Text mode encodes the field as UTF-8 bytes, so accented letters, CJK characters and emoji occupy multiple bytes; hex mode accepts only an even number of hexadecimal digits and preserves every byte, including zero.
- Enter the exact bytes without extra formatting. Do not paste prefixes such as 0x, do not insert spaces, colons or newlines, and do not let your editor auto-wrap long lines. Hex mode rejects prefixes, spaces, colons and odd nibbles so an accidental formatting character cannot silently change a protocol value.
- Generate the tag and copy it as lowercase hex or standard padded Base64. Hex and Base64 are two renderings of the same tag bytes; use whichever encoding the receiving system expects.
- Convert or truncate only when the protocol specification explicitly requires it. Some protocols want Base64url instead of standard Base64, some want a truncated tag (for example, the first 16 bytes of an HMAC-SHA-256), and some want a prefixed algorithm identifier. Apply those rules from the protocol document, not from visual inspection.
Because the operation runs through the browser Web Cryptography API and does not transmit inputs to the site server, you can paste local test vectors without leaking them. The page always shows the full tag; if the output looks shorter than the SHA variant should produce, the input was rejected before signing, not silently truncated.
Java Code Reference: javax.crypto.Mac
The Java reference path uses javax.crypto.Mac and javax.crypto.spec.SecretKeySpec. The shape of the code is the same for all three SHA variants; only the algorithm name and the resulting tag length change. When you build the byte array from a String, getBytes(StandardCharsets.UTF_8) is the only encoding that matches what the browser tool does in UTF-8 mode. Using the platform default charset silently produces different bytes on different operating systems, which is one of the classic causes of HMAC mismatches between development and production.
For a published test vector from RFC 4231 (Test Case 1 for HMAC-SHA-256), the key is 20 bytes of 0x0b and the data is the ASCII string Hi There. The HMAC-SHA-256 tag is the 32-byte hex string b0344c61d8db38535ca8afceaf0bf12b881dc200c9833da726e9376c2e32cff7. If your Java program and the browser tool both produce that exact hex under those exact bytes, the algorithm, the key bytes and the message encoding all agree; if they do not, the mismatch sits in one of those three places rather than in the hash implementation itself.
The verification path calls Mac.doFinal(messageBytes) and then compares the result against the tag the sender transmitted, using a constant-time comparison (MessageDigest.isEqual on the two byte arrays) so that timing differences do not leak information about a correct prefix. A plain Arrays.equals leaks timing; use a constant-time check on the server side.
Key Bytes, Encoding and Hash: What Changes the Tag
Four interacting choices determine whether two HMAC computations agree. Changing any one of them silently produces a different tag, even though the algorithm name still says "HMAC-SHA-256".
| Choice | Effect on the tag |
|---|---|
| Hash variant | SHA-256 returns 32 bytes; SHA-384 returns 48 bytes; SHA-512 returns 64 bytes. |
| Key encoding | UTF-8 text and hex bytes represent the same logical key only if you select matching input on the browser tool. A 3-byte ASCII key and its hex rendering produce different bytes and therefore different tags. |
| Message encoding | UTF-8 encodes accented letters, CJK characters and emoji as multi-byte sequences. Hex mode preserves every byte literally, including zero. Newlines, carriage returns and trailing spaces must match exactly. |
| Tag encoding | Lowercase hex and standard padded Base64 are renderings of identical bytes. Base64url (no padding, - and _) is not interchangeable with standard Base64; decoding the wrong form gives different bytes. |
When two systems refuse to agree, walk this table in order: confirm the hash, confirm the key bytes, confirm the message bytes, and only then check the tag encoding. Most mismatches live in the first three rows, not in the rendering.
Common Mistakes That Produce Mismatched Tags
The same symptom, two different tags, almost always traces back to one of a small set of mistakes. Treating them as a checklist speeds up debugging.
- Hash drift. The signer chose SHA-256 while the verifier assumed SHA-384, or vice versa. The tag lengths do not match even before encoding is checked.
- Key drift. The two sides agreed on the password but one ran it through a different KDF, a different salt or a different iteration count. The raw key bytes differ even though the human-readable secret looks identical.
- Message drift. A trailing newline was added by a logging layer, the JSON serializer escaped a character, or UTF-8 was conflated with Latin-1. Each of these changes the byte stream the hash sees.
- Encoding drift. One side wrote hex, the other wrote Base64url, the protocol expected standard Base64. Decoding the wrong form gives different bytes and the verifier fails.
- Truncated tags. A protocol that accepts truncated tags must say so explicitly. Trimming "by eye" to a round number of characters produces a tag the verifier rejects.
Each of these is recoverable: identify the protocol specification, lock the algorithm, lock the key bytes, lock the message bytes, and use the rendering the spec names. The HMAC Generator exposes all three hashes and both input encodings so you can reproduce each candidate interpretation and see which one matches.
When a Browser Tool Helps More Than Java Code
Java code is the right place for production signing and verification, because the JVM holds the secret in process memory and integrates with your key store and access control. The browser tool earns its place in two specific moments.
First, when you are debugging a tag mismatch. Rather than printing intermediate byte arrays from your production code, paste the published test vector into the HMAC Generator and confirm it reproduces the RFC 4231 result. Eight full RFC 4231 conformance tags are locked into the page, covering short keys, binary repeated-byte keys and data, keys smaller than the digest, and data that crosses hash block boundaries. If the tool matches the RFC and your Java code does not, the bug is in your key or message bytes; if the tool does not match the RFC, the input was typed in differently than you think.
Second, when you need to share a reference tag with a colleague or paste one into a Postman request. Because the Web Cryptography API runs entirely in the current tab and the page never sends inputs to a server, you can reproduce production-shaped tags on a laptop without standing up a Java environment. The page limits each decoded field to 1,000,000 bytes, which covers any realistic protocol message, and empty keys or messages are rejected so an accidental click cannot produce a misleading zero-length tag.
For everything else, keep the signing path inside Java where the secret never leaves the JVM and where constant-time comparison on the server is straightforward. Treat the browser tool as a reference calculator, not as a deployment surface.