HashAlgorithm - Revision history

Kevin Reid: formatting

Kevin Reid — Sat, 10 Apr 2010 18:37:44 GMT

formatting

New page

Part of a [[Hash upgradability]] design issue proposal.

Please comment, especially on whether this seems overly baroque. --[[User:Kevin Reid|Kevin Reid]] 19:03, 29 August 2009 (CDT)

==HashAlgorithm object protocol==

{{instance msgdoc|run|0||[[Tuple]]<nowiki>[</nowiki>[[OutStream]]<nowiki>[</nowiki>0..255], [[vow]]<nowiki>[</nowiki>[[#Hash|Hash]]]<nowiki>]</nowiki>}}

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.

{{instance msgdoc|hashSize|0||[[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 <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===

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 <code>[makeHash, "run", [<var>hashAlgorithm</var>, <var>hashBits</var> :[[List]][0..255]]]</code>.

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]]}}

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|hashAlgorithm|0||[[HashAlgorithm]]}}

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}}

The standard comparison protocol. If the hash algorithm is the same, returns a lexicographic comparison of the bits, else incomparable (NaN).

Kevin Reid: various revision: add Hash#hashAlgorithm/0, talk about Selfless and DeepFrozen, non-reversibility of integer/0, etc.

Kevin Reid — Sat, 10 Apr 2010 18:36:27 GMT

various revision: add Hash#hashAlgorithm/0, talk about Selfless and DeepFrozen, non-reversibility of integer/0, etc.

←Older revision		Revision as of 18:36, 10 April 2010
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}}~~	+

Kevin Reid: fix XXX template

Kevin Reid — Sat, 10 Apr 2010 17:01:16 GMT

fix XXX template

←Older revision		Revision as of 17:01, 10 April 2010
Line 33:		Line 33:
	Returns the hash value as a list of octets.		Returns the hash value as a list of octets.

-	{{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 comparison protocol. If the hash algorithm is the same, a lexicographic comparison of the bits, else incomparable (NaN).

	{{XXX\|add method to expose hashAlgorithm}}		{{XXX\|add method to expose hashAlgorithm}}

Kevin Reid: idea related to Hash upgradability

Kevin Reid — Sun, 30 Aug 2009 00:03:52 GMT

idea related to Hash upgradability

←Older revision		Revision as of 00:03, 30 August 2009
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 27:		Line 17:
	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 ~~objects~~==	+	==Hash==

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

-	Hash objects are [[Selfless~~]] and [[Transparent]]~~. Their portrayal is <code>[makeHash, "run", [<var>hashAlgorithm</var>, <var>hashBits</var> :[[List]][0..255]]]</code>.	+	Hash objects are Selfless. Their portrayal is <code>[makeHash, "run", [<var>hashAlgorithm</var>, <var>hashBits</var> :[[List]][0..255]]]</code>.

-	~~Note that by including~~ the ~~hash algorithm in the portrayal:~~	+	{{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.}}
-	* 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~~]}}	+	{{instance msgdoc\|integer\|0\|\|[[Integer]]}}

-	Returns the hash value as a ~~list of octets. This should be used as the canonical raw~~-~~bits representation of this hash~~.	+	Returns the hash value interpreted as a big-endian unsigned integer.

-	{{instance msgdoc\|~~integer~~\|0\|\|[[~~Integer~~]]}}	+	{{instance msgdoc\|octets\|0\|\|[[List]][0..255]}}
-		+
-	~~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\|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}}