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.
This commit is contained in:
sfan5 2017-11-27 18:00:30 +01:00 committed by SmallJoker
parent 7cc1a36b3c
commit 7d9dbbbf3c

@ -2460,8 +2460,9 @@ Call these functions only at load time!
* `definition`: `{ description = "description text", give_to_singleplayer = boolean}`
the default of `give_to_singleplayer` is true
* To allow players with `basic_privs` to grant, see `basic_privs` minetest.conf setting.
* `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
@ -2470,37 +2471,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.
* To report everybody, set `name=nil`.
* `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
* `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.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 authetification handler.
@ -4792,3 +4800,26 @@ The Biome API is still in an experimental phase and subject to change.
-- ^ 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
}