digest: add FixedOutputDirty trait + finalize_into*

[tarcieri]

ClosesRustCrypto/hashes#86

Replaces the Reset trait with a set of _reset methods on all of the various traits, and uses these as the default impl for the methods which consume hashers.

Also adds a set of methods to FixedOutput (finalize_fixed_into*) which eliminate copies by accepting an existing buffer as an argument.

Adds a FixedOutputDirty trait which writes the digest output to a provided byte array, but does not reset the internal state. This is intended for implementations to use in order to ensure that they are not reset in the event the instance is consumed.

Also adds a set of finalize_into and finalize_into_reset methods to FixedOutput whhich also write their input into a provided byte array, and changes the existing finalize_fixed (and newly added finalize_fixed_reset) methods to have a default implementation which returns a byte array allocated on the stack.

Finally, adds a blanket impl of FixedOutput for FixedOutputDirty + Reset types which handles safely invoking the underlying implementation by either consuming the instance (avoiding a reset) or borrowing the hasher, obtaining the output, and resetting.

[tarcieri]

@newpavlov this is slightly different from what you originally proposed, but I think achieves the same effect. Namely if you wanted something exactly like what you had before, it could be achieved with:

implMyDigest{/// Private method not intended to be used directlyfnfinalize_fixed_core(&mutself,out:&mutGenericArray<u8,Self::OutputSize>,reset:bool){[...]}}implFixedOutputforMyDigest{typeOutputSize = [...];#[inline]fnfinalize_fixed(self) -> GenericArray<u8,Self::OutputSize>{letmut buf = Default::default();self.finalize_fixed_core(&mut buf,false);
buf
}#[inline]fnfinalize_fixed_reset(&mutself) -> GenericArray<u8,Self::OutputSize>{ .. }fnfinalize_fixed_into(self,out:&mutGenericArray<u8,Self::OutputSize>){ .. }fnfinalize_fixed_into_reset(&mutself,out:&mutGenericArray<u8,Self::OutputSize>){ .. }}

...it's just by not making it part of the trait, it could actually be a private method.

[newpavlov]

One problem with this approach is that it makes harder for compiler to eliminate reset code, this is why I was thinking about using the private method, which would keep reset code behind a simple branch which can eliminated by trivial const propagation. Before going with this approach, it would be nice to see that compiler is indeed will be able to properly remove reset code for finalize_fixed.

[tarcieri]

That's only if you rely on the default implementation though. If you want to avoid the resets entirely, just define your own implementation (per above) which doesn't invoke the reset code at all.

[newpavlov]

This will lead to unnecessary code duplication, which I would like to avoid.

How about something like this?

pubtraitFixedOutput{// .../// Retrieve result into provided buffer and leave hasher in a dirty state./// Usage of this method in user code is discouraged, prefer `finalize_fixed`/// or `finalize_fixed_reset`.fnfinalize_into_dirty(&mutself,out:&mutGenericArray<u8,Self::OutputSize>);fnfinalize_into_reset(&mutself,out:&mutGenericArray<u8,Self::OutputSize>)whereSelf:Reset,{self.finalize_into_dirty(out);self.reset();}}pubtraitReset{fnreset(&mutself);}

Yes, users may misuse finalize_into_dirty (use a scarier name?), but I don't think it will be a significant issue in practice.

[tarcieri]

I think you could achieve something like that with a separate trait and a blanket impl:

pubtraitFixedOutputDirty{/// Retrieve result into provided buffer and leave hasher in a dirty state./// Usage of this method in user code is discouraged, prefer `finalize_fixed`/// or `finalize_fixed_reset`.fnfinalize_into_dirty(&mutself,out:&mutGenericArray<u8,Self::OutputSize>);}impl<D:FixedOutputDirty + Reset>FixedOutputforD{#[inline]fnfinalize_into(&mutself,out:&mutGenericArray<u8,Self::OutputSize>)whereSelf:Reset,{self.finalize_into_dirty(out);}#[inline]fnfinalize_into_reset(&mutself,out:&mutGenericArray<u8,Self::OutputSize>)whereSelf:Reset,{self.finalize_into_dirty(out);self.reset();}}

[tarcieri]

Also should I shorten finalize_fixed_into to finalize_into? Seems ok to me.

[newpavlov]

The separate trait looks good, making room for FixedOutput to be used separately from the dirty trait (e.g. for HW accelerated impls) is certainly nice.

Also should I shorten finalize_fixed_into to finalize_into?

Yes, sounds good.

[tarcieri]

Updated to use a FixedOutputDirty trait + blanket impl. I like this approach especially because it's a much less invasive change.

[newpavlov]

BTW should we do something similar for XOF and VariableOutput?

[tarcieri]

Sure