Poly1305KeyGenerator (Bouncy Castle Library 1.54 API Specification)
Date: 2015-12-29

org.bouncycastle.crypto.generators

## Class Poly1305KeyGenerator

- java.lang.Object
- - org.bouncycastle.crypto.CipherKeyGenerator
  - - org.bouncycastle.crypto.generators.Poly1305KeyGenerator

-     public class Poly1305KeyGenerator
      extends CipherKeyGenerator

  Generates keys for the Poly1305 MAC.

  Poly1305 keys are 256 bit keys consisting of a 128 bit secret key used for the underlying block cipher followed by a 128 bit `r` value used for the polynomial portion of the Mac.
  The `r` value has a specific format with some bits required to be cleared, resulting in an effective 106 bit key.
  A separately generated 256 bit key can be modified to fit the Poly1305 key format by using the `clamp(byte[])` method to clear the required bits.

  See Also:
    `Poly1305`

- - ### Field Summary

    - ### Fields inherited from class org.bouncycastle.crypto.CipherKeyGenerator

      `random, strength`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Poly1305KeyGenerator()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `checkKey(byte[] key)` Checks a 32 byte key for compliance with the Poly1305 key requirements, e.g.
    `static void` | `clamp(byte[] key)` Modifies an existing 32 byte key value to comply with the requirements of the Poly1305 key by clearing required bits in the `r` (second 16 bytes) portion of the key.
    `byte[]` | `generateKey()` Generates a 256 bit key in the format required for Poly1305 - e.g.
    `void` | `init(KeyGenerationParameters param)` Initialises the key generator.

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

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

- - ### Constructor Detail

    - #### Poly1305KeyGenerator

          public Poly1305KeyGenerator()

  - ### Method Detail

    - #### init

          public void init(KeyGenerationParameters param)

      Initialises the key generator.
      Poly1305 keys are always 256 bits, so the key length in the provided parameters is ignored.
      Overrides:
        `init` in class `CipherKeyGenerator`
      Parameters:
        `param` - the parameters to be used for key generation

    - #### generateKey

          public byte[] generateKey()

      Generates a 256 bit key in the format required for Poly1305 - e.g. `k[0] ... k[15], r[0] ... r[15]` with the required bits in `r` cleared as per `clamp(byte[])`.
      Overrides:
        `generateKey` in class `CipherKeyGenerator`
      Returns:
        a byte array containing the key value.

    - #### clamp

          public static void clamp(byte[] key)

      Modifies an existing 32 byte key value to comply with the requirements of the Poly1305 key by clearing required bits in the `r` (second 16 bytes) portion of the key.
      Specifically:
      - r[3], r[7], r[11], r[15] have top four bits clear (i.e., are {0, 1, . . . , 15})
      - r[4], r[8], r[12] have bottom two bits clear (i.e., are in {0, 4, 8, . . . , 252})
      Parameters:
        `key` - a 32 byte key value `k[0] ... k[15], r[0] ... r[15]`

    - #### checkKey

          public static void checkKey(byte[] key)

      Checks a 32 byte key for compliance with the Poly1305 key requirements, e.g. `k[0] ... k[15], r[0] ... r[15]` with the required bits in `r` cleared as per `clamp(byte[])`.
      Throws:
        `java.lang.IllegalArgumentException` - if the key is of the wrong length, or has invalid bits set in the `r` portion of the key.