extra/totp/totp-docs.factor

   1 ! Copyright (C) 2018, 2020 Alexander Ilin.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: byte-arrays calendar checksums checksums.sha help.markup
   4 help.syntax kernel math strings ;
   5 IN: totp
   6
   7 ABOUT: "totp"
   8
   9 ARTICLE: "totp" "Time-Based One-Time Passwords"
  10 "The " { $vocab-link "totp" } " vocab implements time-based one-time password generation as described in RFC 6238 (" { $url "https://tools.ietf.org/html/rfc6238" } ")."
  11 $nl
  12 "The idea is that a client is able to prove its identity to a server by submitting a password that is only valid for a short period of time. The password needs to be sent via a secure channel inside that time period, and client and server must have a shared secret established in advance. The TOTP protocol uses the number of whole 30-second intervals passed in Unix time as a counter value, which it authenticates with an HMAC and converts into a string of " { $link digits } ". Client and server must use the same secret key, the same hash for the HMAC, the same time reference point (not necessarily Unix time) and the same time interval length for the counter. The string of digits used as the password should be long enough to balance convenience and brute-force attack resistance. For 30-second intervals 6 or more digits are typically used."
  13 $nl
  14 "Both client and server are able to generate exactly the same digits from the shared secret using their current time as the counter. Server can be programmed to accept values from the adjacent time slots, so that time drift and network delays are compensated for, though that somewhat weakens the system."
  15 $nl
  16 "Simple high-level interface:"
  17 { $subsections totp-hash totp-digits totp }
  18 "Customizable implementation:"
  19 { $subsections timestamp>count* totp* digits }
  20 ;
  21
  22 HELP: totp-hash
  23 { $var-description "A cryptographically secure " { $link checksum } " to be used by " { $link totp } " for the HMAC. See " { $url "https://en.wikipedia.org/wiki/HMAC" } " for more information."
  24 $nl
  25 "Default value is " { $link sha1 } ", same as used by Google Authenticator." } ;
  26
  27 HELP: totp-digits
  28 { $var-description "The number of digits returned by " { $link totp } "."
  29 $nl
  30 "Default value is 6." } ;
  31
  32 HELP: totp
  33 { $values
  34     { "key" object }
  35     { "string" string }
  36 }
  37 { $description "Generate a one-time password for the " { $snippet "key" } " based on the current system time. If " { $snippet "key" } " is a " { $link string } ", it is expected to contain the key data in Base 32 encoding, otherwise it should be a " { $link byte-array } ". The " { $snippet "string" } " length is " { $link totp-digits } ", and the hash used for HMAC is " { $link totp-hash } "." } ;
  38
  39 { totp totp* } related-words
  40
  41 HELP: timestamp>count
  42 { $values
  43     { "timestamp" timestamp }
  44     { "count" byte-array }
  45 }
  46 { $description "Return the number of 30-second intervals between the Unix time and the " { $snippet "timestamp" } " as an 8-byte " { $link byte-array } "." } ;
  47
  48 HELP: timestamp>count*
  49 { $values
  50     { "timestamp" timestamp } { "secs/count" number }
  51     { "count" byte-array }
  52 }
  53 { $description "Return the number of " { $snippet "secs/count" } "-second intervals between the Unix time and the " { $snippet "timestamp" } " as an 8-byte " { $link byte-array } "." } ;
  54
  55 { timestamp>count timestamp>count* } related-words
  56
  57 HELP: totp*
  58 { $values
  59     { "count" "a number of time intervals elapsed since a fixed time point" }
  60     { "key" "a secret key shared between the client and the server" }
  61     { "hash" checksum }
  62     { "n" fixnum }
  63 }
  64 { $description "This is a fully customizable version of " { $link totp } ". To convert a " { $link timestamp } " into the " { $snippet "count" } " value, use " { $link timestamp>count } ". " { $snippet "n" } " is a positive 31-bit integer. To convert the returned value into a string of a predetermined length, use " { $link digits } "." } ;
  65
  66 HELP: digits
  67 { $values
  68     { "n" number } { "digits" number }
  69     { "string" string }
  70 }
  71 { $description "Convert integer " { $snippet "n" } " into a decimal string of length " { $snippet "digits" } ", padding with zeroes on the left if necessary. If the string representation of " { $snippet "n" } " is longer than " { $snippet "digits" } ", return the rightmost part of the requested length." } ;