nethsm: Document namespaces

nethsm/administration.rst

@@ -936,7 +936,7 @@ Each user account configured on the NetHSM has one of the following *Roles* assi
 |                 | required to initiate a system backup only.                  |
 +-----------------+-------------------------------------------------------------+
 
-See `Tags <administration.html#tags-for-users>`__ for more fine-grained access restricions.
+See `Namespaces <administration.html#namespaces`__ and `Tags <administration.html#tags-for-users>`__ for more fine-grained access restricions.
 
 .. note::
    In a future release, additional *Roles* may be introduced.
@@ -948,6 +948,9 @@ Add a user account to the NetHSM.
 Each user account has a *Role*, which needs to be specified.
 Please refer to chapter `Roles <administration.html#roles>`__ to learn more about *Roles*.
 
+Optionally, a user can be assigned to a *Namespace*.
+See the chapter `Namespaces <administration.html#namespaces>`__ for more information.
+
 .. note::
    The NetHSM assigns a random user ID if none is specified.
 
@@ -962,6 +965,8 @@ A user account can be added as follows.
       +================================================================+==================================+
       | ``-n``, ``--real-name`` ``TEXT``                               | The real name of the user        |
       +----------------------------------------------------------------+----------------------------------+
+      | ``-N``, ``--namespace`` ``TEXT``                               | The namespace of the new user    |
+      +----------------------------------------------------------------+----------------------------------+
       | ``-r``, ``--role`` ``[Administrator|Operator|Metrics|Backup]`` | The *Role* of the new user       |
       +----------------------------------------------------------------+----------------------------------+
       | ``-p``, ``--passphrase`` ``TEXT``                              | The passphrase of the new user   |
@@ -991,6 +996,9 @@ A user account can be added as follows.
 
       Information about the `/users/{UserID}` endpoint, to create a user with specifying the user ID, can be found in the `API documentation <https://nethsmdemo.nitrokey.com/api_docs/index.html#/default/PUT_users-UserID>`__.
 
+Per default, the namespace is inherited from the user that adds the new user.
+Only users without a namespace can chose a different namespace for new users.
+
 Delete User
 ~~~~~~~~~~~
 
@@ -1023,6 +1031,9 @@ A user account can be deleted as follows.
    .. tab:: REST API
       Information about the `/users/{UserID}` endpoint can be found in the `API documentation <https://nethsmdemo.nitrokey.com/api_docs/index.html#/default/DELETE_users-UserID>`__.
 
+.. note::
+   Before deleting the last user in a namespace, all keys in the namespace must be deleted.
+
 List Users
 ~~~~~~~~~~
 
@@ -1059,6 +1070,8 @@ The list can be retrieved as follows.
 
       Information about the `/users/{UserID}` endpoint can be found in the `API documentation <https://nethsmdemo.nitrokey.com/api_docs/index.html#/default/GET_users-UserID>`__.
 
+Users within a namespace can only see users in the same namespace.
+
 User Passphrase
 ~~~~~~~~~~~~~~~
 
@@ -1096,6 +1109,19 @@ The user passphrase can be set as follows.
    .. tab:: REST API
       Information about the `/users/{UserID}/passphrase` endpoint can be found in the `API documentation <https://nethsmdemo.nitrokey.com/api_docs/index.html#/default/POST_users-UserID-passphrase>`__.
 
+Namespaces
+~~~~~~~~~~
+
+*Namespaces* group the keys and users on a NetHSM into subsets.
+Users can only see and use keys in the same namespace.
+When a new user is created, it inherits the namespace of the user that created it.
+It is not possible to see users from other namespaces.
+
+Special rules apply to users without a namespace:
+They can set the namespace for new users, list all users and query the namespace of a user.
+
+It is not necessary to explicitly create or delete namespaces.
+
 Tags for Users
 ~~~~~~~~~~~~~~
 

nethsm/operation.rst

@@ -50,6 +50,8 @@ The supported key types and their corresponding mechanisms are the following.
 |                | ``AES_Decryption_CBC``         |
 +----------------+--------------------------------+
 
+Keys are assigned to the `*Namespace* <administration.html#namespaces>`__ of the user that generates the key.
+
 The key can be generated as follows.
 
 .. tabs::
@@ -134,6 +136,8 @@ The supported key types and their corresponding mechanisms are the following.
 |                | ``AES_Decryption_CBC``         |
 +----------------+--------------------------------+
 
+Keys are assigned to the `*Namespace* <administration.html#namespaces>`__ of the user that imports the key.
+
 The import can be initiated as follows.
 
 .. tabs::
@@ -199,6 +203,7 @@ Delete Key
 ~~~~~~~~~~
 
 The NetHSM can delete keys from the *Key Store*.
+Users can only delete keys in their `*Namespace* <administration.html#namespaces>`__.
 
 .. tabs::
    .. tab:: nitropy
@@ -229,7 +234,7 @@ The NetHSM can delete keys from the *Key Store*.
 List Keys
 ~~~~~~~~~
 
-The NetHSM can list all the available keys in the *Key Store*.
+The NetHSM can list all keys in the *Key Store* that are in the `*Namespace* <administration.html#namespaces>`__ of the current user.
 
 The list can be retrieved as follows.
 
@@ -267,6 +272,7 @@ Show Key Details
 ~~~~~~~~~~~~~~~~
 
 The NetHSM can output more detailed information about a stored key.
+Users can only access keys in their `*Namespace* <administration.html#namespaces>`__.
 
 The detailed information can be retrieved as follows.
 
@@ -596,6 +602,8 @@ The NetHSM supports generating CSR (Certificate Signing Requests) for the stored
 Key Operations
 --------------
 
+All operations described in this chapter can only be executed for keys that are in the `*Namespace* <administration.html#namespaces>`__ of the current user.
+
 Encrypt
 ~~~~~~~