DigestService
Keywords: net.corda.core.crypto.DigestService class
Date: 2023-09-18

net.corda.core.crypto

## Class DigestService

- net.corda.core.crypto.DigestService

-     public class DigestService

  The DigestService class is a service that offers the main crypto methods for calculating transaction hashes and building Merkle trees. The `default` instance is passed by default to instances of classes like TransactionBuilder and as a parameter to MerkleTree.getMerkleTree(...) method. In future the `default` instance can be parametrized to initialize with the network default hash algorithm or just a more secure algorithm (e.g. SHA3_256). While the SHA2_256 is vulnerable to pre-image attacks, the computeNonce and componentHash methods behaviour is defined by the hashTwiceNonce and hashTwiceComponent; with SHA2_256 they both must be set to true to ensure pre-image attack won't work (and for backward compatibility), but for other algorithms like SHA3_256 that are not affected, they can and should be set to false as hashing twice would not improve security but affect performance.

  See Also:
    `default`, `default`

- - ### Field Detail

    - #### Companion

          public static net.corda.core.crypto.DigestService.Companion Companion

  - ### Constructor Detail

    - #### DigestService

          public DigestService(@NotNull
                               java.lang.String hashAlgorithm)

      The DigestService class is a service that offers the main crypto methods for calculating transaction hashes and building Merkle trees. The `default` instance is passed by default to instances of classes like TransactionBuilder and as a parameter to MerkleTree.getMerkleTree(...) method. In future the `default` instance can be parametrized to initialize with the network default hash algorithm or just a more secure algorithm (e.g. SHA3_256). While the SHA2_256 is vulnerable to pre-image attacks, the computeNonce and componentHash methods behaviour is defined by the hashTwiceNonce and hashTwiceComponent; with SHA2_256 they both must be set to true to ensure pre-image attack won't work (and for backward compatibility), but for other algorithms like SHA3_256 that are not affected, they can and should be set to false as hashing twice would not improve security but affect performance.

      Parameters:
        `hashAlgorithm` - the name of the hash algorithm to be used for the instance
      See Also:
        `default`, `default`

  - ### Method Detail

    - #### getDigestLength

          public int getDigestLength()

      Specifies the WORD size for the given hash algorithm.

    - #### hash

          @NotNull
          public SecureHash hash(@NotNull
                                          kotlin.Array[] bytes)

      Computes the digest of the ByteArray.

      Parameters:
        `bytes` - The ByteArray to hash.
      See Also:
        ByteArray

    - #### hash

          @NotNull
          public SecureHash hash(@NotNull
                                          java.lang.String str)

      Computes the digest of the String's UTF-8 byte contents.

      Parameters:
        `str` - String whose UTF-8 contents will be hashed.
      See Also:
        String

    - #### getAllOnesHash

          @NotNull
          public SecureHash getAllOnesHash()

      A digest value consisting of 0xFF bytes.

    - #### getZeroHash

          @NotNull
          public SecureHash getZeroHash()

      A hash value consisting of 0x00 bytes.

    - #### componentHash

          @NotNull
          public SecureHash componentHash(@NotNull
                                                   OpaqueBytes opaqueBytes,
                                                   @NotNull
                                                   PrivacySalt privacySalt,
                                                   int componentGroupIndex,
                                                   int internalIndex)

      Compute the hash of each serialised component so as to be used as Merkle tree leaf. The resultant output (leaf) is calculated using the service's hash algorithm, thus HASH(HASH(nonce || serializedComponent)) for SHA2-256 and other algorithms loaded via JCA MessageDigest, or DigestAlgorithm.componentDigest(nonce || serializedComponent) otherwise, where nonce is computed from `computeNonce`.

      See Also:
        MessageDigest, `computeNonce`

    - #### componentHash

          @NotNull
          public SecureHash componentHash(@NotNull
                                                   SecureHash nonce,
                                                   @NotNull
                                                   OpaqueBytes opaqueBytes)

      Return the HASH(HASH(nonce || serializedComponent)) for SHA2-256 and other algorithms loaded via JCA MessageDigest, otherwise it's defined by DigestAlgorithm.componentDigest(nonce || serializedComponent).

      See Also:
        MessageDigest

    - #### serializedHash

          @NotNull
          public <T> SecureHash serializedHash(@NotNull
                                                        T x)

      Serialise the object and return the hash of the serialized bytes. Note that the resulting hash may not be deterministic across platform versions: serialization can produce different values if any of the types being serialized have changed, or if the version of serialization specified by the context changes.

    - #### computeNonce

          @NotNull
          public SecureHash computeNonce(@NotNull
                                                  PrivacySalt privacySalt,
                                                  int groupIndex,
                                                  int internalIndex)

      Method to compute a nonce based on privacySalt, component group index and component internal index. SHA256d (double SHA256) is used to prevent length extension attacks.

      Parameters:
        `privacySalt` - a `class PrivacySalt`.
        `groupIndex` - the fixed index (ordinal) of this component group.
        `internalIndex` - the internal index of this object in its corresponding components list.
      Returns:
        HASH(HASH(privacySalt || groupIndex || internalIndex)) for SHA2-256 and other algorithms loaded via JCA MessageDigest, otherwise it's defined by DigestAlgorithm.nonceDigest(privacySalt || groupIndex || internalIndex).

    - #### getHashAlgorithm

          @NotNull
          public java.lang.String getHashAlgorithm()

      the name of the hash algorithm to be used for the instance

    - #### component1

          @NotNull
          public java.lang.String component1()

      the name of the hash algorithm to be used for the instance

    - #### copy

          @NotNull
          public DigestService copy(@NotNull
                                             java.lang.String hashAlgorithm)

      The DigestService class is a service that offers the main crypto methods for calculating transaction hashes and building Merkle trees. The `default` instance is passed by default to instances of classes like TransactionBuilder and as a parameter to MerkleTree.getMerkleTree(...) method. In future the `default` instance can be parametrized to initialize with the network default hash algorithm or just a more secure algorithm (e.g. SHA3_256). While the SHA2_256 is vulnerable to pre-image attacks, the computeNonce and componentHash methods behaviour is defined by the hashTwiceNonce and hashTwiceComponent; with SHA2_256 they both must be set to true to ensure pre-image attack won't work (and for backward compatibility), but for other algorithms like SHA3_256 that are not affected, they can and should be set to false as hashing twice would not improve security but affect performance.

      Parameters:
        `hashAlgorithm` - the name of the hash algorithm to be used for the instance
      See Also:
        `default`, `default`

    - #### toString

          @NotNull
          public java.lang.String toString()

      The DigestService class is a service that offers the main crypto methods for calculating transaction hashes and building Merkle trees. The `default` instance is passed by default to instances of classes like TransactionBuilder and as a parameter to MerkleTree.getMerkleTree(...) method. In future the `default` instance can be parametrized to initialize with the network default hash algorithm or just a more secure algorithm (e.g. SHA3_256). While the SHA2_256 is vulnerable to pre-image attacks, the computeNonce and componentHash methods behaviour is defined by the hashTwiceNonce and hashTwiceComponent; with SHA2_256 they both must be set to true to ensure pre-image attack won't work (and for backward compatibility), but for other algorithms like SHA3_256 that are not affected, they can and should be set to false as hashing twice would not improve security but affect performance.

      See Also:
        `default`, `default`

    - #### hashCode

          public int hashCode()

      The DigestService class is a service that offers the main crypto methods for calculating transaction hashes and building Merkle trees. The `default` instance is passed by default to instances of classes like TransactionBuilder and as a parameter to MerkleTree.getMerkleTree(...) method. In future the `default` instance can be parametrized to initialize with the network default hash algorithm or just a more secure algorithm (e.g. SHA3_256). While the SHA2_256 is vulnerable to pre-image attacks, the computeNonce and componentHash methods behaviour is defined by the hashTwiceNonce and hashTwiceComponent; with SHA2_256 they both must be set to true to ensure pre-image attack won't work (and for backward compatibility), but for other algorithms like SHA3_256 that are not affected, they can and should be set to false as hashing twice would not improve security but affect performance.

      See Also:
        `default`, `default`

    - #### equals

          public boolean equals(@Nullable
                                java.lang.Object p)

      The DigestService class is a service that offers the main crypto methods for calculating transaction hashes and building Merkle trees. The `default` instance is passed by default to instances of classes like TransactionBuilder and as a parameter to MerkleTree.getMerkleTree(...) method. In future the `default` instance can be parametrized to initialize with the network default hash algorithm or just a more secure algorithm (e.g. SHA3_256). While the SHA2_256 is vulnerable to pre-image attacks, the computeNonce and componentHash methods behaviour is defined by the hashTwiceNonce and hashTwiceComponent; with SHA2_256 they both must be set to true to ensure pre-image attack won't work (and for backward compatibility), but for other algorithms like SHA3_256 that are not affected, they can and should be set to false as hashing twice would not improve security but affect performance.

      See Also:
        `default`, `default`