net.i2p.crypto

## Class DHSessionKeyBuilder

- java.lang.Object
- - net.i2p.crypto.DHSessionKeyBuilder

-     public class DHSessionKeyBuilder
      extends Object

  Generate a new session key through a diffie hellman exchange. This uses the constants defined in CryptoConstants, which causes the exchange to create a 256 bit session key. This class precalcs a set of values on its own thread, using those transparently when a new instance is created. By default, the minimum threshold for creating new values for the pool is 5, and the max pool size is 10. Whenever the pool has less than the minimum, it fills it up again to the max. There is a delay after each precalculation so that the CPU isn't hosed during startup (defaulting to 1 second). These three parameters are controlled by java environmental variables and can be adjusted via: -Dcrypto.dh.precalc.min=40 -Dcrypto.dh.precalc.max=100 -Dcrypto.dh.precalc.delay=60000 (delay is milliseconds) To disable precalculation, set min to 0
  Author:
    jrandom

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `DHSessionKeyBuilder.InvalidPublicParameterException`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DEFAULT_DH_PRECALC_DELAY`
    `static int` | `DEFAULT_DH_PRECALC_MAX`
    `static int` | `DEFAULT_DH_PRECALC_MIN`
    `static String` | `PROP_DH_PRECALC_DELAY`
    `static String` | `PROP_DH_PRECALC_MAX`
    `static String` | `PROP_DH_PRECALC_MIN`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DHSessionKeyBuilder()` Construct a new DH key builder or pulls a prebuilt one from the queue.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static DHSessionKeyBuilder` | `exchangeKeys(InputStream in, OutputStream out)` Conduct a DH exchange over the streams, returning the resulting data.
    `BigInteger` | `generateMyValue()` Create a new private value for the DH exchange, and return the number to be exchanged, leaving the actual private value accessible through getMyPrivateValue()
    `ByteArray` | `getExtraBytes()` Retrieve the extra bytes beyond the session key resulting from the DH exchange.
    `BigInteger` | `getMyPrivateValue()` Retrieve the private value used by the local participant in the DH exchange
    `BigInteger` | `getMyPublicValue()` Retrieve the public value used by the local participant in the DH exchange, generating it if necessary
    `byte[]` | `getMyPublicValueBytes()` Return a 256 byte representation of our public key, with leading 0s if necessary.
    `BigInteger` | `getPeerPublicValue()`
    `byte[]` | `getPeerPublicValueBytes()`
    `SessionKey` | `getSessionKey()` Retrieve the session key, calculating it if necessary (and if possible).
    `(package private) static BigInteger` | `readBigI(InputStream in)`
    `void` | `setPeerPublicValue(BigInteger peerVal)` Specify the value given by the peer for use in the session key negotiation
    `void` | `setPeerPublicValue(byte[] val)`
    `(package private) static void` | `writeBigI(OutputStream out, BigInteger val)` Write out the integer as a 256 byte value.

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

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

- - ### Field Detail

    - #### PROP_DH_PRECALC_MIN

          public static final String PROP_DH_PRECALC_MIN

      See Also:
        Constant Field Values

    - #### PROP_DH_PRECALC_MAX

          public static final String PROP_DH_PRECALC_MAX

      See Also:
        Constant Field Values

    - #### PROP_DH_PRECALC_DELAY

          public static final String PROP_DH_PRECALC_DELAY

      See Also:
        Constant Field Values

    - #### DEFAULT_DH_PRECALC_MIN

          public static final int DEFAULT_DH_PRECALC_MIN

      See Also:
        Constant Field Values

    - #### DEFAULT_DH_PRECALC_MAX

          public static final int DEFAULT_DH_PRECALC_MAX

      See Also:
        Constant Field Values

    - #### DEFAULT_DH_PRECALC_DELAY

          public static final int DEFAULT_DH_PRECALC_DELAY

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### DHSessionKeyBuilder

          public DHSessionKeyBuilder()

      Construct a new DH key builder or pulls a prebuilt one from the queue.

  - ### Method Detail

    - #### exchangeKeys

          public static DHSessionKeyBuilder exchangeKeys(InputStream in,
                                         OutputStream out)
                                                  throws IOException

      Conduct a DH exchange over the streams, returning the resulting data.
      Returns:
        exchanged data
      Throws:
        `IOException` - if there is an error (but does not close the streams

    - #### readBigI

          static BigInteger readBigI(InputStream in)
                              throws IOException

      Throws:
        `IOException`

    - #### writeBigI

          static void writeBigI(OutputStream out,
                       BigInteger val)
                         throws IOException

      Write out the integer as a 256 byte value. This left pads with 0s so to keep in 2s complement, and if it is already 257 bytes (due to the sign bit) ignore that first byte.
      Throws:
        `IOException`

    - #### generateMyValue

          public BigInteger generateMyValue()

      Create a new private value for the DH exchange, and return the number to be exchanged, leaving the actual private value accessible through getMyPrivateValue()

    - #### getMyPrivateValue

          public BigInteger getMyPrivateValue()

      Retrieve the private value used by the local participant in the DH exchange

    - #### getMyPublicValue

          public BigInteger getMyPublicValue()

      Retrieve the public value used by the local participant in the DH exchange, generating it if necessary

    - #### getMyPublicValueBytes

          public byte[] getMyPublicValueBytes()

      Return a 256 byte representation of our public key, with leading 0s if necessary.

    - #### setPeerPublicValue

          public void setPeerPublicValue(BigInteger peerVal)
                                  throws DHSessionKeyBuilder.InvalidPublicParameterException

      Specify the value given by the peer for use in the session key negotiation
      Throws:
        `DHSessionKeyBuilder.InvalidPublicParameterException`

    - #### setPeerPublicValue

          public void setPeerPublicValue(byte[] val)
                                  throws DHSessionKeyBuilder.InvalidPublicParameterException

      Throws:
        `DHSessionKeyBuilder.InvalidPublicParameterException`

    - #### getPeerPublicValue

          public BigInteger getPeerPublicValue()

    - #### getPeerPublicValueBytes

          public byte[] getPeerPublicValueBytes()

    - #### getSessionKey

          public SessionKey getSessionKey()

      Retrieve the session key, calculating it if necessary (and if possible).
      Returns:
        session key exchanged, or null if the exchange is not complete

    - #### getExtraBytes

          public ByteArray getExtraBytes()

      Retrieve the extra bytes beyond the session key resulting from the DH exchange. If there aren't enough bytes (with all of them being consumed by the 32 byte key), the SHA256 of the key itself is used.
      Returns:
        non-null (but rv.getData() may be null)