From: paulr Date: Mon, 22 Nov 2010 14:23:03 +0000 (+1100) Subject: added a funcitonal reference... X-Git-Url: http://git.pjr.cc/?p=ga4php.git;a=commitdiff_plain;h=aca6e69a5eaa260bf6a7f676f31e43dd8e1e6158 added a funcitonal reference... is there such a thing as phpdoc thats like java doc i wonder? --- diff --git a/doco/functional_reference.txt b/doco/functional_reference.txt new file mode 100644 index 0000000..5b79467 --- /dev/null +++ b/doco/functional_reference.txt @@ -0,0 +1,100 @@ +The following text describes each method in the ga4php class + +These are the abstract classes you must define when subclassing that are +needed for the class to function. One gets the data associated with $username +one puts the data assocaiate with $username and the other gets a list of users +as an array. $data is simply a base64 encoded string and never very long, no more +then 1k. However, there is a user data area so the size of the data in the $data +segment is dependant on what you use it for. + abstract function getData($username); + abstract function putData($username, $data); + abstract function getUsers(); + + +The cunstructor of the base class. The default values are usually fine, totpskew +is the value of keys either side of the current time key (i.e. +/- 1 counter value) +hotpskew is how many tokens in advance of the last "seen" token that are checked +and hotphuntvalue is the number of tokens (from 0) the class looks ahead trying +to find where the users token currently is in the advent of a token resync + function __construct($totpskew=1, $hotpskew=10, $hotphuntvalue=200000) + +A simple funciton that returns an empty data structure (which is a "token") as +used internally to the class (it has an array member called "user" which you +can store your own data in. + function createEmptyData() + +A function used internally whenever the class needs to retrieve the users data +structure from the underlying storage. Your getData() function is called by this +function to get its encoded data structure + function internalGetData($username) + +A function used internall whenever the class needs to store the user data structure +into the underlying storage. Your putData() function defines how the $data segment +is stored. + function internalPutData($username, $data) + +A function to set the token type for a given user. Typically you might call this +method if you are manually setting up a token for a user that is using a non-google +authenticator or a hardware token. + function setTokenType($username, $tokentype) + +A function to directly set a users key. Again, typically you'll call this if you +are setting up the user for a non-GA style token, such as a hardware token or a +non-ga software token. + function setUserKey($username, $key) + + +This is the most important function, you call this to setup a user. with no +arguments other then the username, the class will simply provision the user +as an 80-bit HOTP token (as per the GA token) and creata random key. The key +is returned. + function setUser($username, $ttype="HOTP", $key = "", $hexkey="") + +A function which simply tests if the user has a token. + function hasToken($username) + +A function to delete a user, it simply nulls off the data segment of a user. + function deleteUser($username) + +The other most important function of the class. You call this as $username and the +code the user has entered. Returns true if it was the correct code (or falls within +the limits) or false if the user got it wrong. + function authenticateUser($username, $code) + +This function is called to resync a HOTP token. The class keeps track of the counter +for the last used token key, so if the last token the user has entered was counter no +23, it will (by default) look for a token key value from 23-43. If a user presses their +"generate code" button (same for hardware tokens) more then 20 times without authenticating +(such as people playing with their token) the token will fail to authenticate and the +user must "resync" their token with the following code + function resyncCode($username, $code1, $code2) + +A function to return an error string when an error occurs - not fully implemented + function getErrorText() + +A function which generates a url that can be used with a QRcode and scanned in with the +google authenticator. You must generate the qrcode, its not done in the class. + function createURL($user) + +A function that generates a random 80-bit base32 key (as used by the google authenticator) + function createBase32Key() + +A function that returns the key IN HEX of the user. + function getKey($username) + +A function that returns the token type for a given user. + function getTokenType($username) + + +A method that turns a base32 key into a hex key - use with caution + function helperb322hex($b32) + +A method that turns a hex key into a base32 one - use with caution + function helperhex2b32($hex) + +A method that generates the $counter'th hotp/totp key for a given token key value + function oath_hotp($key, $counter) + +A method that truncates the output of oath_hotp to $length as per the token requirements + function oath_truncate($hash, $length = 6) + diff --git a/lib/ga4php.php b/lib/ga4php.php index 0645657..2be25ff 100644 --- a/lib/ga4php.php +++ b/lib/ga4php.php @@ -19,6 +19,8 @@ abstract class GoogleAuthenticator { $this->hotpHuntValue = $hotphuntvalue; } + // pure abstract functions that need to be overloaded when + // creating a sub class abstract function getData($username); abstract function putData($username, $data); abstract function getUsers(); @@ -30,12 +32,13 @@ abstract class GoogleAuthenticator { $data["tokentimer"] = 30; // the token timer (For totp) and not supported by ga yet $data["tokencounter"] = 1; // the token counter for hotp $data["tokenalgorithm"] = "SHA1"; // the token algorithm (not supported by ga yet) - $data["user1"] = ""; // a place for implementors to store their own data + $data["user"] = ""; // a place for implementors to store their own data return $data; } - // an internal funciton to get + // an internal funciton to get data from the overloaded functions + // and turn them into php arrays. function internalGetData($username) { $data = $this->getData($username); $deco = unserialize(base64_decode($data)); @@ -47,7 +50,8 @@ abstract class GoogleAuthenticator { return $deco; } - + // the function used inside the class to put the data into the + // datastore using the overloaded data saving class function internalPutData($username, $data) { $enco = base64_encode(serialize($data)); @@ -60,7 +64,7 @@ abstract class GoogleAuthenticator { // so lets not be able to set that yet function setTokenType($username, $tokentype) { $tokentype = strtoupper($tokentype); - if($tokentype!="HOTP" and $tokentype!="TOTP") { + if($tokentype!="HOTP" && $tokentype!="TOTP") { $errorText = "Invalid Token Type"; return false; } @@ -74,6 +78,8 @@ abstract class GoogleAuthenticator { // create "user" with insert function setUser($username, $ttype="HOTP", $key = "", $hexkey="") { + $ttype = strtoupper($ttype); + if($ttype != "HOTP" && $ttype !="TOTP") return false; if($key == "") $key = $this->createBase32Key(); $hkey = $this->helperb322hex($key); if($hexkey != "") $hkey = $hexkey; @@ -88,7 +94,7 @@ abstract class GoogleAuthenticator { return $key; } - + // a function to determine if the user has an actual token function hasToken($username) { $token = $this->internalGetData($username); // TODO: change this to a pattern match for an actual key