nethsm: Document namespaces (#240)

* nethsm: Document namespaces * fixup! nethsm: Document namespaces * language * fixup! nethsm: Document namespaces * fixup! nethsm: Document namespaces * minor text style * Update faq.rst * Update nethsm/administration.rst * Update nethsm/administration.rst Co-authored-by: Sven Anderson <[email protected]> * Update nethsm/administration.rst * Update administration.rst * Update administration.rst * Update administration.rst * software version 2.0 * small remarks reg. Namespaces --------- Co-authored-by: jans23 <[email protected]> Co-authored-by: Sven Anderson <[email protected]>
Nitrokey · Aug 1, 2024 · 01573b8 · 01573b8
1 parent 76a2ad0
commit 01573b8
Show file tree

Hide file tree

Showing 3 changed files with 148 additions and 14 deletions.
diff --git a/nethsm/administration.rst b/nethsm/administration.rst
@@ -2,7 +2,7 @@ Administration
 ==============
 
 This chapter describes administrative tasks for users with the *Administrator* role.
-Please refer to chapter `Roles <administration.html#roles>`__ to learn more about the role.
+Please refer to chapter `Roles <administration#roles>`__ to learn more about the role.
 
 .. important::
    Please make sure you read the information in the beginning of `this document <index.html>`__ before starting to work.
@@ -142,7 +142,7 @@ The current state of the NetHSM can be retrieved as follows.
       Information about the `/health/state` endpoint can be found in the `API documentation <https://nethsmdemo.nitrokey.com/api_docs/index.html#/default/GET_health-state>`__.
 
 A new NetHSM has an *Unprovisioned* state and after provisioning enters the *Operational* state.
-The provisioning of a NetHSM is described in the chapter `Provisioning <getting-started.html#provisioning>`__.
+The provisioning of a NetHSM is described in the chapter `Provisioning <getting-started#provisioning>`__.
 
 A NetHSM in *Operational* state can be locked again to protect it as follows.
 
@@ -496,9 +496,9 @@ The NetHSM logs metrics of system parameters.
 
 .. note::
    This command requires the authentication of a user with the *Metrics* role.
-   Please refer to chapter `Roles <administration.html#roles>`__ to learn more about the role.
+   Please refer to chapter `Roles <administration#roles>`__ to learn more about the role.
 
-Please refer to `Metrics <metrics.html>`__ to learn more about each metric.
+Please refer to `Metrics <metrics>`__ to learn more about each metric.
 
 The metrics can be retrieved as follows.
 
@@ -650,7 +650,7 @@ namely *Configuration Store*, *Authentication Store*, *Domain Key Store* and *Ke
 
 .. important::
    A NetHSM system software in *Unattended Boot* mode will require the *Unlock Passphrase* if restored on a different NetHSM hardware.
-   Please refer to chapter `Unlock Passphrase <administration.html#unlock-passphrase>`__ to learn more.
+   Please refer to chapter `Unlock Passphrase <administration#unlock-passphrase>`__ to learn more.
 
 .. important::
    A NetHSM in *Unattended Boot* mode will be in the same mode after a restore.
@@ -699,7 +699,7 @@ The backup passphrase can be set as follows.
 
 .. note::
    This command requires the authentication of a user with the *Backup* role.
-   Please refer to chapter `Roles <administration.html#roles>`__ to learn more.
+   Please refer to chapter `Roles <administratio#roles>`__ to learn more.
 
 The backup can be executed as follows.
 
@@ -940,7 +940,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#namespaces>`__ and `Tags <administration#tags-for-users>`__ for more fine-grained access restricions.
 
 .. note::
    In a future release, additional *Roles* may be introduced.
@@ -950,9 +950,12 @@ Add User
 
 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*.
+Please refer to chapter `Roles <administration#roles>`__ to learn more about *Roles*.
+
+Optionally, a user can be assigned to a `*Namespace* <administration#namespaces>`__.
 
 .. note::
+   The user ID must be alphanumeric.
    The NetHSM assigns a random user ID if none is specified.
 
 A user account can be added as follows.
@@ -964,7 +967,9 @@ A user account can be added as follows.
       +----------------------------------------------------------------+----------------------------------+
       | Option                                                         | Description                      |
       +================================================================+==================================+
-      | ``-n``, ``--real-name`` ``TEXT``                               | The real name of the user        |
+      | ``-n``, ``--real-name`` ``TEXT``                               | The real name of the new user    |
+      +----------------------------------------------------------------+----------------------------------+
+      | ``-N``, ``--namespace`` ``TEXT``                               | The Namespace of the new user    |
       +----------------------------------------------------------------+----------------------------------+
       | ``-r``, ``--role`` ``[Administrator|Operator|Metrics|Backup]`` | The *Role* of the new user       |
       +----------------------------------------------------------------+----------------------------------+
@@ -995,6 +1000,10 @@ 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>`__.
 
+By default, the Namespace is inherited from the user that adds the new user.
+Only users without a Namespace can choose a different Namespace for new users.
+The Namespace is used as a prefix for the user name, for example `namespace~user`. Therefore, the same user name can be used in several Namespaces.
+
 Delete User
 ~~~~~~~~~~~
 
@@ -1063,6 +1072,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
 ~~~~~~~~~~~~~~~
 
@@ -1100,12 +1111,127 @@ 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* were introduced in software version 2.0. When migrating from an earlier version of the software, all existing users and keys will be without a Namespace.
+
+Similarly to the concept of partitions, NetHSM supports the more flexible *Namespaces* which group keys, administrators, and users on a NetHSM into separate subsets.
+Users can only see and use keys in the same Namespace and can only see users in the same Namespace.
+It is not possible to see users and to see and use keys of other Namespaces.
+When a new user is created, it inherits the Namespace of the user that created it.
+The available storage capacity is shared between all Namespaces. 
+
+Users with the *Administrator* `Role <administration#roles>`__ are also referred to as *R-Administrator* if they are not in a Namespace, or *N-Administrator* if they are in a Namespace.
+
+Special rules apply to *R-Administrator* users:
+They can set the Namespace for new users, list all users and query the Namespace of a user.
+Also, the NetHSM configuration can only be accessed by *R-Administrator* users.  R-Administrators can not see keys in a Namespace.
+
+To be able to generate keys and users in a Namespace, the Namespace needs to be created by an *R-Administrator* user.
+Once the Namespace has been created, *R-Administrator* users can no longer create, delete or modify users in that Namespace.  This allows to protect Namespaces' keys being accessed by R-Administrator (also indirectly by adding a new user on behalf or resetting existing user's or administrator's credentials).
+Therefore, it is necessary to create an *N-Administrator* user for the Namespace before creating the Namespace.
+*R-Administrator* users can also delete a Namespace with all contained keys.
+
+List Namespaces
+^^^^^^^^^^^^^^^
+
+List the Namespaces on the NetHSM.
+
+The list can be retrieved as follows.
+
+.. tabs::
+   .. tab:: nitropy
+      **Example**
+
+      .. code-block:: bash
+
+         $ nitropy nethsm --host $NETHSM_HOST list-namespaces
+
+      .. code-block::
+
+         Namespaces on NetHSM localhost:8843:
+         - ns1
+         - ns2
+   .. tab:: REST API
+      Information about the `/namespaces` endpoint can be found in the `API documentation <https://nethsmdemo.nitrokey.com/api_docs/index.html#/default/GET_namespaces>`__.
+
+Add Namespace
+^^^^^^^^^^^^^
+
+Add a Namespace to the NetHSM.
+
+*R-Administrator* users can already create new accounts in the Namespace before it is created.
+After the creation, only *N-Administrator* users can manage the users in the Namespace.
+The creation and usage of keys in the Namespace is only possible after it has been added.
+
+.. note::
+   The Namespace ID must be alphanumeric.
+   The NetHSM assigns a random user ID if none is specified.
+
+A Namespace can be added as follows.
+
+.. tabs::
+   .. tab:: nitropy
+      **Arguments**
+
+      +---------------+------------------------+
+      | Argument      | Description            |
+      +===============+========================+
+      | ``NAMESPACE`` | The new Namespace.     |
+      +-------------+--------------------------+
+
+      **Example**
+
+      .. code-block:: bash
+
+         $ nitropy nethsm --host $NETHSM_HOST add-namespace ns1
+
+      .. code-block::
+
+         Namespace ns1 added to NetHSM localhost:8443
+   .. tab:: REST API
+      Information about the `/namespaces/{NamespaceID}` endpoint can be found in the `API documentation <https://nethsmdemo.nitrokey.com/api_docs/index.html#/default/PUT_namespaces-NamespaceID>`__.
+
+
+Delete Namespace
+^^^^^^^^^^^^^^^^
+
+Delete a Namespace from the NetHSM.
+
+Deleting a Namespace also deletes all keys of that Namespace.
+Remaining users in the Namespace cannot add keys until the Namespace has been added again.
+
+A Namespace can be deleted as follows.
+
+.. tabs::
+   .. tab:: nitropy
+      **Arguments**
+
+      +---------------+--------------------------+
+      | Argument      | Description              |
+      +===============+==========================+
+      | ``NAMESPACE`` | The Namespace to delete. |
+      +---------------+--------------------------+
+
+      **Example**
+
+      .. code-block:: bash
+
+         $ nitropy nethsm --host $NETHSM_HOST delete-namespace ns1
+
+      .. code-block::
+
+         Namespace ns1 deleted on NetHSM localhost:8443
+   .. tab:: REST API
+      Information about the `/namespaces/{NamespaceID}` endpoint can be found in the `API documentation <https://nethsmdemo.nitrokey.com/api_docs/index.html#/default/DELETE_namespaces-NamespaceID>`__.
+
 Tags for Users
 ~~~~~~~~~~~~~~
 
 *Tags* can be used to set fine-grained access restrictions on keys, and are an optional feature. One or more *Tags* can be assigned to user accounts with the *Operator* role only. The *Operators* can see all keys, but only use those with at least one corresponding *Tag*. A key can not be modified by an *Operator* user.
 
-To learn about how to use *Tags* on keys, please refer to `Tags for Keys <operation.html#tags-for-keys>`__.
+To learn about how to use *Tags* on keys, please refer to `Tags for Keys <operation#tags-for-keys>`__.
 
 A *Tag* can be added as follows.
 

diff --git a/nethsm/faq.rst b/nethsm/faq.rst
@@ -18,14 +18,14 @@ Frequently Asked Questions (FAQ)
 **Q:** Roadmap: Which features are planned?
    We plan the following developments in the loose order. Changes to this prioritization based on customer requests are possible.
 
-   * Performance improvements
-   * Quorum: m-of-n access scheme and security domain management
+   * Productive usable software container
    * Additional ECC: ECDH (X25519, NIST), secpXk (Koblitz) , Brainpool
+   * Quorum: m-of-n access scheme and security domain management
+   * Performance improvements
    * Direct, dynamic cluster capability, possibly support for external database
    * Remote attestation and cloud service
    * User authentication via mTLS certificates or FIDO
    * More user rights management (e.g. additional roles, groups)
-   * Productive usable software container
    * Further separations and hardenings
    * FIPS and/or Common Criteria certifications
    * Redundant power supplies

diff --git a/nethsm/operation.rst b/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
 ~~~~~~~