KMAC submission

[hoxxep]

I have tried to follow the RustCrypto MACs workflow, and used the traits as best I can.

This implements KMAC128, KMAC256, KMACXOF128, and KMACXOF256.

Key deviations from the existing mac traits:

• Mac::finalize() outputs a 32-bit digest for KMAC128, and 64-bit for KMAC256 following the NIST default MAC output length guidance in section 8.4.
• Kmac*::finalize_into_buf(out: &mut [u8]) is a generic finalize method for any fixed output size, following section 4.3 of NIST SP 800-185. I wasn't aware of a suitable trait to express this.
  • There is FixedOutput::finalize_into, but it's limited to the Mac-defined output size Output<Self>. This implementation allows for runtime determined output sizes.
• ExtendableOutput::finalize_xof() is used to implement KMACXOF128 and KMACXOF256. We could add an ExtendableMac trait to incorporate ExtendableOutput?
• Kmac*::new_customization(secret: &[u8], customization: &[u8]) is used to initialize with a customization string, and again I wasn't aware of any suitable existing trait to express this.

I'd be happy to try to add traits for this, if you believe this is the right direction? The crate should already be useful in it's current form though, and we could add traits later.

An alternate design could separate Kmac128, Kmac256, KmacXof128, and KmacXof256 types. This PR combines the fixed and XOF outputs into the same type, with different finalization methods for each output.

Happy to hear any feedback!

Related issues:

• kmac: Towards an implementation #133
• Missing MACs #1

[tarcieri]

Sorry we haven't taken a look at this yet. We're trying to wrap up our next stable release series and will have time after that

[hoxxep]

No worries at all, thank you Tony!

[hoxxep]

@newpavlov Thank you for the review, the implementation is significantly cleaner with a trait-based Rate approach. Your other comments should hopefully be addressed too?

I've had to add the kmac/tests/nist.rs to the spellcheck exclude list, because it was flagging "BA" in the nist hex as a spelling error and I want to keep the nist hex as close to the original PDF as possible. If there's a better way to exclude the nist hex entries let me know.

[newpavlov]

We could use this instead:

use digest::array::typenum::Diff;
use core::ops::Sub;

impl<Rate: BlockSizes> OutputSizeUser for Kmac<Rate>
where
    U200: Sub<Rate>,
    Diff<U200, Rate>: ArraySize,
{
    type OutputSize = Diff<U200, Rate>;
}

It would be more "generic" and allow to remove the sealed trait, but with a bit more annoying trait bounds, so I am not sure whether it's worth the trouble.

[newpavlov]

Unfortunately, the Rust compiler is not "smart" enough for Rate: IsLess<U200, Output = True> to be sufficient.

[hoxxep]

Edit: the new code now opts for the following, as I believe this is the most straightforward way to link the const-generics to OutputSize and KeySize.

pub struct Kmac<const RATE: usize> {
    cshake: CShake<RATE>,
}

pub type Kmac128 = Kmac<168>;
pub type Kmac256 = Kmac<136>;

impl OutputSizeUser for Kmac128 {
    type OutputSize = U32;
}

impl OutputSizeUser for Kmac256 {
    type OutputSize = U64;
}

impl KeySizeUser for Kmac128 {
    type KeySize = U168;
}

impl KeySizeUser for Kmac256 {
    type KeySize = U136;
}

[hoxxep]

@newpavlov I've ported kmac to the latest cshake const-generic based API, thanks!

[hoxxep]

I've updated this PR to match the latest master and now:

• matches the latest cshake const generic struct Kmac<const RATE: usize> { cshake: CShake<RATE> } design for consistency
• uses a published version of cshake instead of a git dependency
• uses default-features=false on cshake to avoid bringing in alloc
• adds a zeroize feature
• adds Debug and AlgorithmName impls
• adds changelog and license files
• new_customization now returns Self instead of an infallible result, this can presumably be adjusted with a major version bump down the road if other RustCrypto traits can support (key, customisation) initialisers.
• removes the hex dev dependency in favour of hex-literal