Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
HASHCASH(1)			   hashcash			   HASHCASH(1)

NAME
       hashcash	- hashcash anti-spam / denial of service counter-measure tool

SYNOPSIS
       Mint (create) stamps:

       hashcash	-m [ [ options ] [ resource ...	] ... ]

       Check stamps:

       hashcash	-c [ [ options ] -r resource ... ] [ stamp ... ]

       Speed estimates:

       hashcash	-s [ options ] [ -b bits ]

       Purge database:

       hashcash	-p now [ -j resource ] [ -k ] [	-t time	] [ -u ]

       Count partial preimage bits:

       hashcash	-w [ options ] [ stamp ... ]

       Get resource name:

       hashcash	-n [ options ] [ stamp ... ]

       Get time	remaining until	expiry

       hashcash	-l [ options ] -e period [ stamp ... ]

DESCRIPTION
       Hashcash	is a denial-of-service counter measure tool.  Its main current
       use  is	to help	hashcash users avoid losing email due to content based
       and blacklist based anti-spam systems.

       The hashcash tool allows	you to create hashcash	stamps	to  attach  to
       emails  you  send, and to verify	hashcash stamps	attached to emails you
       receive.	 Email senders attach hashcash	stamps	with  the  X-Hashcash:
       header.	 Vendors  and authors of anti-spam tools are encouraged	to ex-
       empt mail sent with hashcash from their blacklists  and	content	 based
       filtering rules.

       A hashcash stamp	constitutes a proof-of-work which takes	a parameteriz-
       able  amount of work to compute for the sender.	The recipient can ver-
       ify received stamps efficiently.	 This package also includes a sha1 im-
       plementation which is equivalent	in functionality to the	 sha1sum  pro-
       gram available on some systems.

       The  hashcash  proof-of-work function is	to compute partial hash	preim-
       ages (the SHA1 hash function is used).  By choosing the number of  bits
       of  the	preimage  that	are equal to 0,	the work required to compute a
       partial preimage	can be made arbitrarily	expensive -- from fractions of
       a second	to minutes or hours.  The verification is efficient  requiring
       the same	small cost whatever the	preimage size.

       For  more  detailed  discussion of other	applications hashcash has been
       used for	see http://www.hashcash.org/

USAGE NOTES
       In this man page	a resource name	is the name of the service or  address
       the  stamp  is created for.  In the case	of email, the resource name is
       the recipient's email address in	the form user@domain.com.

       Minting stamps

       The -m flag must	be given to mint a stamp.

       The resource name (recipient's email address) to	mint the stamp against
       can be passed as	an argument, or	if omitted is  read  from  stdin.   If
       stdin  is  a  tty the user is prompted, if stdin	is a pipe the resource
       name is just silently read.  The	desired	preimage size can be specified
       with the	-b option.  If no preimage size	is specified, the  default  is
       20 bits.	 See also the -b default option.

       Checking	stamps

       The -c flag must	be given to check a stamps expiry.  The	stamp to check
       can  be	given  as an argument to "hashcash".  If no stamp is given the
       stamp is	read from stdin.  If stdin is a	tty the	user will be prompted,
       if stdin	is a pipe the stamp is just silently read.   A	resource  name
       (the  recipient's email address)	can be given with the -r option.  If a
       resource	name is	given the resource name	is compared  to	 the  resource
       name in the stamp, if they do not match,	the stamp is rejected.

       Note:  if  no resource name is given the	stamp is anyway	checked	to see
       if it is	otherwise valid, but it	could be minted	for  a	different  re-
       source,	which  would  allow  stamps  to	be reused across different re-
       sources,	so hashcash will return	unchecked exit code on exit.

       Stamps are by default considered	to be valid for	28 days.  The validity
       period can be changed using the -e flag.

       If the stamp has	expired	or has a date in the future the	stamp  is  re-
       jected and the program exits immediately.

       If a required preimage size is given with the -b	flag, the stamps value
       is  computed and	compared, if the stamp has insufficent value it	is re-
       jected, and the program exits immediately.   If	the  -b	 flag  is  not
       given,  the stamp is checked to see if it is otherwise valid, but hash-
       cash will return	unchecked exit code on exit.

       If the stamp is double spent the	stamp is  rejected.   Double  spending
       protection  is  discussed in more detail	below in "Double Spending Pro-
       tection".  If double spending protection	 is  not  enabled,  the	 stamp
       could  be  double  spent,  so  hashcash will return unchecked exit code
       (exit code 2) on	exit.

       The -w flag can be used to request that	the  number  of	 bits  of  the
       preimage	 are counted and displayed. The	-n flag	can be used to request
       that the	resource name in the stamp is parsed out and  displayed.   The
       -l  flag	 can  be used to request the number of seconds until expiry of
       the stamp is output.

       The program will	only return exit codes valid or	invalid	if the -c flag
       is used,	the -b flag is used, -d, -r resource are used.	These are  the
       minimum set of options necessary	to fully check the validty of a	stamp.
       If  these  criteria  are	 not  met,  the	 program will return exit code
       unchecked (exit code 2) on exit.	 (See also the -y flag.)

       Double Spending Protection

       If the -d flag is used when checking stamps, a database of spent	stamps
       is kept.

       By default stamps expire	after 28 days,	without	 expiry	 the  database
       would  grow  indefinately.   You	can specify an alternate expiry	period
       with the	-e flag.  The recommended  (and	 default)  expiry  period  for
       email is	28 days.  After	the expiry period amount of time, the stamp is
       anyway  considered  expired and may be purged from the database to save
       space.  (See "Purging Periodically vs on	Next Access" for how to	 purge
       stamps.)

       For  efficiency reasons a stamp is verified before it is	checked	in the
       database; if it is otherwise invalid no database	activity will occur.

       Note: The decision about	how long the stamp should be considered	 valid
       is  up to the verifier.	If it is too short it is possible for some ap-
       plications that the stamp will expire before arriving at	the  recipient
       (eg  with  email.)   The	 suggested value of 28 days should be safe for
       normal email delivery delays.  The choice is a trade-off	between	 data-
       base  size  and risk of expiry prior to arrival,	and depends on the ap-
       plication.

       Note: Different stamps in the same database can have different validity
       periods,	so for example stamps for different resources  with  different
       validity	 periods  can be stored	in the same database, or the recipient
       may change the validity period for future stamps	without	affecting  the
       validity	of old stamps.

       Purging Periodically vs on Next Access

       To  purge  old stamps periodically while	checking stamps	use the	-p pe-
       riod option to purge no sooner than the given  time  period  since  the
       last  purge.  Purging can be used with the -k option to purge unexpired
       stamps also, and	with the -j resource flag to purge only	stamps for the
       given resource.

       There are circumstances where it	may be inconvenient to purge stamps on
       the next	access,	for example if there is	a large	double spend  database
       which  takes  some time to purge, and the response time of the hashcash
       checker is important.  To avoid this problem, purging can be done sepa-
       rately using just the -p	now option to request just  the	 purge	opera-
       tion.   On  unix	for example you	could call "hashcash -p	now" in	a cron
       job once	per day, or on demand when disk	was running low.

       Speed Estimates

       The -s flag requests measurement	of how many preimage can be tested per
       second.	No stamp is minted, or verified.

       If the -b flag is used with this	option,	instead	 an  estimate  of  how
       many seconds it would take to mint a stamp of the given size in bits is
       computed.   To  find  out  how much time	it will	take to	mint a default
       sized stamp use -s -b default.

       Notes

       All informational output	is printed on stderr.  Minted stamps, and  re-
       sults  of  stamp	 verification  and  timing are printed on stdout.  The
       quiet flag -q suppresses	all informational output.   The	 -v  flag  re-
       quests  more  informational output.  The	requested output, which	is the
       only information	that is	output in quiet	mode (when -q is specified) is
       printed on standard output.  If stdout is a pipe, or when quiet mode is
       in effect the output is printed without description (ie just bits, just
       seconds,	just resource).

OPTIONS
       -c  Check the expiry information	of stamps given	as an argument	or  on
	   stdin.  (Use	with -b, -d and	-r resource to fully check stamps).

       -m  Mint	stamps with the	resources given	as arguments or	on stdin.

       -b bits
	   When	minting	a stamp, create	a preimage of at least this many bits.
	   When	 verifying a stamp require that	it have	a preimage of at mini-
	   mum this many bits, otherwise reject	it.  If	omitted	the default is
	   used.

	   When	checking stamps, require that the stamps have this many	bits.

	   The default number of bits can be specified with -b default.	  Bits
	   relative to the default can also be specified with -b +n for	n bits
	   more	than the default and -b	-n for n bits less than	the default.

	   -b default, -b +0 and -b -0 are all equivalent.

	   When	doing the speed	test -s, can to	measure	speed of default token
	   with	-s -b default.

       -r resource
	   When	 minting stamps, the resource name (recipient's	email address)
	   to mint the stamp against can be given either with -r  resource  or
	   as an argument to "hashcash".

	   When	checking stamps, the resource name (your own email address) is
	   given  with	the  -r	 option.   If the resource name	is given it is
	   checked against the resource	name in	the stamp, and if they do  not
	   match  the  stamp  is  rejected.   Note if the resource name	is not
	   given, stamps for other resources would be accepted,	and  therefore
	   hashcash returns exit code unchecked	(exit code 2) on exit.

       -o  When	 verifying stamps multiple resources can be given.  By default
	   the resources are just checked one by one until  a  matching	 valid
	   resource  is	 found.	 However when you use wildcards	or regular ex-
	   pressions (see -E), it is useful to be able to specify that one re-
	   source overrides another.  For example this:	-b15 -r	 adam@dev.null
	   -o  -b10  *@dev.null	 states	that mail to address adam@dev.null re-
	   quires 15 bits, but mail to *@dev.null requires only	10  bits.   If
	   we  omitted the -o override relationship between the	two resources,
	   a stamp of 10 bits would be accepted	for address adam@dev.null  be-
	   cause  while	it would be rejected as	having insufficient bits under
	   the first rule, it would be accepted	under the 2nd  rule.   The  -o
	   option allows you avoid this	problem.

       -e time
	   Expiry  period  for spent stamps.  While checking stamps (using the
	   -c flag), if	the stamp was minted more than the specified amount of
	   time	ago, it	is considered expired.	If this	option is not used, by
	   default stamps expire after 28 days.	 The expiry period is given in
	   seconds by default (an argument of  0  means	 forever).   A	single
	   character  suffix  can be used to specify alternate units (m	= min-
	   utes, h = hours, d =	days, M	= months, y = Y	= years, and s =  sec-
	   onds).

	   If  used  with the -d option, the spent stamp and its expiry	period
	   is recorded in the database.	 See the -p option for description  of
	   how to purge	stamps from the	database.

	   While minting stamps, the -e	flag can have an effect	on the resolu-
	   tion	 of time created in the	stamp.	Without	the -e option, the de-
	   fault resolution is days (time format: YYMMDD).  Alternate  formats
	   based on range of expiry period are as follows:

	   While minting you can also given an explicit	time width with	the -z
	   option  instead.   (-z  overrides -e	if both	are given.  If neither
	   are given the default is 6 chars (time format: YYMMDD)).

	   The rules for automatically determining appropriate time width from
	   -e if no -z option is given are:

	   * period >= 2 years then time format	YY is used rounded down	to the
	   nearest year	start;
	   * 2 years < period <= 2 months then time format YYMM	is used
	   rounded down	to the nearest month start;
	   * 2 months <	period <= 2 days then time format YYMMDD is used
	   rounded down	to the begining	of the nearest day;
	   * 2 days < period <=	2 minutes then time format YYMMDDhhmm is used
	   rounded down	to the begining	of the nearest minute;
	   * period < 2	minutes	then time format YYMMDDhhmmss is used in sec-
	   onds.

	   Note	the rounding down is based on UTC time,	not local time.	  This
	   can	lead  to  initially suprising results when rounding down to eg
	   days	in time	zones other than GMT (UTC = GMT).  It may  be  clearer
	   to understand if you	use the	-u option.

       -z width
	   The	-z  option is for use during minting and allows	user choice of
	   width of time width field.  See also	the -e option given in	combi-
	   nation  with	 -m  to	specify	an implicit time field width under the
	   description of the -e flag.	Valid widths are 6,10 or 12 chars cor-
	   responding respectively to: YYMMDD,	YYMMDDhhmm,  and  YYMMDDhhmmss
	   rounded down	to the nearest day, or minute respectively.

	   Note	 the rounding down is based on UTC time, not local time.  This
	   can lead to initially suprising results when	rounding  down	to  eg
	   days	 in  time zones	other than GMT (UTC = GMT).  It	may be clearer
	   to understand if you	use the	-u option.

       -g period
	   The -g option is for	use when checking hashcash stamps with the  -c
	   option  and	specifies a grace period for clock skew, ie if a hash-
	   cash	stamp arrives with a date in the future	or in the past it will
	   not be rejected as having a futuristic date (or as  being  expired)
	   unless  it is more futuristic (or has been expired for longer) than
	   this	period.	 The default is	2 days,	which means  as	 long  as  the
	   sending  system's clock is no more than 2 days ahead	(or 2 days be-
	   hind) of the	receiving system's  clock,  the	 hashcash  stamp  will
	   still be accepted.

	   The default units for grace period are seconds.  A single character
	   suffix  can	be  used  to specify alternate units (m	= minutes, h =
	   hours, d = days, M =	months,	y = Y =	years, and s = seconds).

       -d  Store stamps	in a double spend database.  If	stamp  has  been  seen
	   before  it will be rejected even if it is otherwise valid.  The de-
	   fault database file is database.sdb in the current directory.  Only
	   otherwise valid stamps will be stored in the	database.  Only	 fully
	   validated  stamps will be stored in the database, unless the	-y op-
	   tion	is given.

       -f dbname
	   Use dbname instead of default filename for double spend database.

       -p period
	   Purges the database of expired stamps if the	given time period  has
	   passed  since the last time it was purged.  As a convenience	-p now
	   is equivalent to -p 0 both of which mean purge now,	regardless  of
	   when	the database was last purged.

	   If  used in combination with	-j resource only the stamps minted for
	   the given resource are purged.

	   If used in combination with -k all stamps  even  un-expired	stamps
	   are	purged.	  Can be used in combination with -t time to expire as
	   if the current time were the	given time.

       -k  Use with option -p to request all stamps  are  purged  rather  than
	   just	expired	ones.

       -j resource
	   Use	with  option -p	to request that	just stamps matching the given
	   resource name are to	be purged, rather than the default which is to
	   purge all expired stamps.   If  the	resource  name	is  the	 empty
	   string,  all	stamps are matched (this is equivalent to omitting the
	   -j option).

	   Note	the -E,	-M and -S type of match	flags also apply to  resources
	   given with the -j resource flag.

       -s  Print timing	information only, and don't proceed to create a	stamp.
	   If  combined	 with  -b bits flag print estimate of how long the re-
	   quested preimage size would take to compute,	if -s given by itself,
	   just	prints speed of	the preimage finder.  To print an estimate  of
	   how long the	default	number of bits would take use -b default.

       -h  Print short usage information.

       -v  Print  more verbose informational output about the stamp minting or
	   verification.  (If -v is the	only argument, prints the tool version
	   number.)

       -V  Prints tool version number.

       -q  Batch mode.	Prints no information other than output.  This	option
	   overrides the -v option.

       -X  When	minting, prints	the hashcash email X-header 'X-Hashcash: ' be-
	   fore	 the  stamp.   Without	this  option  just  the	 bare stamp is
	   printed.

	   When	checking, after	scanning  stamps  given	 as  arguments,	 scans
	   stdin  for  lines  starting with the	string 'X-Hashcash:', and uses
	   the rest of the matching line as the	stamp.	Only the lines	up  to
	   and	ending	at  the	first blank line are scanned (see also -i flag
	   which can be	used to	override this).	 A blank line is the separator
	   used	to separate the	headers	from the body of  a  mail  message  or
	   USENET article.  This is meant to make it convenient	to pipe	a mail
	   message or USENET article to	hashcash on stdin.

       -x extension
	   An  extension  string  composed  of name value sets.	 The extension
	   format is described below in	the section on the hashcash stamp for-
	   mat.	 This allows users to define their own stamp extensions	 which
	   are	hashed	into  the  stamp,  verified by recipients that support
	   them, and ignored by	recipients that	don't support them.  Note  the
	   extension  hook  mechanism has not yet been implemented.  This will
	   come	in a subsequent	release.

       -i  When	checking and using the -X flag,	ignore the blank line boundary
	   between headers and body of the message, and	check  for  stamps  in
	   the body too	if one is not found in the headers.

       -t time
	   Pretend  the	current	time is	the time given for purposes of minting
	   stamps, verifying stamps and	purging	old stamps from	the  database.
	   Time	is given in a format based on UTCTIME format YYMMDD[hhmm[ss]].

	   Time	 is  expressed	in local time by default.  Use with -u flag to
	   give	time in	UTC (GMT).

	   You can also	give time relative to the current  time	 by  prefixing
	   the	argument with +	or -.  The default units for relative time are
	   seconds.  A single character	suffix can be used to  specify	alter-
	   nate	 units	(m = minutes, h	= hours, d = days, M = months, y = Y =
	   years, and s	= seconds).

	   Note: when time is expressed	in local time, if  there  is  daylight
	   savings  in your timezone, there are	one or two ambiguous hours per
	   year	at the time of change from daylight  savings  time  to	normal
	   time.

       -u  Input and output absolute times in UTC (GMT)	instead	of local time.

       -a period
	   Add	(or  subtract  if  number is negative) a random	value from the
	   current time	before minting the stamp.  This	 hides	the  time  the
	   stamp  was  created,	which may be useful for	anonymous users.  Note
	   adding (rather than subtracting) a random time may be risky if  the
	   stamp  takes	 less  than  the added time to arrive as the recipient
	   will	reject stamps with time	stamps in the future.

       -n  Print resource name parsed from stamp being verified.  Returns exit
	   code	unchecked on exit.

       -l  Print number	of seconds left	before stamp  expires.	 Returns  exit
	   code	unchecked on exit.

	   Note:  the calculation includes the grace period, so	can be up to 2
	   times grace period longer than you might  otherwise	expect	(clock
	   fast	 but  system has to presume it could be	slow).	If you want to
	   exclude the grace period add	-g0 to set grace period	to 0  for  the
	   calculation.

       -w  Print  number  of  bits  of	preimage  of stamp.  Returns exit code
	   unchecked on	exit.

       -y  Returns success if the stamp	is valid  even	if  it	is  not	 fully
	   checked.   Use with -c where	not all	of -d, -r are specified	to get
	   success exit	code on	valid but partially checked stamp.   Similarly
	   can use with	-n, -l,	-w with	same effect.

       -M  When	 checking  stamps,  allow  wildcard * matching in the resource
	   name	to make	it simpler to specify multiple email addresses and  to
	   allow  matching  catch-all addresses	and addresses including	subdo-
	   mains.  This	is the default.	 See also -S, -E and -C

       -S  When	checking stamps	use simple text	compare	 to  compare  resource
	   names to those in stamps.  See also -M, -E and -C.

       -E  When	 checking  stamps  use regular expressions to specify resource
	   names to make it  simpler  to  specify  multiple  email  addresses,
	   catch-all  addresses,  classes of extension addresses and addresses
	   including subdomains.  Note	regular	 expression  syntax  is	 POSIX
	   style:  special  characters	do not need to be quoted to have their
	   special meaning; but	they do	have to	be quoted with \ to that char-
	   acter in the	searched string.  The regular expression automatically
	   has ^ added at the beginning	and $ added at the end,	 if  they  are
	   not	specified.   The special characters ^ matches the beginning of
	   the resouce,	and $ matches the end of resource.

	   (Note even if compiled with BSD regular  expressions,  POSIX	 style
	   syntax  is  used;  also note	BSD regular expressions	do not support
	   ranges {}.)

       -C  By default resources	are canonicalized to lower case	on minting and
	   on checking.	 The -C	flag overrides	this  so  that	resources  are
	   treated  as	case  sensitive	 on checking, and not canonizalized on
	   minting.

       -P  Print progress info (number	of  iterations,	 expected  iterations,
	   percentage done, best stamp size found so far).

       -O core
	   Select  hashcash  core  with	 that number.  Currently 0-9 are valid
	   cores.  Not all cores work on all architectures.  Eg	some  are  x86
	   specific  assembler,	 others	 PPC specific assembler.  If a core is
	   not valid hashcash returns failure and explains what	happened.

       -Z n
	   Compress the	stamp.	This is	a time vs  space  trade	 off.	Larger
	   stamps  are faster, but arguably slightly ugly.  For	fastest	stamps
	   (the	default) use -Z	0; for partly compressed stamps	use -Z 1;  for
	   very	 compressed, but somewhat slow stamps use -Z 2.	 (Note:	due to
	   a late discovered bug, -Z2 is the same as -Z1 for now until	I  can
	   fix that.)

EXAMPLES
       Creating	stamps

       "hashcash -s"
	   Print  timing  information about how	many preimages the machine can
	   try per second.

       "hashcash -sv"
	   More	accurate but quite slow	benchmarking  of  different  processor
	   specific minting cores.

       "hashcash -s -b default"
	   Print how long it would take	the machine to compute a default sized
	   preimage (but don't actually	compute	a preimage).

       "hashcash -s -b 32"
	   Print how long it would take	the machine to compute a 32 bit	preim-
	   age (but don't actually compute a preimage).

       "hashcash -m"
	   Mint	 a stamp.  Will	prompt for resource name and mint with default
	   value (number of preimage bits).

       "hashcash -m foo"
	   Compute preimage on resource	foo.  Will  mint  with	default	 value
	   (number of preimage bits).

       "hashcash -m foo	-b 10"
	   Compute 10 bit preimage on resource foo.

       "hashcash -a -3d"
	   Subtract  a	random	time  of  between  0  days and 3 days from the
	   stamp's creation time.  This	is the same fuzz factor	used  by  mix-
	   master to reduce risk of timing-correlations.

       Examining Stamps

       "hashcash -w 1:24:040806:foo::511801694b4cd6b0:1e7297a"
	   Report  the	value  of  the stamp (how many bits of preimage) there
	   are.	 The example is	a 24 bit preimage, which takes on  average  25
	   seconds to create on	a 3Ghz P4.

       "hashcash -mq -b	10 foo | hashcash -w"
	   Create  a stamp in batch mode, pass to hashcash on stdin to verify,
	   have	it print how many bits there were.

       "hashcash -n 1:24:040806:foo::511801694b4cd6b0:1e7297a"
	   Report the resource name from the stamp.  The resource name in  the
	   example is foo.

       "hashcash -l -e 30y 1:24:040806:foo::511801694b4cd6b0:1e7297a"
	   Report  how	long until the stamp expires if	it expires in 30 years
	   from	its creation date.  (Note dates	too far	into  the  future  run
	   into	 the  2038  end	of Epoch, which	is the unix time analog	of the
	   y2k bug).

       Verifying Stamps

       "hashcash -c 1:24:040806:foo::511801694b4cd6b0:1e7297a"
	   Check if the	stamp is valid.	 Note as we are	not checking the stamp
	   in a	double spend database, and did not specify a resource name  or
	   required  number of bits of preimage	and hashcash will consider the
	   stamp not fully checked, and	it will	report it  as  valid  but  not
	   fully  unchecked,  or  as  invalid if there is any problem with the
	   stamp.

       "hashcash -c -b24 1:24:040806:foo::511801694b4cd6b0:1e7297a"
	   Check that the value	of the stamp is	greater	or equal to  24	 bits.
	   This	 example has 24	bit value.  If you increase the	requested num-
	   ber of bits or replace the stamp with one with  less	 than  24  bit
	   preimage the	stamp will be rejected.

       "hashcash -c -b24 -r foo	1:24:040806:foo::511801694b4cd6b0:1e7297a"
	   As  above  check if the stamp has sufficient	value, but in addition
	   check that the resource name	given matches the resource name	in the
	   stamp.

       Double Spending Prevention

       The examples given in "Verifying	Stamps"	can be modified	to keep	a dou-
       ble spend database so that the same stamp will not be  accepted	twice.
       Note a stamp will only be checked in and	added to the database if it is
       otherwise  valid	and fully checked (a required number of	bits of	preim-
       age has been specified and a resource has been specified).

       "hashcash -cd -b	10 -r foo 1:24:040806:foo::511801694b4cd6b0:1e7297a"
	   Check the stamp and add to double spent database if it's valid (has
	   correct resource name and sufficient	value).

       "hashcash -cd -b	10 -r foo 1:24:040806:foo::511801694b4cd6b0:1e7297a"
	   Try to double spend the stamp.   It	will  be  rejected  as	double
	   spent.

       Stamp Expiry

       To  prevent the double spend database growing indefinately, the recipi-
       ent can request that stamps be no older than a specified	period.	 After
       expiry old stamps can dropped from the double spend  database  as  they
       will no longer be needed	-- expired stamps can be rejected based	purely
       on  their  old date, so the space taken by expired stamps in the	double
       spend database can be saved without risk	of accepting an	expired	though
       otherwise valid stamp.

       The third field of the stamp is the UTC time since  1st	January	 1970.
       The  default  time  format  is YYMMDD, time rounded down	to the nearest
       day.  The default validity period is 28 days.

       You can provide an alternative validity period with the -e option.

       "hashcash -cd -b	10 -e 2d -r foo
       1:24:040806:foo::511801694b4cd6b0:1e7297a"
	   Try verifying an old	stamp, the above  stamp	 was  created  11  Aug
	   2002.

	   We gave option -e 2d	so the stamps expiry date is 2 days after cre-
	   ation, which	is now in the past.

	   Note:  if  the creation time	is expressed in	the stamp in days, the
	   precise creation date is the	begining of the	specified day  in  UTC
	   time	 (similarly  for  alternate units the creation time is rounded
	   down	to the begining	of the unit it is expressed in).  For units in
	   days, for example, this may mean depending on your time  zone  that
	   the	stamp  appears to be considered	invalid	in under the specified
	   expiry period in days relative to your relative view	of what	day it
	   is, as the calculation is based on current time  in	UTC,  and  the
	   creation time of the	stamp is expressed in UTC time.

       "hashcash -cd -b	10 -r foo 1:24:040806:foo::511801694b4cd6b0:1e7297a"
	   Test	 whether  the  stamp is	otherwise valid, apart from having ex-
	   pired.  Omitting the	-e tells hashcash that the  stamp  will	 never
	   expire.   An	 expiry	 period	 of forever can	also be	given explitly
	   like	this: -e 0, where an expiry period of 0	means forever.

       Purging old stamps

       If the -c, -d options are used together,	each time a stamp is  checked,
       if  it is valid and all of the mandatory	aspects	of the stamp are veri-
       fied (preimage bits check, resource name	check) then the	stamp and  its
       expiry  period is written to the	database file.	The default expiry pe-
       riod if an expiry period	is not given explicitly	with the -e option  is
       28 days (ie stamps expire after 4 weeks).

       First mint and then add a stamp:

       "hashcash -m -b 10 foo -e 1m > stamp"
	   Note:  we specified an expiry on minting in this example, to	ensure
	   that	the stamp creation time	is given in high enough	resolution  in
	   the	stamp that the stamp will not be considered expired at time of
	   creation.  (Recall the default resolution is	in days, a stamp  cre-
	   ated	 with a	creation time rounded down to the beginging of the day
	   is unlikely to be considered	valid 1	minute later unless  you  mint
	   it at midnight UTC time.)

       "hashcash -cd -e	1m -b 10 -r foo	< stamp"
	   The	stamp  expires in 1 minute.  Wait 1 minute and then explicitly
	   request that	expired	stamps be purged:

       "hashcash -p now"
	   Then	try resubmitting the same stamp:

       "hashcash -cd -e	1m -b 10 -r foo	< stamp"
	   and the stamp will be rejected anyway as it has expired, illustrat-
	   ing why it was not necessary	to keep	this stamp in the database.

	   With	the default database (the sdb format)  the  database  contents
	   are	human  readable, so you	can view their contents	by cating them
	   to the terminal:

       "cat hashcash.sdb"
	   to see that the stamp really	is added and then after	puring	subse-
	   quently purged due to expiry.

       Purging old stamps on Demand

       As  a  convenience you can purge	at the same time as checking stamps by
       using the -p option with	the -c option.

       "hashcash -m -b 10 foo >	stamp"
       "hashcash -cd -p	now -e 1 -b 10 -r foo <	stamp"
	   It may be inefficient to purge stamps on every use  as  the	entire
	   database  has  to  be scanned for expired stamps.  By giving	a time
	   period to the -p option, you	can tell "hashcash" to purge  no  more
	   frequently than that	time period since the previous purge.

	   For example:

       "hashcash -cd -p	1d -e 1	-b 10 -r foo < stamp"
	   tells  "hashcash" to	purge any expired stamps no more than once per
	   day.

       "hashcash -p 1M -j foo"
	   tells "hashcash" to purge only expired stamps matching resource foo
	   once	per month.

       "hashcash -p now	-k"
	   tells "hashcash" to purge all stamps	(expired and unexpired)	now.

stamp format (version 1)
       The current stamp format	is version 1.  This tool can  verify  hashcash
       version	0  stamps  also, but version 0 stamps are no longer created as
       they are	being phased out in favor of the more extensible v1 stamp for-
       mat.

       ver:bits:date:resource:[ext]:rand:counter

       where

       ver = 1
       bits = how many bits of partial-preimage	the stamp is claimed to	have
       date = YYMMDD[hhmm[ss]]
       resource	= resource string (eg IP address, email	address)
       ext = extension -- ignored in the current version
	   Format of extension:

	   [name1[=val1[,val2...]];[name2[=val1[,val2...]]...]]
	       Note the	value can also contain =.  Example  extension  (not  a
	       real one):

		       name1=2,3;name2;name3=var1=2,var2=3,2,val

	       Which  would  be	 extension name1 has values 2 and 3; extension
	       name2 has no values; extension name3  has  3  values  "var1=2",
	       "var2=3",  "2" and "val".  The hashcash extension may interpret
	       the values as it	sees fit eg "var1=2" could be the value	of  an
	       option to the extension name3.

       rand = string of	random characters from alphabet	a-zA-Z0-9+/= to	avoid
       preimage	with other sender's stamps
       counter = to find a stamp with the desired number of preimage bits need
       to try lots of different	strings	this counter is	incremented on each
       try. The	Counter	is also	composed of characters from the	alphabet
       a-zA-Z0-9+/=.  (Note an implementation is not required to count sequen-
       tially).

FILES
       hashcash.sdb
	   default double spend	database

EXIT STATUS
       "hashcash"  returns  success (exit code 0) after	successfully minting a
       stamp, after fully checking a stamp and finding it valid, and  after  a
       timing test.

       If  when	 checking a stamp it is	found to be invalid (due to being mal-
       formed, being expired, having insufficient value, having	a date in  the
       future,	or  being double spent), "hashcash" returns failure (exit code
       1).

       If insufficient options are given to fully check	a stamp, if the	 stamp
       is  otherwise  valid return unchecked (exit code	2).  If	the -y flag is
       given and hashcash would	normally return	unchecked, exit	 code  success
       is returned instead.

       If  any	exception  occurs  (file read failure for database checking or
       corrupted database contents) an exit status of 3	is returned.

AUTHOR
       Written by Adam Back <adam@cypherspace.org>

SEE ALSO
       sha1sum(1), sha1-hashcash(1), sha1(1), http://www.hashcash.org/

1.22				  2006-04-07			   HASHCASH(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=hashcash&sektion=1&manpath=FreeBSD+Ports+15.0>

home | help