extra/hashcash/hashcash-docs.factor

   1 ! Copyright (C) 2022 Zoltán Kéri.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: hashcash.private help.markup help.syntax kernel math
   4 random.passwords strings ;
   5 IN: hashcash
   6
   7 ARTICLE: "hashcash" "Hashcash"
   8 "Hashcash is an anti-spam / denial of service counter-measure tool."
   9 $nl
  10 "A hashcash stamp constitutes a proof-of-work which takes a parameterizable amount of work to compute for the sender. The recipient (and indeed anyone as it is publicly auditable) can verify received hashcash stamps efficiently."
  11 $nl
  12 "E-mail senders attach hashcash stamps with the " { $snippet X-Hashcash } " header. Vendors and authors of anti-spam tools are encouraged to exempt e-mail sent with hashcash from their blacklists and content-based filtering rules."
  13 $nl
  14 "This library provides basic utilities for hashcash creation and validation."
  15 $nl
  16 { $subheading "Creating stamps" }
  17 { $subsections
  18   mint
  19   mint*
  20 }
  21 { $subheading "Validation" }
  22 { $subsections
  23   valid-stamp?
  24   valid-date?
  25 }
  26 { $subheading "Hashcash tuple and constructor" }
  27 { $subsections
  28   hashcash
  29   <hashcash>
  30   expiry-days
  31 }
  32 { $subheading "Private utilities" }
  33 { $subsections
  34   on-or-before-today?
  35   now-gmt-yymmdd
  36   yymmdd-gmt-diff
  37   yymmdd-gmt>timestamp
  38   timestamp>yymmdd
  39   lastn-digits
  40 }
  41 { $see-also ascii-password }
  42 { $heading "Further readings" }
  43 { $url "https://en.wikipedia.org/wiki/Hashcash" } $nl
  44 { $url "http://www.hashcash.org/" } $nl
  45 { $url "http://www.hashcash.org/papers/hashcash.pdf" } $nl
  46 { $url "https://dbpedia.org/page/Hashcash" } $nl
  47 { $url "https://nakamoto.com/hashcash/" } ;
  48
  49 HELP: mint
  50 { $values { "resource" string } { "stamp" "generated stamp" } }
  51 { $description "This word generates a valid stamp with default parameters and the specified resource." }
  52 { $examples
  53   { $subheading "Generate a valid stamp" }
  54   "The value " { $snippet "foo@bar.com" } " represents the resource string. "
  55   "The generated stamp is pushed on the data stack." }
  56 { $unchecked-example
  57   "USING: hashcash ;"
  58   "\"foo@bar.com\" mint"
  59   "\n--- Data stack:\n1:20:220401:foo@bar.com::^Xt'xHT;:1eab9d"
  60 }
  61 "Generated stamp tabulated for better readability:"
  62 { $slots
  63   { { $slot "version" } { $snippet "1" } }
  64   { { $slot "bits" } { $snippet "20" } }
  65   { { $slot "date" } { $snippet "220401" } }
  66   { { $slot "resource" } { $snippet "foo@bar.com" } }
  67   { { $slot "salt" } { $snippet "^Xt'xHT;:1eab9d" } }
  68 }
  69 { $notes "Examples of common resource strings:"
  70   { $list
  71     { "IP address" }
  72     { "E-mail address" }
  73   }
  74 } ;
  75
  76 HELP: mint*
  77 { $values { "tuple" "a tuple" } { "stamp" "generated stamp" } }
  78 { $description "As " { $snippet "mint" } " but it takes a hashcash tuple as a parameter." } ;
  79
  80 HELP: hashcash
  81 { $class-description "A hashcash object. A hashcash have the following slots:"
  82   { $slots
  83     { { $slot "version" } "The version number. Only version 1 is supported." }
  84     { { $slot "bits" } "The claimed bit value." }
  85     { { $slot "date" } { "The date on which a stamp was minted. Expiry time is 28 days by default. See " { $link valid-stamp? } " for more." } }
  86     { { $slot "resource" } "The resource string for which a stamp is minted." }
  87     { { $slot "ext" } "Extensions that a specialized application may want. Ignored in version 1 (?)." }
  88     { { $slot "salt" } { "A random salt generated with " { $link ascii-password } "." } }
  89     { { $slot "suffix" } "The computed suffix. This is supposed to be manipulated by the library." }
  90   }
  91 } ;
  92
  93 HELP: <hashcash>
  94 { $values { "tuple" object } }
  95 { $description "It fills a hashcash tuple with the default values: " { $snippet 1 } " as hashcash version, " { $snippet 20 } " as bits, " { $snippet "today's date" } " as date, and a " { $snippet "8-character long random string" } " as salt." } ;
  96
  97 HELP: valid-stamp?
  98 { $values { "stamp" string } { "?" boolean } }
  99 { $description "Verify the stamp's validity. Only supports hashcash version 1. Expiry time / validity period is 28 days by default as it is the recommended value."
 100   $nl
 101   "The decision about how long the stamp should be considered valid is up to the verifier. If it is too short, then it is possible for some applications that the stamp will expire before arriving at the recipient (e.g. with e-mail). The suggested value of 28 days should be safe for normal e-mail delivery delays. The choice is a trade-off between database size and risk of expiry prior to arrival, and depends on the application."
 102   $nl
 103   "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." }
 104 $nl
 105 { "You can obtain the current value by executing the following line of code: " }
 106 { $code "expiry-days get" }
 107 { "You can modify the expiry time by modifying the value of the symbol " { $snippet "expiry-days" } "." }
 108 { $code "32 expiry-days set" }
 109 { "This changes the expiry period to 32 days." }
 110 { $examples
 111   { $example
 112     "USING: hashcash ;"
 113     "\"foo@bar.com\" mint valid-stamp?"
 114     "\n--- Data stack:\nt"
 115   }
 116 } ;