mirror of
https://github.com/minetest/minetest.git
synced 2024-08-18 20:44:16 +02:00
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:
parent
36838ea22f
commit
ab947bd582
@ -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
|
||||
}
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user