net.i2p.data

## Class Hash

- java.lang.Object
- - net.i2p.data.SimpleDataStructure
  - - net.i2p.data.Hash

- All Implemented Interfaces:
    DataStructure
  Direct Known Subclasses:
    LocalHash, Peer

      public class Hash
      extends SimpleDataStructure

  SHA-256 hash implementation for I2P data identification and integrity.

  Hash provides cryptographic hash functionality throughout I2P:

  - Algorithm: SHA-256 cryptographic hash function
  - Fixed Size: Always 32 bytes (256 bits)
  - Uniqueness: Extremely low collision probability
  - Standardized: Consistent hash across all I2P components

  Key Uses:

  - Identification: Unique identifiers for destinations and routers
  - Integrity: Verify data hasn't been modified or corrupted
  - Indexing: Fast lookup keys in network database (NetDb)
  - Routing: Keys for distributed hash table (DHT) operations
  - Caching: Efficient storage and retrieval of frequently used hashes

  Performance Features:

  - LRU Caching: Least-recently-used cache with size limits
  - Factory Methods: Static creation methods for cache efficiency
  - Efficient Comparison: Optimized equals() and hashCode() methods
  - Base32 Conversion: Cached .b32.i2p address generation
  - Memory Management: Automatic cache size adjustment

  Security Properties:

  - Cryptographic Strength: SHA-256 provides 128-bit security against collisions
  - Preimage Resistance: Computationally infeasible to reverse
  - Second Preimage: Computationally infeasible to find similar inputs
  - Collision Resistance: Practically impossible to find colliding inputs

  Common Operations:

  - Data Hashing: Calculate hash of any byte array or data structure
  - Stream Hashing: Incremental hashing of large data streams
  - File Verification: Verify file integrity using hash comparison
  - Address Generation: Convert to Base32 for .b32.i2p addresses

  Constants:

  - `HASH_LENGTH` - Standard 32-byte hash size
  - `FAKE_HASH` - All-zero hash for testing/placeholder use

  Thread Safety:

  - Immutable Data: Hash data cannot be modified after creation
  - Thread-Safe Cache: Static factory methods are thread-safe
  - Safe Sharing: Instances can be safely shared between threads

  Best Practices:

  - Factory Methods: Use static create() methods for cache efficiency
  - Hash Verification: Always verify critical data hashes
  - Constant Time: Use hash comparison for data integrity checks
  - Memory Efficiency: Reuse hash instances when possible

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Hash` | `FAKE_HASH`
    `static int` | `HASH_LENGTH`

    - ### Fields inherited from class net.i2p.data.SimpleDataStructure

      `_data`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Hash()`
    `Hash(byte[] data)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `clearCache()` Clear the hash cache.
    `static Hash` | `create(byte[] data)` Pull from cache or return new WARNING - If the SDS is found in the cache, the passed-in byte array will be returned to the SimpleByteCache for reuse.
    `static Hash` | `create(byte[] data, int off)` Pull from cache or return new
    `static Hash` | `create(InputStream in)` Pull from cache or return new
    `int` | `hashCode()` a Hash is a hash, so just use the first 4 bytes for speed
    `int` | `length()` The legal length of the byte array in this data structure
    `void` | `readBytes(InputStream in)` Sets the data.
    `void` | `setData(byte[] data)` Sets the data.
    `String` | `toBase32()` For convenience.
    `String` | `toBase64()` render the structure into modified base 64 notation

    - ### Methods inherited from class net.i2p.data.SimpleDataStructure

      `calculateHash, equals, fromBase64, fromByteArray, getData, read, toByteArray, toString, writeBytes`

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

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### FAKE_HASH

          public static final Hash FAKE_HASH

    - #### HASH_LENGTH

          public static final int HASH_LENGTH

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Hash

          public Hash()

    - #### Hash

          public Hash(byte[] data)

      Throws:
        `IllegalArgumentException` - if data is not 32 bytes (null is ok)

  - ### Method Detail

    - #### clearCache

          public static void clearCache()

      Clear the hash cache.

    - #### create

          public static Hash create(byte[] data)

      Pull from cache or return new WARNING - If the SDS is found in the cache, the passed-in byte array will be returned to the SimpleByteCache for reuse. Do NOT save a reference to the passed-in data, or use or modify it, after this call. Ignore this warning and you WILL corrupt the cache or other data structures.
      Throws:
        `IllegalArgumentException` - if data is not the correct number of bytes

    - #### create

          public static Hash create(byte[] data,
                                    int off)

      Pull from cache or return new
      Throws:
        `ArrayIndexOutOfBoundsException` - if not enough bytes

    - #### create

          public static Hash create(InputStream in)
                             throws IOException

      Pull from cache or return new
      Throws:
        `IOException`

    - #### hashCode

          public int hashCode()

      a Hash is a hash, so just use the first 4 bytes for speed
      Overrides:
        `hashCode` in class `SimpleDataStructure`

    - #### length

          public int length()

      Description copied from class: `SimpleDataStructure`
      The legal length of the byte array in this data structure
      Specified by:
        `length` in class `SimpleDataStructure`

    - #### readBytes

          public void readBytes(InputStream in)
                         throws DataFormatException,
                                IOException

      Description copied from class: `SimpleDataStructure`
      Sets the data.
      Specified by:
        `readBytes` in interface `DataStructure`
      Overrides:
        `readBytes` in class `SimpleDataStructure`
      Parameters:
        `in` - the stream to read
      Throws:
        `DataFormatException` - if the data is improperly formatted
        `IOException` - if there was a problem reading the stream

    - #### setData

          public void setData(byte[] data)

      Description copied from class: `SimpleDataStructure`
      Sets the data.
      Overrides:
        `setData` in class `SimpleDataStructure`
      Parameters:
        `data` - of correct length, or null
      Throws:
        `IllegalArgumentException` - if data is not 32 bytes (null is ok)

    - #### toBase32

          public String toBase32()

      For convenience.
      Returns:
        "{52 chars}.b32.i2p" or null if data not set.

    - #### toBase64

          public String toBase64()

      Description copied from interface: `DataStructure`
      render the structure into modified base 64 notation
      Specified by:
        `toBase64` in interface `DataStructure`
      Overrides:
        `toBase64` in class `SimpleDataStructure`
      Returns:
        null on error