DigestService - corda

corda / net.corda.core.crypto / DigestService

# DigestService

`data 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.

### Parameters

`hashAlgorithm` - the name of the hash algorithm to be used for the instance

### Constructors

#### <init> | 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. `DigestService(hashAlgorithm: String)`

### Properties

#### allOnesHash | A digest value consisting of 0xFF bytes. `val allOnesHash: SecureHash`
#### digestLength | Specifies the WORD size for the given hash algorithm. `val digestLength: Int`
#### hashAlgorithm | the name of the hash algorithm to be used for the instance `val hashAlgorithm: String`
#### zeroHash | A hash value consisting of 0x00 bytes. `val zeroHash: SecureHash`

### Functions

#### componentHash | 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. `fun componentHash(opaqueBytes: OpaqueBytes, privacySalt: PrivacySalt, componentGroupIndex: Int, internalIndex: Int): SecureHash` 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). `fun componentHash(nonce: SecureHash, opaqueBytes: OpaqueBytes): SecureHash`
#### computeNonce | 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. `fun computeNonce(privacySalt: PrivacySalt, groupIndex: Int, internalIndex: Int): SecureHash`
#### hash | Computes the digest of the ByteArray. `fun hash(bytes: ByteArray): SecureHash` Computes the digest of the String's UTF-8 byte contents. `fun hash(str: String): SecureHash`
#### serializedHash | 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. `fun <T : Any> serializedHash(x: T): SecureHash`

### Companion Object Properties

#### default | The default instance will be parametrized and initialized at runtime. It would be probably useful to assume an override priority order. `val default: DigestService`
#### sha2_256 | `val sha2_256: DigestService`
#### sha2_384 | `val sha2_384: DigestService`
#### sha2_512 | `val sha2_512: DigestService`

### Extension Functions

#### randomHash | `fun DigestService.randomHash(): SecureHash`