From ab947bd58280637e7dbef44c983b6a27f6e7637b Mon Sep 17 00:00:00 2001 From: sfan5 Date: Mon, 27 Nov 2017 18:00:30 +0100 Subject: 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. --- doc/lua_api.txt | 79 +++++++++++++++++++++++++++++++++++++++------------------ 1 file 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=, privileges=, last_login=}` + 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 + } + -- cgit v1.2.3