SHA3 extended function variable output.

[05nelsonm]

According to NIST.SP.800-185 , the extended functions should all have L (desired number of bits to output) as an input to produce variable length output when digest (or doFinal for Macs) is called. It specifies L as an input parameter for producing L / 8 bytes of output. The derived functions KMAC, TupleHash and ParallelHash are to rightEncode this value and then apply it before producing output. When the functions are being utilized as XOFs, this value will be 0 to indicate an arbitrary length.

After looking around at some different implementations (go, rust), I only see the option to utilize SHAKE, CSHAKE and functions derived from CSHAKE, as having the ability to be used as XOFs and skipping the customization of L all together.

As the publication specifies L as a function input, I believe the best course of action is to add the customization via an additional constructor which can be utilized when the default digest length is not wanted.

public class CSHAKE128: SHAKEDigest {
    public constructor(
        N: ByteArray?,
        S: ByteArray?,
        outputByteLength: Int,
        // ...
    )
}

I see in BouncyCastle that they simply have on their Xof interface the doFinal and doOutput functions which provides this functionality, but holy shit does it wreak havoc on the implementations. I am very happy that I went with the XofDelegate route for a clean separation of concerns.

[05nelsonm]

Also, L can be 0 which would return an empty ByteArray. Digest would need an update b/c currently passing digestLength of 0 throws an exception. Digest should only throw exception if it's less than 0.

[05nelsonm]

Also, L can be 0 which would return an empty ByteArray. Digest would need an update b/c currently passing digestLength of 0 throws an exception. Digest should only throw exception if it's less than 0.

See KotlinCrypto/core#30 (comment)