doco/functional_reference.txt

   1 The following text describes each method in the ga4php class
   2
   3 These are the abstract classes you must define when subclassing that are
   4 needed for the class to function. One gets the data associated with $username
   5 one puts the data assocaiate with $username and the other gets a list of users
   6 as an array. $data is simply a base64 encoded string and never very long, no more
   7 then 1k. However, there is a user data area so the size of the data in the $data
   8 segment is dependant on what you use it for.
   9         abstract function getData($username);
  10         abstract function putData($username, $data);
  11         abstract function getUsers();
  12
  13
  14 The cunstructor of the base class. The default values are usually fine, totpskew
  15 is the value of keys either side of the current time key (i.e. +/- 1 counter value)
  16 hotpskew is how many tokens in advance of the last "seen" token that are checked
  17 and hotphuntvalue is the number of tokens (from 0) the class looks ahead trying
  18 to find where the users token currently is in the advent of a token resync
  19         function __construct($totpskew=1, $hotpskew=10, $hotphuntvalue=200000)
  20
  21 A simple funciton that returns an empty data structure (which is a "token") as
  22 used internally to the class (it has an array member called "user" which you
  23 can store your own data in.
  24         function createEmptyData()
  25
  26 A function used internally whenever the class needs to retrieve the users data
  27 structure from the underlying storage. Your getData() function is called by this
  28 function to get its encoded data structure
  29         function internalGetData($username)
  30
  31 A function used internall whenever the class needs to store the user data structure
  32 into the underlying storage. Your putData() function defines how the $data segment
  33 is stored.
  34         function internalPutData($username, $data)
  35
  36 A function to set the token type for a given user. Typically you might call this
  37 method if you are manually setting up a token for a user that is using a non-google
  38 authenticator or a hardware token.
  39         function setTokenType($username, $tokentype)
  40
  41 A function to directly set a users key. Again, typically you'll call this if you
  42 are setting up the user for a non-GA style token, such as a hardware token or a
  43 non-ga software token.
  44         function setUserKey($username, $key)
  45
  46
  47 This is the most important function, you call this to setup a user. with no
  48 arguments other then the username, the class will simply provision the user
  49 as an 80-bit HOTP token (as per the GA token) and creata random key. The key
  50 is returned.
  51         function setUser($username, $ttype="HOTP", $key = "", $hexkey="")
  52
  53 A function which simply tests if the user has a token.
  54         function hasToken($username)
  55
  56 A function to delete a user, it simply nulls off the data segment of a user.
  57         function deleteUser($username)
  58
  59 The other most important function of the class. You call this as $username and the
  60 code the user has entered. Returns true if it was the correct code (or falls within
  61 the limits) or false if the user got it wrong.
  62         function authenticateUser($username, $code)
  63
  64 This function is called to resync a HOTP token. The class keeps track of the counter
  65 for the last used token key, so if the last token the user has entered was counter no
  66 23, it will (by default) look for a token key value from 23-43. If a user presses their
  67 "generate code" button (same for hardware tokens) more then 20 times without authenticating
  68 (such as people playing with their token) the token will fail to authenticate and the
  69 user must "resync" their token with the following code
  70         function resyncCode($username, $code1, $code2)
  71
  72 A function to return an error string when an error occurs - not fully implemented
  73         function getErrorText()
  74
  75 A function which generates a url that can be used with a QRcode and scanned in with the
  76 google authenticator. You must generate the qrcode, its not done in the class.
  77         function createURL($user)
  78
  79 A function that generates a random 80-bit base32 key (as used by the google authenticator)
  80         function createBase32Key()
  81
  82 A function that returns the key IN HEX of the user.
  83         function getKey($username)
  84
  85 A function that returns the token type for a given user.
  86         function getTokenType($username)
  87
  88
  89 A method that turns a base32 key into a hex key - use with caution
  90         function helperb322hex($b32)
  91
  92 A method that turns a hex key into a base32 one - use with caution
  93         function helperhex2b32($hex)
  94
  95 A method that generates the $counter'th hotp/totp key for a given token key value
  96         function oath_hotp($key, $counter)
  97
  98 A method that truncates the output of oath_hotp to $length as per the token requirements
  99         function oath_truncate($hash, $length = 6)
 100