org.bouncycastle.crypto.macs

## Class KMAC

- java.lang.Object
- - org.bouncycastle.crypto.macs.KMAC

- All Implemented Interfaces:
    Digest, EncodableDigest, EncodableService, ExtendedDigest, Mac, Xof, Memoable

      public class KMAC
      extends java.lang.Object
      implements Mac, Xof, Memoable, EncodableDigest

  KMAC - MAC with optional XOF mode.

  From NIST Special Publication 800-185 - SHA-3 Derived Functions:cSHAKE, KMAC, TupleHash and ParallelHash

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `KMAC(byte[] state)`
    `KMAC(int bitLength, byte[] S)` Base constructor.
    `KMAC(KMAC original)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Memoable` | `copy()` Produce a copy of this object with its configuration and in its current state.
    `int` | `doFinal(byte[] out, int outOff)` Compute the final stage of the MAC writing the output to the out parameter.
    `int` | `doFinal(byte[] out, int outOff, int outLen)` Output the results of the final calculation for this digest to outLen number of bytes.
    `int` | `doOutput(byte[] out, int outOff, int outLen)` Start outputting the results of the final calculation for this digest.
    `java.lang.String` | `getAlgorithmName()` Return the name of the algorithm the MAC implements.
    `int` | `getByteLength()` Return the size in bytes of the internal buffer the digest applies it's compression function to.
    `int` | `getDigestSize()` return the size, in bytes, of the digest produced by this message digest.
    `byte[]` | `getEncodedState()` Return an encoded byte array for the digest's internal state
    `int` | `getMacSize()` Return the block size for this MAC (in bytes).
    `void` | `init(CipherParameters params)` Initialise the MAC.
    `void` | `reset()` Reset the MAC.
    `void` | `reset(Memoable other)` Restore a copied object state into this object.
    `void` | `update(byte in)` add a single byte to the mac for processing.
    `void` | `update(byte[] in, int inOff, int len)` update the message digest with a block of bytes.

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

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

- - ### Constructor Detail

    - #### KMAC

          public KMAC(int bitLength,
                      byte[] S)

      Base constructor.
      Parameters:
        `bitLength` - bit length of the underlying SHAKE function, 128 or 256.
        `S` - the customization string - available for local use.

    - #### KMAC

          public KMAC(KMAC original)

    - #### KMAC

          public KMAC(byte[] state)

  - ### Method Detail

    - #### init

          public void init(CipherParameters params)
                    throws java.lang.IllegalArgumentException

      Description copied from interface: `Mac`
      Initialise the MAC.
      Specified by:
        `init` in interface `Mac`
      Parameters:
        `params` - the key and other data required by the MAC.
      Throws:
        `java.lang.IllegalArgumentException` - if the params argument is inappropriate.

    - #### getAlgorithmName

          public java.lang.String getAlgorithmName()

      Description copied from interface: `Mac`
      Return the name of the algorithm the MAC implements.
      Specified by:
        `getAlgorithmName` in interface `Digest`
      Specified by:
        `getAlgorithmName` in interface `Mac`
      Returns:
        the name of the algorithm the MAC implements.

    - #### getByteLength

          public int getByteLength()

      Description copied from interface: `ExtendedDigest`
      Return the size in bytes of the internal buffer the digest applies it's compression function to.
      Specified by:
        `getByteLength` in interface `ExtendedDigest`
      Returns:
        byte length of the digests internal buffer.

    - #### getMacSize

          public int getMacSize()

      Description copied from interface: `Mac`
      Return the block size for this MAC (in bytes).
      Specified by:
        `getMacSize` in interface `Mac`
      Returns:
        the block size for this MAC in bytes.

    - #### getDigestSize

          public int getDigestSize()

      Description copied from interface: `Digest`
      return the size, in bytes, of the digest produced by this message digest.
      Specified by:
        `getDigestSize` in interface `Digest`
      Returns:
        the size, in bytes, of the digest produced by this message digest.

    - #### update

          public void update(byte in)
                      throws java.lang.IllegalStateException

      Description copied from interface: `Mac`
      add a single byte to the mac for processing.
      Specified by:
        `update` in interface `Digest`
      Specified by:
        `update` in interface `Mac`
      Parameters:
        `in` - the byte to be processed.
      Throws:
        `java.lang.IllegalStateException` - if the MAC is not initialised.

    - #### update

          public void update(byte[] in,
                             int inOff,
                             int len)
                      throws DataLengthException,
                             java.lang.IllegalStateException

      Description copied from interface: `Digest`
      update the message digest with a block of bytes.
      Specified by:
        `update` in interface `Digest`
      Specified by:
        `update` in interface `Mac`
      Parameters:
        `in` - the array containing the input.
        `inOff` - the index in the array the data begins at.
        `len` - the length of the input starting at inOff.
      Throws:
        `DataLengthException` - if there isn't enough data in in.
        `java.lang.IllegalStateException` - if the MAC is not initialised.

    - #### doFinal

          public int doFinal(byte[] out,
                             int outOff)
                      throws DataLengthException,
                             java.lang.IllegalStateException

      Description copied from interface: `Mac`
      Compute the final stage of the MAC writing the output to the out parameter.

      doFinal leaves the MAC in the same state it was after the last init.

      Specified by:
        `doFinal` in interface `Digest`
      Specified by:
        `doFinal` in interface `Mac`
      Parameters:
        `out` - the array the MAC is to be output to.
        `outOff` - the offset into the out buffer the output is to start at.
      Throws:
        `DataLengthException` - if there isn't enough space in out.
        `java.lang.IllegalStateException` - if the MAC is not initialised.

    - #### doFinal

          public int doFinal(byte[] out,
                             int outOff,
                             int outLen)

      Description copied from interface: `Xof`
      Output the results of the final calculation for this digest to outLen number of bytes.
      Specified by:
        `doFinal` in interface `Xof`
      Parameters:
        `out` - output array to write the output bytes to.
        `outOff` - offset to start writing the bytes at.
        `outLen` - the number of output bytes requested.
      Returns:
        the number of bytes written

    - #### doOutput

          public int doOutput(byte[] out,
                              int outOff,
                              int outLen)

      Description copied from interface: `Xof`
      Start outputting the results of the final calculation for this digest. Unlike doFinal, this method will continue producing output until the Xof is explicitly reset, or signals otherwise.
      Specified by:
        `doOutput` in interface `Xof`
      Parameters:
        `out` - output array to write the output bytes to.
        `outOff` - offset to start writing the bytes at.
        `outLen` - the number of output bytes requested.
      Returns:
        the number of bytes written

    - #### reset

          public void reset()

      Description copied from interface: `Mac`
      Reset the MAC. At the end of resetting the MAC should be in the in the same state it was after the last init (if there was one).
      Specified by:
        `reset` in interface `Digest`
      Specified by:
        `reset` in interface `Mac`

    - #### getEncodedState

          public byte[] getEncodedState()

      Description copied from interface: `EncodableDigest`
      Return an encoded byte array for the digest's internal state
      Specified by:
        `getEncodedState` in interface `EncodableDigest`
      Specified by:
        `getEncodedState` in interface `EncodableService`
      Returns:
        an encoding of the digests internal state.

    - #### copy

          public Memoable copy()

      Description copied from interface: `Memoable`
      Produce a copy of this object with its configuration and in its current state.

      The returned object may be used simply to store the state, or may be used as a similar object starting from the copied state.

      Specified by:
        `copy` in interface `Memoable`

    - #### reset

          public void reset(Memoable other)

      Description copied from interface: `Memoable`
      Restore a copied object state into this object.

      Implementations of this method should try to avoid or minimise memory allocation to perform the reset.

      Specified by:
        `reset` in interface `Memoable`
      Parameters:
        `other` - an object originally `copied` from an object of the same type as this instance.