org.apache.commons.codec.digest

Class HmacUtils

java.lang.Object

org.apache.commons.codec.digest.HmacUtils

public final class HmacUtils
extends Object

Simplifies common Mac tasks. This class is immutable and thread-safe. However the Mac may not be.

Note: Not all JCE implementations support all algorithms. If not supported, an IllegalArgumentException is thrown.

Sample usage:

 import static HmacAlgorithms.*;
 byte[] key = {1,2,3,4}; // don't use this actual key!
 String valueToDigest = "The quick brown fox jumps over the lazy dog";
 byte[] hmac = new HmacUtils(HMAC_SHA_224, key).hmac(valueToDigest);
 // Mac re-use
 HmacUtils hm1 = new HmacUtils("HmacAlgoName", key); // use a valid name here!
 String hexPom = hm1.hmacHex(new File("pom.xml"));
 String hexNot = hm1.hmacHex(new File("NOTICE.txt"));
 

Since:

1.10

Constructor Summary

Constructors

Constructor and Description
HmacUtils(HmacAlgorithms algorithm, byte[] key) Creates an instance using the provided algorithm type.
HmacUtils(HmacAlgorithms algorithm, String key) Creates an instance using the provided algorithm type.
HmacUtils(String algorithm, byte[] key) Creates an instance using the provided algorithm type.
HmacUtils(String algorithm, String key) Creates an instance using the provided algorithm type.

Method Summary

Modifier and Type	Method and Description
static Mac	getInitializedMac(HmacAlgorithms algorithm, byte[] key) Returns an initialized Mac for the given algorithm.
static Mac	getInitializedMac(String algorithm, byte[] key) Returns an initialized Mac for the given algorithm.
byte[]	hmac(byte[] valueToDigest) Returns the digest for the input data.
byte[]	hmac(ByteBuffer valueToDigest) Returns the digest for the input data.
byte[]	hmac(File valueToDigest) Returns the digest for the file.
byte[]	hmac(InputStream valueToDigest) Returns the digest for the stream.
byte[]	hmac(String valueToDigest) Returns the digest for the input data.
String	hmacHex(byte[] valueToDigest) Returns the digest for the input data.
String	hmacHex(ByteBuffer valueToDigest) Returns the digest for the input data.
String	hmacHex(File valueToDigest) Returns the digest for the file.
String	hmacHex(InputStream valueToDigest) Returns the digest for the stream.
String	hmacHex(String valueToDigest) Returns the digest for the input data.
static boolean	isAvailable(HmacAlgorithms name) Returns whether this algorithm is available
static boolean	isAvailable(String name) Returns whether this algorithm is available
static Mac	updateHmac(Mac mac, byte[] valueToDigest) Resets and then updates the given Mac with the value.
static Mac	updateHmac(Mac mac, InputStream valueToDigest) Resets and then updates the given Mac with the value.
static Mac	updateHmac(Mac mac, String valueToDigest) Resets and then updates the given Mac with the value.

Methods inherited from class java.lang.Object

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

Constructor Detail

HmacUtils

public HmacUtils(HmacAlgorithms algorithm,
                 byte[] key)

Creates an instance using the provided algorithm type.

Parameters:

algorithm - to use.

key - the key to use

Throws:

IllegalArgumentException - when a NoSuchAlgorithmException is caught or key is null or key is invalid.

Since:

1.11

HmacUtils

public HmacUtils(HmacAlgorithms algorithm,
                 String key)

Creates an instance using the provided algorithm type.

Parameters:

algorithm - to use

key - the key to use

Throws:

IllegalArgumentException - when a NoSuchAlgorithmException is caught or key is null or key is invalid.

Since:

1.11

HmacUtils

public HmacUtils(String algorithm,
                 byte[] key)

Creates an instance using the provided algorithm type.

Parameters:

algorithm - to use

key - the key to use

Throws:

IllegalArgumentException - when a NoSuchAlgorithmException is caught or key is null or key is invalid.

Since:

1.11

HmacUtils

public HmacUtils(String algorithm,
                 String key)

Creates an instance using the provided algorithm type.

Parameters:

algorithm - to use

key - the key to use

Throws:

IllegalArgumentException - when a NoSuchAlgorithmException is caught or key is null or key is invalid.

Since:

1.11

Method Detail

getInitializedMac

public static Mac getInitializedMac(HmacAlgorithms algorithm,
                                    byte[] key)

Returns an initialized Mac for the given algorithm.

Parameters:

algorithm - the name of the algorithm requested. See Appendix A in the Java Cryptography Architecture Reference Guide for information about standard algorithm names.

key - They key for the keyed digest (must not be null)

Returns:

A Mac instance initialized with the given key.

Throws:

IllegalArgumentException - when a NoSuchAlgorithmException is caught or key is null or key is invalid.

See Also:

Mac.getInstance(String), Mac.init(Key)

getInitializedMac

public static Mac getInitializedMac(String algorithm,
                                    byte[] key)

Returns an initialized Mac for the given algorithm.

Parameters:

algorithm - the name of the algorithm requested. See Appendix A in the Java Cryptography Architecture Reference Guide for information about standard algorithm names.

key - They key for the keyed digest (must not be null)

Returns:

A Mac instance initialized with the given key.

Throws:

IllegalArgumentException - when a NoSuchAlgorithmException is caught or key is null or key is invalid.

See Also:

Mac.getInstance(String), Mac.init(Key)

hmac

public byte[] hmac(byte[] valueToDigest)

Returns the digest for the input data.

Parameters:

valueToDigest - the input to use

Returns:

the digest as a byte[]

Since:

1.11

hmac

public byte[] hmac(ByteBuffer valueToDigest)

Returns the digest for the input data.

Parameters:

valueToDigest - the input to use

Returns:

the digest as a byte[]

Since:

1.11

hmac

public byte[] hmac(File valueToDigest)
            throws IOException

Returns the digest for the file.

Parameters:

valueToDigest - the file to use

Returns:

the digest

Throws:

IOException - If an I/O error occurs.

Since:

1.11

hmac

public byte[] hmac(InputStream valueToDigest)
            throws IOException

Returns the digest for the stream.

Parameters:

valueToDigest - the data to use

The InputStream must not be null and will not be closed

Returns:

the digest

Throws:

IOException - If an I/O error occurs.

Since:

1.11

hmac

public byte[] hmac(String valueToDigest)

Returns the digest for the input data.

Parameters:

valueToDigest - the input to use, treated as UTF-8

Returns:

the digest as a byte[]

Since:

1.11

hmacHex

public String hmacHex(byte[] valueToDigest)

Returns the digest for the input data.

Parameters:

valueToDigest - the input to use

Returns:

the digest as a hex String

Since:

1.11

hmacHex

public String hmacHex(ByteBuffer valueToDigest)

Returns the digest for the input data.

Parameters:

valueToDigest - the input to use

Returns:

the digest as a hex String

Since:

1.11

hmacHex

public String hmacHex(File valueToDigest)
               throws IOException

Returns the digest for the file.

Parameters:

valueToDigest - the file to use

Returns:

the digest as a hex String

Throws:

IOException - If an I/O error occurs.

Since:

1.11

hmacHex

public String hmacHex(InputStream valueToDigest)
               throws IOException

Returns the digest for the stream.

Parameters:

valueToDigest - the data to use

The InputStream must not be null and will not be closed

Returns:

the digest as a hex String

Throws:

IOException - If an I/O error occurs.

Since:

1.11

hmacHex

public String hmacHex(String valueToDigest)

Returns the digest for the input data.

Parameters:

valueToDigest - the input to use, treated as UTF-8

Returns:

the digest as a hex String

Since:

1.11

isAvailable

public static boolean isAvailable(HmacAlgorithms name)

Returns whether this algorithm is available

Parameters:

name - the name to check

Returns:

whether this algorithm is available

Since:

1.11

isAvailable

public static boolean isAvailable(String name)

Returns whether this algorithm is available

Parameters:

name - the name to check

Returns:

whether this algorithm is available

Since:

1.11

updateHmac

public static Mac updateHmac(Mac mac,
                             byte[] valueToDigest)

Resets and then updates the given Mac with the value.

Parameters:

mac - the initialized Mac to update

valueToDigest - the value to update the Mac with (maybe null or empty)

Returns:

the updated Mac

Throws:

IllegalStateException - if the Mac was not initialized

updateHmac

public static Mac updateHmac(Mac mac,
                             InputStream valueToDigest)
                      throws IOException

Resets and then updates the given Mac with the value.

Parameters:

mac - the initialized Mac to update

valueToDigest - the value to update the Mac with

The InputStream must not be null and will not be closed

Returns:

the updated Mac

Throws:

IOException - If an I/O error occurs.

IllegalStateException - If the Mac was not initialized

updateHmac

public static Mac updateHmac(Mac mac,
                             String valueToDigest)

Resets and then updates the given Mac with the value.

Parameters:

mac - the initialized Mac to update

valueToDigest - the value to update the Mac with (maybe null or empty)

Returns:

the updated Mac

Throws:

IllegalStateException - if the Mac was not initialized