hashcash 0.1

data/README

@@ -0,0 +1,49 @@
+== Description
+   A library for creating and verifying so-called »hash cash stamps«, i.e.
+   proof of work as defined on hashcash.org.
+
+== Prerequisites
+   This package requires Ruby 1.8 or later.
+
+== Installation instructions
+   rake test (optional)
+   rake install (non-gem) or rake install_gem (gem)
+
+== Synopsis
+   require 'hashcash'
+
+   # Create a new hash cash stamp
+   s = HashCash::Stamp.new(:resource => 'hashcash@alech.de')
+   puts s
+
+   # Verify a given stamp
+   s = HashCash::Stamp.new(:stamp => '1:20:060408:adam@cypherspace.org::1QTjaYd7niiQA/sc:ePa')
+   s.verify('adam@cypherspace.org)
+
+== Known bugs
+   Stamp creation is an order of magnitude slower than using the
+   standalone hash cash program. This might not be fixed as I
+   mainly use the library for verification.
+
+== Copyright
+   (c) 2010 Alexander Klink
+
+== License
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+== Warranty
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+== Author
+   Alexander Klink
+   hashcash@alech.de
+   http://www.alech.de
+   @alech on Twitter

data/lib/hashcash.rb

@@ -0,0 +1,143 @@
+require 'time'
+require 'digest/sha1'
+require 'openssl'
+require 'base64'
+
+module HashCash
+	# The HashCash::Stamp class can be used to create and verify proof of work, so
+	# called hash cash, as defined on hashcash.org.
+	#
+	# Basically, it creates a 'stamp', which when hashed with SHA-1 has a
+	# certain amount of 0 bytes at the top.
+	#
+	# To create a new stamp, call the constructor with the :resource parameter
+	# to specify a resource for which this stamp will be valid (e.g. an email
+	# address).
+	#
+	# To verify a stamp, call it with a string representation of the stamp as
+	# the :stamp parameter and call verify with a resource on it.
+	class Stamp
+		attr_reader :version, :bits, :resource, :date, :stamp_string
+
+		STAMP_VERSION = 1
+
+		# To construct a new HashCash::Stamp object, pass the :resource parameter
+		# to it, e.g.
+		#
+		# s = HashCash::Stamp.new(:resource => 'hashcash@alech.de')
+		#
+		# This creates a 20 bit hash cash stamp, which can be retrieved using
+		# the stamp_string() attribute reader method.
+		#
+		# Optionally, the parameters :bits and :date can be passed to the
+		# method to change the number of bits the stamp is worth and the issuance
+		# date (which is checked on the server for an expiry with a default
+		# deviance of 2 days, pass a Time object).
+		#
+		# Alternatively, a stamp can be passed to the constructor by passing
+		# it as a string to the :stamp parameter, e.g.
+		#
+		# s = HashCash::Stamp.new(:stamp => '1:20:060408:adam@cypherspace.org::1QTjaYd7niiQA/sc:ePa')
+		def initialize(args)
+			if ! args || (! args[:stamp] && ! args[:resource]) then
+				raise ArgumentError, 'either stamp or stamp parameters needed'
+			end
+			# existing stamp in string format
+			if args[:stamp] then
+				@stamp_string = args[:stamp]
+				(@version, @bits, @date, @resource, ext, @rand, @counter) \
+					= args[:stamp].split(':')
+				@bits = @bits.to_i
+				if @version.to_i != STAMP_VERSION then
+					raise ArgumentError, "incorrect stamp version #{@version}"
+				end
+				@date = parse_date(@date)
+			# new stamp to be created
+			elsif args[:resource] then
+				@resource = args[:resource]
+				# optional parameters: bits and date
+				@bits = args[:bits] || 20
+				@bits = @bits.to_i
+				if args[:date] && ! args[:date].class == Time then
+					raise ArgumentError, 'date needs to be a Time object'
+				end
+				@date = args[:date] || Time.now
+
+				# create first part of stamp string
+				random_string = Base64.encode64(OpenSSL::Random.random_bytes(12)).chomp
+				first_part = "#{STAMP_VERSION}:#{@bits}:" + \
+							 "#{date_to_str(@date)}:#{@resource}" + \
+							 "::#{random_string}:"
+				ctr = 0
+				@stamp_string = nil
+				while ! @stamp_string do
+					test_stamp = first_part + ctr.to_s(36)
+					if Digest::SHA1.digest(test_stamp).unpack('B*')[0][0,@bits].to_i == 0
+						@stamp_string = test_stamp
+					end
+					ctr += 1
+				end
+			end
+		end
+
+		# Verify a stamp for a given resource or resources and a number of bits.
+		# The resources parameter can either be a string for a single resource
+		# or an array of strings for more than one possible resource (for example
+		# if you have different email addresses and want the stamp to verify against
+		# one of them).
+		#
+		# The method checks the resource, the time of issuance and the number of
+		# 0 bits when the stamp is SHA1-hashed. It returns true if all checks
+		# are successful and raises an exception otherwise.
+		def verify(resources, bits = 20)
+			# check for correct resource
+			if resources.class != String && resources.class != Array then
+				raise ArgumentError, "resource must be either String or Array"
+			end
+			if resources.class == String then
+				resources = [ resources ]
+			end
+			if ! resources.include? @resource then
+				raise "Stamp is not valid for the given resource(s)."
+			end
+			# check if difference is greater than 2 days
+			if (Time.now - @date).to_i.abs > 2*24*60*60 then
+				raise "Stamp is expired/not yet valid"
+			end
+			# check 0 bits in stamp
+			if (Digest::SHA1.hexdigest(@stamp_string).hex >> (160-bits) != 0) then
+				raise "Invalid stamp, not enough 0 bits"
+			end
+			true
+		end
+
+		# A string representation of the stamp
+		def to_s
+			@stamp_string
+		end
+
+		private
+		# Parse the date contained in the stamp string.
+		def parse_date(date)
+			year  = date[0,2].to_i
+			month = date[2,2].to_i
+			day   = date[4,2].to_i
+			# Those may not exist, but it is irrelevant as ''.to_i is 0
+			hour  = date[6,2].to_i
+			min   = date[8,2].to_i
+			sec   = date[10,2].to_i
+			Time.utc(year, month, day, hour, min, sec)
+		end
+
+		# Convert a date to the string format used in the stamps
+		def date_to_str(date)
+			if (date.sec == 0) && (date.hour == 0) && (date.min == 0) then
+				date.strftime("%y%m%d")
+			elsif (date.sec == 0) then
+				date.strftime("%y%m%d%H%M")
+			else
+				date.strftime("%y%m%d%H%M%S")
+			end
+		end
+	end
+end

data/test/test_hashcash.rb

@@ -0,0 +1,50 @@
+require 'test/unit'
+require 'lib/hashcash'
+require 'digest/sha1'
+
+class TestHashCash < Test::Unit::TestCase
+    WIKIPEDIA_EXAMPLE = '1:20:060408:adam@cypherspace.org::1QTjaYd7niiQA/sc:ePa'
+
+	def test_instantiation
+		assert_raise( ArgumentError ) { HashCash::Stamp.new }
+        assert(HashCash::Stamp.new(:resource => 'testhashcash'))
+        assert(HashCash::Stamp.new(:resource => 'foobar', :bits => 15))
+        assert(HashCash::Stamp.new(:stamp => WIKIPEDIA_EXAMPLE))
+	end
+
+	def test_parsing
+        s = HashCash::Stamp.new(:stamp => WIKIPEDIA_EXAMPLE)
+        assert_equal(1, s.version.to_i)
+        assert_equal(20, s.bits)
+        assert_equal(2006, s.date.year)
+        assert_equal(4, s.date.month)
+        assert_equal(8, s.date.day)
+	end
+
+    def test_verify_errors
+        s = HashCash::Stamp.new(:stamp => WIKIPEDIA_EXAMPLE)
+        # wrong resource
+        assert_raise( RuntimeError ) { s.verify('foo@example.org') }
+        # expired
+        assert_raise( RuntimeError ) { s.verify('adam@cypherspace.org') }
+        # not enough 'cash'
+        stamp = "1:32:" + Time.now.strftime('%y%m%d') + ':testhashcash::foobar1234:1'
+        # make sure it is really not enough
+        while (Digest::SHA1.hexdigest(stamp).hex >> (160-32) == 0) do
+            stamp += '1'
+        end
+        s2 = HashCash::Stamp.new(:stamp => stamp)
+        assert_raise( RuntimeError ) { s.verify('testhashcash') }
+    end
+
+    def test_create_and_verify
+        s = HashCash::Stamp.new(:resource => 'testhashcash')
+        assert(s.verify('testhashcash'))
+
+        s2 = HashCash::Stamp.new(:resource => 'testhashcash', :bits => 10)
+        assert(s2.verify('testhashcash', 10))
+
+        s3 = HashCash::Stamp.new(:resource => 'testhashcash', :bits => 10, :date => Time.now)
+        assert(s3.verify('testhashcash', 10))
+    end
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+name: hashcash
+version: !ruby/object:Gem::Version 
+  hash: 9
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  version: "0.1"
+platform: ruby
+authors: 
+- Alexander Klink
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-09-24 00:00:00 +02:00
+default_executable: 
+dependencies: []
+
+description: "A library for creating and verifying so-called \xC2\xBBhash cash stamps\xC2\xAB, i.e.\n\
+  proof of work as defined on hashcash.org.\n"
+email: hashcash@alech.de
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- lib/hashcash.rb
+- test/test_hashcash.rb
+- README
+has_rdoc: true
+homepage: 
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A library to create hash cash stamps as defined on hashcash.org.
+test_files: 
+- test/test_hashcash.rb