iaik.security.md

Class SHAKE256

java.lang.Object

java.security.MessageDigestSpi

java.security.MessageDigest

iaik.security.md.SHAKE256

All Implemented Interfaces:

java.lang.Cloneable

public final class SHAKE256
extends java.security.MessageDigest

This class implements the SHA-3 Extendable Output Function (XOF) SHAKE256.

NIST (FIPS PUB 202) specifies the Secure Hash Algorithm-3 (SHA-3) family of message digest algorithms as supplement of the SHA-1 and SHA-2 message digest algorithm family. SHA-3 is based on the KECCAK message digest algorithm but is not fully identical to KECCAK because it adds a suffix to the message to ensure domain separation between the SHA-3 hash function and the newly specified SHA-3 Extendable-Output Function (XOF). The XOF allows the output to be extended to any desired length.

This class implements the SHAKE256 Extendable Output Function. The suffix "256" does not indicate the (arbitrary) output length of the XOF, it specifies its security strength. SHAKE256 provides less than 256 bits of security if the output length d is sufficiently small (see FIPS PUB 202). The collision resistance is min(d/2, 256), the preimage resistance is >=min(d, 256), and the 2nd preimage resistance is min(d,256). For example, if d = 224, then SHAKE256 provides min(224/2,128)=112 bits of collision resistance and min(224, 256) = 224 bits of preimage resistance (see FIPS PUB 202).
Although it is possible to use an XOF as a hash function for a fixed output length, XOFs have the potential for generating related outputs. When selecting two different output length values for a common message, the two outputs of the XOF will be closely related. The longer output will be an extension of the shorter output. For that reason XOFs should be used with special care. See (the Security section of) NIST FIPS PUB 202 for more information! Please be aware that SHAKE128 is approved as XOF, but NOT as hash function. Approved XOF use cases may be specified in further NIST Special Publications.

Currently the JCA API does not provide any engines for Extenable Output Functions. Because of their relation to hash functions and the membership of SHAKE256 to the SHA-3 family SHAKE256 is implemented as MessageDigest engine. By default it produces an output of 256 bit when calling a digest() method that returns the calculated digest value, e.g.:

 MessageDigest shake256 = MessageDigest.getInstance("SHAKE256");
 ...
 ((SHAKE256)shake256).setOutputLength(512);
 ...
 shake256.update(m1);
 shake256.update(m2);
 ...
 byte[] output = shake256.digest(); 
 

Note that "256" in name "SHAKE256" actually refers to the security strength, however, for convenience this MessageDigest implementation uses 256 as default digest output length, too.
To get a digest output of other than the default length an application shall create a byte array of the desired output length (e.g. 64 bytes) and specify this array when calling the final digest(byte[] buf, int offset, int len) method of the MessageDigest engine, e.g.:

 MessageDigest shake256 = MessageDigest.getInstance("SHAKE256");
 ...
 shake256.update(m1);
 shake256.update(m2);
 ...
 int digestLen = 64;
 byte[] output = new byte[digestLen]
 shake256.digest(output, 0, digestLen); 
 

Doing so the 64 byte digest value is written to the given output array.

Alternatively you may use the SHAKE256InputStream from which you can read any desired number of output bytes. However, note that whereas a SHAKE128 MessageDigest engine resets automatically after each call of method digest() a SHAKE128InputStream has to be reset by explicitly calling its reset() method (after having read the required number of digest bytes by one or more read() calls).

Constructor Summary

Constructors

Constructor and Description
SHAKE256() Default constructor.

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.Object	clone()
protected void	doPadding()
protected void	engineCompress(byte[] input, int offset)
protected byte[]	engineDigest()
protected void	engineDigest(byte[] output, int offset)
protected int	engineDigest(byte[] buf, int offset, int len) Calculates the digest value and writes it to the given output buffer.
protected int	engineGetDigestLength() Returns the default length of the digest in bytes.
protected void	engineReset()
protected void	engineUpdate(byte input)
protected void	engineUpdate(byte[] input, int offset, int len)

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

engineUpdate

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SHAKE256

public SHAKE256()

Default constructor.

Method Detail

engineGetDigestLength

protected int engineGetDigestLength()

Returns the default length of the digest in bytes.

Returns:

the default length of the digest in bytes.

engineCompress

protected void engineCompress(byte[] input,
                  int offset)

doPadding

protected void doPadding()

engineDigest

protected void engineDigest(byte[] output,
                int offset)

engineDigest

protected byte[] engineDigest()

Specified by:

engineDigest in class java.security.MessageDigestSpi

engineDigest

protected int engineDigest(byte[] buf,
               int offset,
               int len)
                    throws java.security.DigestException

Calculates the digest value and writes it to the given output buffer.

Overrides:

engineDigest in class java.security.MessageDigestSpi

Parameters:

buf - the output buffer in which to write the digest

offset - the start offset in the output buffer

len - the length of the digest value.

Returns:

the length of the digest written to the output buffer.

Throws:

java.security.DigestException - if an error occurs when calculating the digest value.

engineUpdate

protected void engineUpdate(byte input)

Specified by:

engineUpdate in class java.security.MessageDigestSpi

engineUpdate

protected void engineUpdate(byte[] input,
                int offset,
                int len)

Specified by:

engineUpdate in class java.security.MessageDigestSpi

engineReset

protected void engineReset()

Specified by:

engineReset in class java.security.MessageDigestSpi

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Overrides:

clone in class java.security.MessageDigest

Throws:

java.lang.CloneNotSupportedException