Part of a Hash upgradability design issue proposal.
Please comment, especially on whether this seems overly baroque. --Kevin Reid 19:03, 29 August 2009 (CDT)
HashAlgorithm object protocol
Prepares for a hash computation. Write the data to be hashed to the returned OutStream; when it is closed the returned promise will (synchronously) resolve to the hash value.
- Signature: hashSize() :Integer
Returns the number of bits in the hashes produced.
It should be the case that
def [stream, hash] := someHashAlgorithm() ...do anything with stream... !Ref.isNear(hash) || hash.hashAlgorithm() == someHashAlgorithm
XXX Note that the above property can be enforced by a wrapper. Change protocol so that there isn't such a property to violate, by having a canonical hash-maker? i.e. hash(hashAlgorithm) => [OutStream,vow[Hash]] and the hashAlgorithm just returns the bits. Or is this too much complexity for the client by having to import 'hash' as well as the algorithm?
To discuss: add convenience method to hash a given List[0..255]? A given integer?
For flexibility, discoverability, and type checking benefits, hash algorithms return Hash objects which contain the bits of the hash value. All hash algorithms use the same implementation of Hash objects, but Hash objects are tagged with the algorithm that produced them.
Note that by including the hash algorithm in the portrayal:
- A vat unserializing a Hash either must have that hash algorithm implementation, or the algorithm must unserialize as a dummy HashAlgorithm which has a name but no actual implementation. (The latter means that at least the vat can represent and pass around the hash objects.)
- Given a hash, you can hash other data using the same algorithm without previously knowing of that algorithm. XXX Crypto people please comment: Is this actually useful?
- Signature: octets() :List[0..255]
Returns the hash value as a list of octets. This should be used as the canonical raw-bits representation of this hash.
- Signature: integer() :Integer
Returns the hash value interpreted as a big-endian unsigned integer. Note that if the hash value happens to begin with at least 8 zero bits, then the conversion is not reversible: interpreting the integer as a list of octets will lose that leading zero octet(s).
- Signature: hashAlgorithm() :HashAlgorithm
Return the hash algorithm which produced this hash.
- Signature: op__cmp(other :any[Hash, any]) :comparison result XXX write spec on op__cmp and how this should be described
The standard comparison protocol. If the hash algorithm is the same, returns a lexicographic comparison of the bits, else incomparable (NaN).