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 exempt
    mail sent with hashcash from their blacklists and content based
    filtering rules.

    A hashcash stamp constitutes a proof-of-work which takes a
    parameterizable amount of work to compute for the sender. The recipient
    can verify received stamps efficiently. This package also includes a
    sha1 implementation which is equivalent in functionality to the sha1sum
    program available on some systems.

    The hashcash proof-of-work function is to compute partial hash preimages
    (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 resource,
    which would allow stamps to be reused across different resources, 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
    rejected 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
    rejected, and the program exits immediately. If the *-b* flag is not
    given, the stamp is checked to see if it is otherwise valid, but
    hashcash 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
    Protection". 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
    applications 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 database
    size and risk of expiry prior to arrival, and depends on the
    application.

    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
    period* 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
    separately using just the *-p now* option to request just the purge
    operation. 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
    results of stamp verification and timing are printed on stdout. The
    quiet flag *-q* suppresses all informational output. The *-v* flag
    requests 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 minimum
        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
        expressions (see *-E*), it is useful to be able to specify that one
        resource overrides another. For example this: *-b15 -r adam@dev.null
        -o -b10 *@dev.null* states that mail to address *adam@dev.null*
        requires 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*
        because 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 =
        minutes, h = hours, d = days, M = months, y = Y = years, and s =
        seconds).

        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
        resolution of time created in the stamp. Without the *-e* option,
        the default 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
        seconds.

        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
        combination with *-m* to specify an implicit time field width under
        the description of the *-e* flag. Valid widths are 6,10 or 12 chars
        corresponding 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
        hashcash 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 behind) 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
        default 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*
        option 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
        requested 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: '
        before 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
        format. 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 alternate
        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
        subdomains. 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 character 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
        preimage (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 mixmaster 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 number
        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
    double 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 preimage
    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 recipient
    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
        creation, 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
        expired. 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 verified (preimage bits check, resource name check) then the stamp
    and its expiry period is written to the database file. The default
    expiry period 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 created
        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,
        illustrating 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
        subsequently 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
    format.

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

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
    malformed, 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/

