Improvedocs

[merretbuurman]

Improving documentation on user authentication / user permissions. Addressing issue #60 .

[cookie33]

It adds:

Note: This setting gives admin permissions to users foo/bar and foo/doe. You should also make sure that those users
are not able to change other people's admin permissions. For this, make sure the ``HS_ADMIN`` of the handles concerned with
user administration points to a username or ``HS_VLIST`` that only you can access.
As an example, we add a ``HS_VLIST`` to the foo/admin handle that contains the admin's usernames (index 201). Only the users in this list
can administer users.

**Handle record 0.NA/foo:**

===== ========= =======================
Index Key       Value
...   ...       ...
100   HS_ADMIN  (refers to 200:0.NA/foo)
200   HS_VLIST  200:foo/admin
 ...  ...       ...
===== ========= =======================

**Handle record foo/admin:**

===== ========= =======================
Index Key       Value
...   ...       ...
100   HS_ADMIN  (refers to 201:foo/admin)
200   HS_VLIST  300:foo/bar
                301:foo/bar
                300:foo/doe
201   HS_VLIST  300:foo/admin
                301:foo/admin
300   HS_SECKEY *myadminpassword*
301   HS_PUBKEY 0000B652300
 ...  ...       ...
===== ========= =======================

**Handle record foo/bar:**

===== ========= =======================
Index Key       Value
...   ...       ...
100   HS_ADMIN  (refers to 201:foo/admin)
300   HS_SECKEY *mypassword*
301   HS_PUBKEY 0000A552100
 ...  ...       ...
===== ========= =======================

**Handle record foo/doe:**

===== ========= =======================
Index Key       Value
...   ...       ...
100   HS_ADMIN  (refers to 201:foo/admin)
300   HS_SECKEY *mypassword*
 ...  ...       ...
===== ========= =======================

Could this also be:

Note: This setting gives admin permissions to users foo/bar and foo/doe. You should also make sure that those users
are not able to change other people's admin permissions. For this, make sure the ``HS_ADMIN`` of the handles concerned with
user administration points to a username or ``HS_VLIST`` that only you can access.
As an example, we add a ``HS_VLIST`` to the foo/admin handle that contains the admin's usernames (index 201). Only the users in this list
can administer users.

**Handle record 0.NA/foo:**

===== ========= =======================
Index Key       Value
...   ...       ...
100   HS_ADMIN  (refers to 200:0.NA/foo)
200   HS_VLIST  200:foo/admin
 ...  ...       ...
===== ========= =======================

**Handle record foo/admin:**

===== ========= =======================
Index Key       Value
...   ...       ...
100   HS_ADMIN  (refers to 201:foo/admin)
200   HS_VLIST  200:foo/bar
                200:foo/doe
201   HS_VLIST  300:foo/admin
                301:foo/admin
300   HS_SECKEY *myadminpassword*
301   HS_PUBKEY 0000B652300
 ...  ...       ...
===== ========= =======================

**Handle record foo/bar:**

===== ========= =======================
Index Key       Value
...   ...       ...
100   HS_ADMIN  (refers to 201:foo/admin)
200   HS_VLIST  300:foo/bar
                301:foo/bar
300   HS_SECKEY *mypassword*
301   HS_PUBKEY 0000A552100
 ...  ...       ...
===== ========= =======================

**Handle record foo/doe:**

===== ========= =======================
Index Key       Value
...   ...       ...
100   HS_ADMIN  (refers to 201:foo/admin)
200   HS_VLIST  300:foo/doe
300   HS_SECKEY *mypassword*
 ...  ...       ...
===== ========= =======================

in the HS_VLIST of foo/ADMIN each HS_VLIST record of foo/bar and foo/doe is referenced. And in the handle record foo/bar and foo/doe also a HS_VLIST is added which points to the final HS_SECKEY or HS_PUBKEY.

Question: can foo/bar and foo/doe create handle records with the owner: 200:0.NA/foo? Or are they restricted to 200:foo/bar and 200/foo/doe for each?

[merretbuurman]

Hi, the version you suggest is possible, but it adds another level of depth into the permissions tree. I think I remember reading somewhere in the Handle System docs that too many levels should be avoided, but other than that I do not know if there is any negative consequences.

For the question: When creating handles, there is no restrictions at all in what can be written into their HS_ADMINs. It is very well possible to lock yourself out by creating a handle you cannot edit anymore, or even point to an inexistent user as admin, so nobody can edit that handle anymore (at least not in the 'normal' way). If users were restricted to 200:foo/bar and 200:foo/doe, they would not be able to create handles that a larger group can then edit.