HMAC (cryptix JavaDoc)

java.lang.Object
- java.security.MessageDigestSpi
- - java.security.MessageDigest
  - - cryptix.provider.mac.HMAC

All Implemented Interfaces:

java.lang.Cloneable, Parameterized

Direct Known Subclasses:

HMAC_HAVAL, HMAC_MD2, HMAC_MD4, HMAC_MD5, HMAC_RIPEMD128, HMAC_RIPEMD160, HMAC_SHA0, HMAC_SHA1
```
public class HMAC
extends java.security.MessageDigest
implements Parameterized, java.lang.Cloneable
```
A class to implement the HMAC message authentication code, as described in RFC 2104.
The definition of HMAC-X for a given message digest algorithm X depends on that algorithm's internal block size, which is passed into the constructor when this class is used directly. Normally, this class will be obtained indirectly via the JCA API, e.g. MessageDigest.getInstance("HMAC-SHA-1") if SHA-1 is to be used as the digest algorithm.
The key can be set as a byte array using the "key" parameter. It is not reset after the MAC has been returned (this enables successive MACs using the same key to be calculated efficiently). For example:
```
    import java.security.Parameterized;
 

    MessageDigest hmac = MessageDigest.getInstance("HMAC-SHA-1");
    byte[] key = ..., input1 = ..., input2 = ...;
    ((Parameterized) mac).setParameter("key", key);
    byte[] mac1 = hmac.digest(input1);
    byte[] mac2 = hmac.digest(input2);
 
```
Parameters other than "key" are passed through to the MessageDigest object, but this can only be done when the key is not set. An explicit call to reset() will 'unset' the key.
This implementation does not support truncation of the output MAC. If truncation is desired, the caller should use only the relevant initial bits of the output array.
Note that although this class implements Cloneable, its clone() method will throw a CloneNotSupportedException if the underlying MessageDigest cannot be cloned. This should not be the case for any of the Cryptix-supported digest algorithms.
HMAC is similar, but not identical to the MAC used by Secure Sockets Layer version 3. The JCA standard algorithm name of the variant used in SSL v3 is "SSL3MAC-X", for a message digest name X.
References:
1. RFC 2104, HMAC: Keyed-Hashing for Message Authentication
2. RFC 2202, Test Cases for HMAC-MD5 and HMAC-SHA-1
Copyright © 1997 Systemics Ltd on behalf of the Cryptix Development Team.
All rights reserved.
$Revision: 1.4 $
Since:

Cryptix 3.0.3

Author:

David Hopwood

Constructor Summary

Constructors
Constructor and Description

HMAC(java.lang.String mdAlgorithm, int mdBlockSize)
Constructs an HMAC object for the given MD algorithm name and block size.

Constructors
Constructor and Description
`HMAC(java.lang.String mdAlgorithm, int mdBlockSize)` Constructs an HMAC object for the given MD algorithm name and block size.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`java.lang.Object`	`clone()` Returns a copy of this HMAC object.
`protected byte[]`	`engineDigest()` Calculates the final MAC.
`protected int`	`engineGetDigestLength()` SPI: Returns the digest length in bytes.
`protected java.lang.Object`	`engineGetParameter(java.lang.String param)`
`protected void`	`engineReset()` Resets this object disregarding any temporary data present at the time of the invocation of this call.
`protected void`	`engineSetParameter(java.lang.String param, java.lang.Object value)`
`protected void`	`engineUpdate(byte input)` Continues an HMAC digest using the input byte.
`protected void`	`engineUpdate(byte[] input, int offset, int len)` Hashes a byte array from a given offset for a specified length.
`java.lang.Object`	`getParameter(java.lang.String param)` Gets the value of the specified algorithm parameter.
`void`	`setParameter(java.lang.String param, java.lang.Object value)` Sets the specified algorithm parameter to the specified value.

Methods inherited from class java.security.MessageDigest
digest, digest, digest, getAlgorithm, getDigestLength, getInstance, getInstance, getInstance, getProvider, isEqual, reset, toString, update, update, update, update

Methods inherited from class java.security.MessageDigestSpi
engineDigest, engineUpdate

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - HMAC
```
public HMAC(java.lang.String mdAlgorithm,
            int mdBlockSize)
```
    Constructs an HMAC object for the given MD algorithm name and block size.
    Do not rely on being able to use this constructor to obtain a subclass of MessageDigest; when Cryptix is changed to use the Java 1.2 provider architecture, it will be a subclass of MessageDigestSpi instead.
    
    Parameters:
    
    mdAlgorithm - the standard JCA algorithm name of the message digest to be used.
    
    mdBlockSize - the internal block size of the digest algorithm.
- Method Detail
  - clone
```
public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException
```
    Returns a copy of this HMAC object.
    
    Overrides:
    
    clone in class java.security.MessageDigest
    
    Throws:
    
    java.lang.CloneNotSupportedException - if the underlying MessageDigest is not cloneable.
  - engineReset
```
protected void engineReset()
```
    Resets this object disregarding any temporary data present at the time of the invocation of this call.
    
    Specified by:
    
    engineReset in class java.security.MessageDigestSpi
  - engineUpdate
```
protected void engineUpdate(byte input)
```
    Continues an HMAC digest using the input byte.
    
    Specified by:
    
    engineUpdate in class java.security.MessageDigestSpi
  - engineUpdate
```
protected void engineUpdate(byte[] input,
                            int offset,
                            int len)
```
    Hashes a byte array from a given offset for a specified length.
    
    Specified by:
    
    engineUpdate in class java.security.MessageDigestSpi
    
    Parameters:
    
    input - byte array from which data is to be hashed.
    
    offset - start index of bytes to hash in input.
    
    len - number of bytes to hash.
  - engineDigest
```
protected byte[] engineDigest()
```
    Calculates the final MAC.
    RFC 2104 describes HMAC as follows:
    The definition of HMAC requires a cryptographic hash function, which we denote by H, and a secret key K. We assume H to be a cryptographic hash function where data is hashed by iterating a basic compression function on blocks of data. We denote by B the byte-length of such blocks (B=64 for all the above mentioned examples of hash functions), and by L the byte-length of hash outputs (L=16 for MD5, L=20 for SHA-1). The authentication key K can be of any length up to B, the block length of the hash function. Applications that use keys longer than B bytes will first hash the key using H and then use the resultant L byte string as the actual key to HMAC. In any case the minimal recommended length for K is L bytes (as the hash output length). See section 3 for more information on keys.
    We define two fixed and different strings ipad and opad as follows (the 'i' and 'o' are mnemonics for inner and outer):
    ipad = the byte 0x36 repeated B times
    opad = the byte 0x5C repeated B times.
    
    To compute HMAC over the data 'text' we perform
    H(K XOR opad, H(K XOR ipad, text))
    
    Namely,
    1. append zeros to the end of K to create a B byte string (e.g., if K is of length 20 bytes and B=64, then K will be appended with 44 zero bytes 0x00)
    2. XOR (bitwise exclusive-OR) the B byte string computed in step (1) with ipad
    3. append the stream of data 'text' to the B byte string resulting from step (2)
    4. apply H to the stream generated in step (3)
    5. XOR (bitwise exclusive-OR) the B byte string computed in step (1) with opad
    6. append the H result from step (4) to the B byte string resulting from step (5)
    7. apply H to the stream generated in step (6) and output the result
    Specified by:
    
    engineDigest in class java.security.MessageDigestSpi
  - engineGetDigestLength
```
protected int engineGetDigestLength()
```
    SPI: Returns the digest length in bytes.
    
    Overrides:
    
    engineGetDigestLength in class java.security.MessageDigestSpi
  - setParameter
```
public void setParameter(java.lang.String param,
                         java.lang.Object value)
                  throws java.security.InvalidParameterException
```
    Description copied from interface: Parameterized
    
    Sets the specified algorithm parameter to the specified value.
    This method supplies a general-purpose mechanism through which it is possible to set the various parameters of this object. A uniform algorithm-specific naming scheme for each parameter is desirable but left unspecified at this time.
    
    Specified by:
    
    setParameter in interface Parameterized
    
    Parameters:
    
    param - the string identifier of the parameter.
    
    value - the parameter value.
    
    Throws:
    
    java.security.InvalidParameterException - if the parameter exists but cannot be set (for example because the object is in the wrong state).
  - getParameter
```
public java.lang.Object getParameter(java.lang.String param)
                              throws java.security.InvalidParameterException
```
    Description copied from interface: Parameterized
    
    Gets the value of the specified algorithm parameter.
    This method supplies a general-purpose mechanism through which it is possible to get the various parameters of this object. A uniform algorithm-specific naming scheme for each parameter is desirable but left unspecified at this time.
    
    Specified by:
    
    getParameter in interface Parameterized
    
    Parameters:
    
    param - the string name of the parameter.
    
    Returns:
    
    the object that represents the parameter value.
    
    Throws:
    
    java.security.InvalidParameterException - if the parameter exists but cannot be read.
  - engineSetParameter
```
protected void engineSetParameter(java.lang.String param,
                                  java.lang.Object value)
                           throws java.security.InvalidParameterException
```
    Throws:
    
    java.security.InvalidParameterException
  - engineGetParameter
```
protected java.lang.Object engineGetParameter(java.lang.String param)
                                       throws java.security.InvalidParameterException
```
    Throws:
    
    java.security.InvalidParameterException

Class HMAC

Constructor Summary

Method Summary

Methods inherited from class java.security.MessageDigest

Methods inherited from class java.security.MessageDigestSpi

Methods inherited from class java.lang.Object

Constructor Detail

HMAC

Method Detail

clone

engineReset

engineUpdate

engineUpdate

engineDigest

engineGetDigestLength

setParameter

getParameter

engineSetParameter

engineGetParameter