diff --git a/nethsm/administration.rst b/nethsm/administration.rst index 6dec9d7125..f403ca33c3 100644 --- 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 `__ to learn more about the role. +Please refer to chapter `Roles `__ to learn more about the role. .. important:: Please make sure you read the information in the beginning of `this document `__ 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 `__. 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 `__. +The provisioning of a NetHSM is described in the chapter `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 `__ to learn more about the role. + Please refer to chapter `Roles `__ to learn more about the role. -Please refer to `Metrics `__ to learn more about each metric. +Please refer to `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 `__ to learn more. + Please refer to chapter `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 `__ to learn more. + Please refer to chapter `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 `__ for more fine-grained access restricions. +See `Namespaces `__ and `Tags `__ 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 `__ to learn more about *Roles*. +Please refer to chapter `Roles `__ to learn more about *Roles*. + +Optionally, a user can be assigned to a `*Namespace* `__. .. 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 `__. +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 `__. +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 `__. +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 `__ 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 `__. + +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 `__. + + +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 `__. + 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 `__. +To learn about how to use *Tags* on keys, please refer to `Tags for Keys `__. A *Tag* can be added as follows. diff --git a/nethsm/faq.rst b/nethsm/faq.rst index 2054bba961..c17e87668e 100644 --- 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 index e2c9a04b73..a44021070b 100644 --- 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 `__* 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* `__ 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* `__. .. 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* `__ 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* `__. 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* `__ of the current user. + Encrypt ~~~~~~~