Re: [boost] [rfc] Preliminary Hash Library

Subject: Re: [boost] [rfc] Preliminary Hash Library
From: Stewart, Robert (Robert.Stewart_at_[hidden])
Date: 2010-05-08 09:47:14

Scott McMurray wrote:
> On 6 May 2010 07:54, Stewart, Robert <Robert.Stewart_at_[hidden]> wrote:
> >
> > Not everyone considering your library knows about
> > cryptographic hashes and the terminology relating to them.
> > [...] Listing reasons for having created the library should
> > be part of a Rationale section, or similar.
>
> I've added an Introduction defining terms and suggesting usages, and
> moved the history to a Rationale.

You launch right into describing cryptographic hashes rather than the library, making the Introduction an introduction to cryptographic hashes.  Perhaps this would work well:

"The MaybeBoost Hash library provides concept-based hashing algorithms of various kinds for use in cryptography, mostly as part of authentication schemes, plus corruption detection, digital fingerprinting, and duplication detection. For more information on cryptographic hashing, see the <Wikipedia article>.

"A hashing algorithm produces a small encoded representation of a message called a _digest_ (sometimes known as a _hash_). The digest is most useful when it is unique to that message alone and cannot be used to recreate the original message. There are numerous hashing algorithms that satisfy these criteria to differing degrees, with variations in digest size and processing time required.

"To be more specific, a hashing algorithm H takes a message M and produces a B-bit digest, D = H(M), in such a way that the following properties hold:"

Notice that I removed the emphasis on "cryptographic" in the foregoing as I think you intend the library to include more than those algorithms.

For clarity, perhaps use boldface on the terms or capitalize all words in the terms (when defining them, at least).

"Second preimage resistance" and "Collision resistance" seem alike to me, based upon the explanations.  Since both assert difficulty in H(M) = H(M'), where M and M' are different messages, what is different?

In, "As their name suggests," the antecedent for "their" is vague.  I suggest, "As the name cryptographic hash suggests, such algorithms have many uses...."

As you can tell, I've reordered some of the content anyway.

> > To what bits does, "All the bits in the provided values are
> > used," refer?  Did you mean something like, "All bits in the
> > input range values are used?"
>
> Yes.  I've changed it to use your phrasing.
>
> > Do you support Boost.Range/RangeEx?
>
> Yes.  The documentation now has a "single-pass range of
> readable iterators".
>
> > I don't understand to what the Portability Note applies.
> > [...] The Alternative may make more sense when you clarify
> > the "all bits" part I raised above.
>
> I've rephrased both these sections; Let me know whether the changes
> are any better.

Much better.

> > Is "HashPolicy" a good name?  Is "Hash" not enough?  That
> > is, the Hash Concept?  You don't have "MessageDigestPolicy"
> > or "StreamHashPolicy," so why "HashPolicy?"
>
> I put "Policy" in that name to emphasize that its usual usage would be
> as a policy template argument, rather than providing any functions.
> I've spelt that out explicitly now, and changed the concept name to
> HashAlgorithm.  I'd prefer not to use just "Hash" since some people
> refer to digests as hashes, so I think being more explicit would be
> better.

I like the new name and I used the hash <=> digest part in my Introduction rewrite.

> > StreamHash Concept
> >
> > Notice that I removed the "<ValueBits>" part.  I don't
> > think that should be part of the concept name.
>
> The thing is that a StreamHash that looks at the bottom 4 bits of a
> value in update_one is semantically very different one one that looks
> at all 8 bits, so I considered that important enough to be part of the
> concept name.  It also simplifies the description of HashAlgorithm,
> since it needs to say somehow that stream_hash<4>::type is different
> from stream_hash<8>::type.

While those variations are semantically different, they all support the same concept, don't they?  That is, StreamHash<2> is the same *concept* as StreamHash<4>, even if the implementation of the two differs.

> > What does, "Provided models are accessible through
> > HashPolicy models," mean?
>
> I've changed that part to read, "Each HashAlgorithm  model provides
> access to all its associated StreamHash models; Those StreamHash
> models are generally not accessible in other ways."  It's not
> essential though, and could be removed if it's more confusing than
> helpful.

s/models; Those/modesl; those/

That statement suggests that one shouldn't instantiate a stream_hash<N> directly, yet you don't say so.  Perhaps you mean, "StreamHash models are typically generated from a HashAlgorithm by the expression ha::stream_hash<N>::type."  That's a little more concrete and implies your intention of not creating some stream_hash<N> directly.

_____
Rob Stewart                           robert.stewart_at_[hidden]
Software Engineer, Core Software      using std::disclaimer;
Susquehanna International Group, LLP  http://www.sig.com

IMPORTANT: The information contained in this email and/or its attachments is confidential. If you are not the intended recipient, please notify the sender immediately by reply and immediately delete this message and all its attachments. Any review, use, reproduction, disclosure or dissemination of this message or any attachment by an unintended recipient is strictly prohibited. Neither this message nor any attachment is intended as or should be construed as an offer, solicitation or recommendation to buy or sell any security or other financial instrument. Neither the sender, his or her employer nor any of their respective affiliates makes any warranties as to the completeness or accuracy of any of the information contained herein or that this message or any of its attachments is free of viruses.