HashAlgorithm

From Erights

(Difference between revisions)
Jump to: navigation, search
m (fix XXX template)
(various revision: add Hash#hashAlgorithm/0, talk about Selfless and DeepFrozen, non-reversibility of integer/0, etc.)
Line 12: Line 12:
Returns the number of bits in the hashes produced.
Returns the number of bits in the hashes produced.
 +
 +
===Properties===
 +
 +
A HashAlgorithm should be [[DeepFrozen]] and [[PassByCopy]].
 +
 +
It should be the case that
 +
def [stream, hash] := someHashAlgorithm()
 +
...do anything with <var>stream</var>...
 +
!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?}}
===Extensions===
===Extensions===
Line 17: Line 27:
To discuss: add convenience method to hash a given List[0..255]? A given integer?
To discuss: add convenience method to hash a given List[0..255]? A given integer?
-
==Hash==
+
==Hash objects==
-
For flexibility, discoverability, and type checking benefits, hash algorithms return Hash objects which contain the bits of the hash value. All hash algorithms produce the same Hash object, but Hash objects are tagged with the algorithm that produced them.
+
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.
-
Hash objects are Selfless. Their portrayal is <code>[makeHash, "run", [<var>hashAlgorithm</var>, <var>hashBits</var> :[[List]][0..255]]]</code>.
+
Hash objects are [[Selfless]] and [[Transparent]]. Their portrayal is <code>[makeHash, "run", [<var>hashAlgorithm</var>, <var>hashBits</var> :[[List]][0..255]]]</code>.
-
{{XXX|What exactly is the hashAlgorithm value of a Hash? The algorithm object? A string? Must take into consideration letting them unserialize on vats that don't have the hash algorithm itself.}}
+
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?}}
 +
 
 +
{{instance msgdoc|octets|0||[[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.
{{instance msgdoc|integer|0||[[Integer]]}}
{{instance msgdoc|integer|0||[[Integer]]}}
-
Returns the hash value interpreted as a big-endian unsigned 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).
-
{{instance msgdoc|octets|0||[[List]][0..255]}}
+
{{instance msgdoc|hashAlgorithm|0||[[HashAlgorithm]]}}
-
Returns the hash value as a list of octets.
+
Return the hash algorithm which produced this hash.
{{instance msgdoc|op__cmp|1|other :any[Hash, any]|comparison result}} {{XXX|write spec on op__cmp and how this should be described}}
{{instance msgdoc|op__cmp|1|other :any[Hash, any]|comparison result}} {{XXX|write spec on op__cmp and how this should be described}}
-
The comparison protocol. If the hash algorithm is the same, a lexicographic comparison of the bits, else incomparable (NaN).
+
The standard comparison protocol. If the hash algorithm is the same, returns a lexicographic comparison of the bits, else incomparable (NaN).
-
 
+
-
{{XXX|add method to expose hashAlgorithm}}
+

Revision as of 18:36, 10 April 2010

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)

Contents

HashAlgorithm object protocol

run/0

Signature: run() :Tuple[OutStream[0..255], vow[Hash]]

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.

hashSize/0

Signature: hashSize() :Integer

Returns the number of bits in the hashes produced.

Properties

A HashAlgorithm should be DeepFrozen and PassByCopy.

It should be the case that 

def [stream, hash] := someHashAlgorithm()
...do anything with stream...
!Ref.isNear(hash) || hash.hashAlgorithm() == someHashAlgorithm

XXX

Extensions

To discuss: add convenience method to hash a given List[0..255]? A given integer?

Hash objects

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.

Hash objects are Selfless and Transparent. Their portrayal is [makeHash, "run", [hashAlgorithm, hashBits :List[0..255]]].

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?

octets/0

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.

integer/0

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).

hashAlgorithm/0

Signature: hashAlgorithm() :HashAlgorithm

Return the hash algorithm which produced this hash.

op__cmp/1

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).

Retrieved from "http://wiki.erights.org/wiki/HashAlgorithm"
Personal tools
more tools