# Class Hmac

java.lang.Object
com.codename1.security.Hmac

public final class Hmac extends java.lang.Object

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.

- ## Method Summary

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

  ### Methods inherited from class java.lang.Object

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

- ## Method Details

  - ### create

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

    Creates a streaming HMAC.

    ###### Parameters

    - `algorithm`: any algorithm accepted by `Hash.create(String)`

    - `key`: 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.