Class Hmac

java.lang.Object
com.codename1.security.Hmac
public final class Hmac extends 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 Object

    clone, equals, 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.