Add hash customization traits

[sylvainpelissier]

Some hash function constructions allow to have a customization string to have domain separation in hash functions. This is the case for CSHAKE and Blake2:

With these new traits, the construction of hash functions with customization strings would be simpler. From currently for CSHAKE:

let mut hasher = CShake128::from_core(CShake128Core::new(b"test")); 

To:

let mut hasher = CShake128:new_personalization(b"test"));

[tarcieri]

nit: BLAKE2 calls this a "personalization string" which I think might be a bit more clear vs "custom"

[sylvainpelissier]

Should I change the function and/or parameter names ?

[tarcieri]

IMO it'd be clearer, but I'm curious what @newpavlov thinks

[newpavlov]

I don't have a particular preference, so I am fine with both options.

I wonder if we should use an associated type, instead of simple byte slice. For example, cSHAKE also takes the "function-name" argument, which also can be viewed as a customization parameter. IIRC BLAKE2 in addition to the personalization string also can take salt and perform even finer-grained personalization.

[sylvainpelissier]

For SHA3, the "function-name" argument is more an internal parameter used for example by TupleHash to instantiate CSHAKE. It may not be accessible from outside. For Blake2 I'm not aware of the salt usage.

[sylvainpelissier]

IMO it'd be clearer, but I'm curious what @newpavlov thinks

I made the changes.

[tarcieri]

I guess BLAKE3 calls it a "context string", and also has some additional stipulations about how it be used (i.e. hardcoded at compile time)

[sylvainpelissier]

Is there anything I need to add to this PR ?

[tarcieri]

@sylvainpelissier sorry for the belated reply!

I think it'd be good if you could also open a PR to https://github.com/RustCrypto/hashes which impls these traits, so we can see if e.g. the potential name conflict I was asking about would occur in practice.

Looks like this also needs a rebase.

[tarcieri]

I've changed my mind on the name "personalization", especially since it's used by BLAKE2 but not BLAKE3.

I know I didn't like "custom" before, but "customization" seems ok? It also goes well with e.g. cSHAKE.

[sylvainpelissier]

@sylvainpelissier sorry for the belated reply!

I think it'd be good if you could also open a PR to https://github.com/RustCrypto/hashes which impls these traits, so we can see if e.g. the potential name conflict I was asking about would occur in practice.

Looks like this also needs a rebase.

I'm not able to make a PR in hashes. There is an existing error when compiling hashes with the latest commit of trait (6c5f56e) without my modifications:

$ cargo build
   Compiling digest v0.11.0-pre.8 (https://github.com/RustCrypto/traits?rev=6c5f56e206ff0bbf6ac8b51a6cf4730d278d7c8b#6c5f56e2)
   Compiling sha3 v0.11.0-pre.3 (/home/sylvain/software/hashes/sha3)
   Compiling k12 v0.4.0-pre (/home/sylvain/software/hashes/k12)
error[E0277]: the trait bound `TurboShake128ReaderCore: digest::core_api::XofReaderCore` is not satisfied
   --> k12/src/lib.rs:207:11
    |
207 |     tshk: XofReaderCoreWrapper<TurboShake128ReaderCore>,
    |           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the trait `digest::core_api::XofReaderCore` is not implemented for `TurboShake128ReaderCore`
    |
    = help: the trait `digest::core_api::XofReaderCore` is implemented for `KangarooTwelveReaderCore`
note: required by a bound in `digest::core_api::XofReaderCoreWrapper`
   --> /home/sylvain/.cargo/registry/src/index.crates.io-6f17d22bba15001f/digest-0.11.0-pre.8/src/core_api/xof_reader.rs:12:8
    |
10  | pub struct XofReaderCoreWrapper<T>
    |            -------------------- required by a bound in this struct
11  | where
12  |     T: XofReaderCore,
    |        ^^^^^^^^^^^^^ required by this bound in `XofReaderCoreWrapper`

For more information about this error, try `rustc --explain E0277`.
error: could not compile `k12` (lib) due to 1 previous error
warning: build failed, waiting for other jobs to finish...

Would you prefer I rebase my modification at digest-v0.11.0-pre.8

[tarcieri]

Can you still open a PR so we can see the error in context? It's hard to tell what's wrong without code.

[sylvainpelissier]

It seems there is no naming conflict in hashes. Is there still something missing ?

[tarcieri]

I would still suggest changing the name to new_customized (sorry about backpedaling)

[sylvainpelissier]

Ah yes, I made the change to new_customized

[tarcieri]

@sylvainpelissier can you also change the trait name from Personalized* to Customized* and any other remaining instances of "personalized"?

[sylvainpelissier]

Yes right. It should be good now.

[tarcieri]

Needs rustfmt

[newpavlov]

Thank you!