X-Git-Url: http://git.pjr.cc/?p=ga4php.git;a=blobdiff_plain;f=doco%2Ffunctional_reference.txt;fp=doco%2Ffunctional_reference.txt;h=5b79467f87e3bde99fa75fbb7d2b1b275f61a6e2;hp=0000000000000000000000000000000000000000;hb=aca6e69a5eaa260bf6a7f676f31e43dd8e1e6158;hpb=2245953d256f03c5803faecf00a07b70d250a6fc

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)
+