Update documentation regarding authentication handler and related functions

Properly document it instead of referencing the builtin handler as
authoritative "example" code.
Also adds definition of get_auth_handler() which was missing previously.

1 files changed, 55 insertions, 24 deletions

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index ae0287c43..08527c196 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -2643,8 +2643,9 @@ Call these functions only at load time!
     * Note that the above two callbacks will be called twice if a player is responsible -
       once with the player name, and then with a nil player name.
     * Return true in the above callbacks to stop register_on_priv_grant or revoke being called.
-* `minetest.register_authentication_handler(handler)`
-    * See `minetest.builtin_auth_handler` in `builtin.lua` for reference
+* `minetest.register_authentication_handler(authentication handler definition)`
+    * Registers an auth handler that overrides the builtin one
+    * This function can be called by a single mod once only.
 
 ### Setting-related
 * `minetest.settings`: Settings object containing all of the settings from the
@@ -2653,37 +2654,44 @@ Call these functions only at load time!
   parses it as a position (in the format `(1,2,3)`). Returns a position or nil.
 
 ### Authentication
-* `minetest.notify_authentication_modified(name)`
-    * Should be called by the authentication handler if privileges changes.
-    * `name`: string, if omitted, everybody is reported
-* `minetest.check_password_entry(name, entry, password)`
-    * Returns true if the "db entry" for a player with name matches given
-    * password, false otherwise.
-    * The "db entry" is the usually player-individual value that is derived
-    * from the player's chosen password and stored on the server in order to allow
-    * authentication whenever the player desires to log in.
-    * Only use this function for making it possible to log in via the password from
-    * via protocols like IRC, other uses for inside the game are frowned upon.
-* `minetest.get_password_hash(name, raw_password)`
-    * Convert a name-password pair to a password hash that Minetest can use.
-    * The returned value alone is not a good basis for password checks based
-    * on comparing the password hash in the database with the password hash
-    * from the function, with an externally provided password, as the hash
-    * in the db might use the new SRP verifier format.
-    * For this purpose, use `minetest.check_password_entry` instead.
 * `minetest.string_to_privs(str)`: returns `{priv1=true,...}`
 * `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."`
     * Convert between two privilege representations
-* `minetest.set_player_password(name, password_hash)`
-* `minetest.set_player_privs(name, {priv1=true,...})`
 * `minetest.get_player_privs(name) -> {priv1=true,...}`
-* `minetest.auth_reload()`
 * `minetest.check_player_privs(player_or_name, ...)`: returns `bool, missing_privs`
     * A quickhand for checking privileges.
     * `player_or_name`: Either a Player object or the name of a player.
     * `...` is either a list of strings, e.g. `"priva", "privb"` or
       a table, e.g. `{ priva = true, privb = true }`.
-* `minetest.get_player_ip(name)`: returns an IP address string
+
+* `minetest.check_password_entry(name, entry, password)`
+    * Returns true if the "password entry" for a player with name matches given
+      password, false otherwise.
+    * The "password entry" is the password representation generated by the engine
+      as returned as part of a `get_auth()` call on the auth handler.
+    * Only use this function for making it possible to log in via password from
+      external protocols such as IRC, other uses are frowned upon.
+* `minetest.get_password_hash(name, raw_password)`
+    * Convert a name-password pair to a password hash that Minetest can use.
+    * The returned value alone is not a good basis for password checks based
+      on comparing the password hash in the database with the password hash
+      from the function, with an externally provided password, as the hash
+      in the db might use the new SRP verifier format.
+    * For this purpose, use `minetest.check_password_entry` instead.
+* `minetest.get_player_ip(name)`: returns an IP address string for the player `name`
+    * The player needs to be online for this to be successful.
+
+* `minetest.get_auth_handler()`: Return the currently active auth handler
+    * See the `Authentication handler definition`
+    * Use this to e.g. get the authentication data for a player:
+      `local auth_data = minetest.get_auth_handler().get_auth(playername)`
+* `minetest.notify_authentication_modified(name)`
+    * Must be called by the authentication handler for privilege changes.
+    * `name`: string; if omitted, all auth data should be considered modified
+* `minetest.set_player_password(name, password_hash)`: Set password hash of player `name`
+* `minetest.set_player_privs(name, {priv1=true,...})`: Set privileges of player `name`
+* `minetest.auth_reload()`
+    * See `reload()` in authentication handler definition
 
 `minetest.set_player_password`, `minetest_set_player_privs`, `minetest_get_player_privs`
 and `minetest.auth_reload` call the authentication handler.
@@ -5202,3 +5210,26 @@ Definition tables
      -- ^ HTTP status code
         data = "response"
     }
+
+### Authentication handler definition
+
+    {
+        get_auth = func(name),
+    --  ^ Get authentication data for existing player `name` (`nil` if player doesn't exist)
+    --  ^ returns following structure `{password=<string>, privileges=<table>, last_login=<number or nil>}`
+        create_auth = func(name, password),
+    --  ^ Create new auth data for player `name`
+    --  ^ Note that `password` is not plain-text but an arbitrary representation decided by the engine
+        set_password = func(name, password),
+    --  ^ Set password of player `name` to `password`
+           Auth data should be created if not present
+        set_privileges = func(name, privileges),
+    --  ^ Set privileges of player `name`
+    --  ^ `privileges` is in table form, auth data should be created if not present
+        reload = func(),
+    --  ^ Reload authentication data from the storage location
+    --  ^ Returns boolean indicating success
+        record_login = func(name),
+    --  ^ Called when player joins, used for keeping track of last_login
+    }
+