User management - design document

Design document / white paper for user management
in openBmc covering user creation, deletion,
and 1:1 mapping with IPMI etc.

Change-Id: If1562752357093d0ba631d148ffdfde1ad742b87
Signed-off-by: Richard Marian Thomaiyar <richard.marian.thomaiyar@linux.intel.com>

1 files changed, 306 insertions, 0 deletions

diff --git a/user_management.md b/user_management.md
new file mode 100644
index 0000000..6a5fc57
--- /dev/null
+++ b/user_management.md
@@ -0,0 +1,306 @@
+# User Management - OpenBMC - Design document
+
+## Scope
+This document covers the architectural, interface, and design details needed for
+user-management components. The implementation detail is beyond the scope of
+this document.
+
+## Basic principles in design
+1. Use common user-management (e.g. phosphor-user-manager) rather than
+application-based user-management. Especially, avoid IPMI based user-management.
+2. For security reasons, avoid transmitting passwords over any D-Bus API.
+Observe this rule even while creating, modifying or authenticating the user.
+3. Have applications use the PAM module to authenticate the user instead of
+relying on a D-Bus API-based approach.
+4. User creation has to be generic in nature wherever possible.
+5. As IPMI requires clear text password (Refer IPMI 2.0 specification, section
+13.19-13.33 inclusive for more details), new PAM module (e.g. pam-ipmi modules)
+has to be used along with regular PAM password hashing modules (e.g. pam-unix),
+which will store the password in encrypted form. Implementation can elect to
+skip this if the IPMI daemon is not the part of the distribution or if the user
+created doesn't have an 'ipmi' group role.
+6. User name, Password, Group and Privilege roles are maintained by the common
+user-management (e.g. phosphor-user-manager), whereas individual user-related
+settings for any application has to be managed by that application. In other
+words, with the exception of User Name, Password, Group and Privileged Role,
+the rest of the settings needed has to be owned by the application in question.
+(e.g. IPMI daemon has to manage settings like channel based restriction etc.
+for the corresponding user). Design is made to cover this scenario.
+
+## Supported Group Roles
+The purpose of group roles is to determine the first-level authorization of the
+corresponding user. This is used to determine at a high level whether the user
+is authorized to the required interface.
+In other words, users should not be allowed to login to SSH if they only belong
+to webserver group and not to group SSH. Also having group roles in common
+user-management (e.g. phosphor-user-manager) allows different application to
+create roles for the other (e.g. Administrative user will be able to create a
+new user through webserver who will be able to login to webserver/REDFISH &
+IPMI etc.)
+
+*Note: Group names are for representation only and can be modified/extended
+ based on the need*
+
+|Sl. No| Group Name | Purpose / Comments                |
+|-----:|------------|-----------------------------------|
+|1     | ssh        | Users in this group are only allowed to login through SSH.|
+|2     | ipmi       | Users in this group are only allowed to use IPMI Interface.|
+|3     | redfish    | Users in this group are only allowed to use REDFISH Interface.|
+|4     | web        | Users in this group are only allowed to use webserver Interface.|
+
+## Supported Privilege Roles
+OpenBMC supports privilege roles which are common across all the supported
+groups (i.e. User will have same privilege for REDFISH / Webserver / IPMI /
+SSH).  User can belong to any one of the following privilege roles at any point
+of time.
+
+*Note: Privileges are for representation only and can be modified/extended
+ based on the need*
+
+|Sl. No| Privilege roles | Purpose / Comments                |
+|-----:|-----------------|-----------------------------------|
+|1     | admin           | Users are allowed to configure all OpenBMC (including user-management, network and all configurations). Users will have full administrative access.|
+|2     | operator        | Users are allowed to view and control basic operations. This includes reboot of the host, etc. But users are not allowed to change other configuration like user, network, etc.|
+|3     | user            | Users only have read access and can't change any behavior of the system.|
+|4     | callback        | Lowest privilege level, only allowed to initiate IPMI 2.0 specific callbacks.|
+
+## Common User Manager - D-Bus API (phosphor-user-manager)
+User Manager service exposes D-Bus methods for user-management operations.
+It exposes `xyz.openbmc_project.User.Manager` as a service and handles
+objects through `org.freedesktop.DBus.ObjectManager`. Please refer
+https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/xyz/openbmc_project/User
+for detailed user management D-Bus API and interfaces.
+
+## OpenBMC - User Management - High Level architectural diagram
+
+```
+                                WEBSERVER/REDFISH
+     ========================================================================
+    ||  ________________  |  ________________  |   |**********************| ||
+    ||  |PAM for user   | |  |Create new user| |   | Redfish specific 1:1 | ||
+    ||  |authentication | |  |or delete or   | |   | user settings storage| ||
+    ||  |_|_____________| |  |update________|| |   |**********************| ||
+    ||====|===============|=================|===========^===================||
+          |                                 |           |
+          V   Storage                       |           |
+    |**************|********************|   V           ^              NET-IPMID
+    |  pam_unix -  | pam_ipmi- encrypted|   |           |    ===========================
+    |  /etc/shadow | password (only if  |   |           |    ||                        ||
+    |  (hashed)    | user in ipmi group)|   |           |    || _____________________  ||
+    |***********************|***********|   |           |    || | RMCP+ login using  | ||
+                            +---<-----------------<---------<---- clear text password| ||
+                                            |           |    || |____________________| ||
+                                            |           |    ||________________________||
+                                D-Bus Call  |           |    || _____________________  ||
+                                +------------+          ^    || | Create new user    | ||
+                                |                       |    || | or delete or       | ||
+           Common user manager  |      D-Bus Call       |    || | update             | ||
+    ||==========================V==||<---------------------<----|(Note: Host-IPMID   | ||
+    ||     phosphor-user-manager   ||                   |    || | must use same logic| ||
+    ||                             ||                   |    || |____________________| ||
+    ||======================|======||                   |    ||                        ||
+                            V                           |    || |********************| ||
+                            |                           ^    || | IPMI specific 1:1  | ||
+                            |                           |    || | user mappings      | ||
+                            +------>-------------->-----+------>| storage            | ||
+                            PropertiesChanged /              || | Note: Either Host  | ||
+                            InterfacesAdded /                || | / Net IPMID must   | ||
+                            InterfacesRemoved /              || | implement signal   | ||
+                            UserRenamed Signals              || | handler            | ||
+                                                             || |********************| ||
+                                                             ||========================||
+
+```
+
+## OpenBMC - User Management - User creation from webserver flow - with all groups
+
+```
+------------------------------------|---------------------------------- -|-----------------------------|
+WEBSERVER                           | Common User Manager                |   IPMI & REDFISH(webserver) |
+------------------------------------|------------------------------------|-----------------------------|
+1.Request to add new user           |                                    |                             |
+with 'ipmi, redfish' Group.         |                                    |                             |
+Webserver sends D-Bus command       |                                    |                             |
+to user-manager with User Name,     |                                    |                             |
+Groups and Privilege (No Password)  |                                    |                             |
+                             (REQ)--------->                             |                             |
+                                    | 2. Validate inputs, including      |                             |
+                                    | group restrictions.                |                             |
+                                    | if successful go to step 4, else   |                             |
+                                    | return a corresponding error, (e.g.|                             |
+                                    | too many users, user name is too   |                             |
+                                    | long (say, more than IPMI required |                             |
+                                    | 16 bytes etc.)                     |                             |
+                            <-------------(FAILURE)                      |                             |
+3. Throw error to the user          |                                    |                             |
+                                    |                                    |                             |
+                                    | 4. Add User Name, Groups and       |                             |
+                                    | Privileges accordingly. Send signal|                             |
+                                    | for User Name created         ---(SIGNAL)->                      |
+                                    | (InterfacesAdded)                  | 5. IPMI & REDFISH can       |
+                                    |                                    | register for 'UserUpdate'   |
+                                    |                                    | signal handler and use      |
+                                    |                                    | the same to maintain 1:1    |
+                                    |                                    | mapping, if required        |
+                            <-------------(SUCCESS)                      |                             |
+6. User created successfully but    |                                    |                             |
+still can't login, as there is no   |                                    |                             |
+password set.                       |                                    |                             |
+                                    |                                    |                             |
+7.Set the password for              |                                    |                             |
+the user using pam_chauthtok()      |                                    |                             |
+(which will store clear-text        |                                    |                             |
+password in encrypted form, if      |                                    |                             |
+user is part of 'ipmi' Group)       |                                    |                             |
+                                    |                                    |                             |
+8. User created successfully        |                                    |                             |
+--------------------------------------------------------------------------------------------------------
+```
+
+## OpenBMC - User Management - User creation from IPMI - 'ipmi' Group only
+
+```
+------------------------------------|---------------------------------- -|-----------------------------|
+IPMI                                | Common User Manager                |   pam_unix/pam_ipmi storage |
+------------------------------------|------------------------------------|-----------------------------|
+1. User sends Set User Name command.|                                    |                             |
+IPMI Sends D-Bus command to         |                                    |                             |
+to user-manager with User Name      |                                    |                             |
+Groups & privileges (No Password) (REQ)--------->                        |                             |
+(Note: Configurations for other     |                                    |                             |
+commands like Set User Access /     |                                    |                             |
+Channel access has to be stored     |                                    |                             |
+in IPMI NV along with User Name)    |                                    |                             |
+                                    | 2. Validate inputs, including      |                             |
+                                    | group restrictions.                |                             |
+                                    | if success go to step 4, else      |                             |
+                                    | return a corresponding error.      |                             |
+                            <-------------(FAILURE)                      |                             |
+3. Return error to the Set User     |                                    |                             |
+Name command. User creation failed. |                                    |                             |
+                                    | 4. Add User Name, Groups and       |                             |
+                                    | Privileges accordingly. Send signal|                             |
+                                    | for User Name created              |                             |
+                            <-------------(SIGNAL) (InterfacesAdded)     |                             |
+5. IPMI can register for            |                                    |                             |
+'UserUpdate' signal handler and use |                                    |                             |
+the same to maintain 1:1 mapping,   |                                    |                             |
+if required                         |                                    |                             |
+                            <-------------(SUCCESS)                      |                             |
+6. User sends Set User Password     |                                    |                             |
+command. IPMI uses pam-ipmi         |                                    |                             |
+to set the password.                |                                    |                             |
+(Note: can't accept password without|                                    |                             |
+Set User Name command in first      |                                    |                             |
+place as User Name has to exist     |                                    |                             |
+before trying to store the password.|                                    |                             |
+Implementation can elect to accept  |                                    |                             |
+the password and set it through PAM |                                    |                             |
+after Set User Name command)   (SET)----------------------------------------> pam-ipmi will store      |
+                                    |                                    |clear text password in       |
+                                    |                                    |encrypted form along with    |
+                                    |                                    |hashed password by pam-unix, |
+                                    |                                    |when the user belongs to IPMI|
+                            <----------------------------------------------(SUCCESS)                   |
+7. User created successfully        |                                    |                             |
+but will allow only when user is    |                                    |                             |
+enabled. IPMI shouldn't allow user  |                                    |                             |
+to login if user is disabled        |                                    |                             |
+(Note: stored in IPMI NV).          |                                    |                             |
+--------------------------------------------------------------------------------------------------------
+```
+
+## OpenBMC - User Management - User deletion from webserver flow - with all groups
+
+```
+------------------------------------|---------------------------------- -|-----------------------------|
+WEBSERVER                           | Common User Manager                |   IPMI & REDFISH(webserver) |
+------------------------------------|------------------------------------|-----------------------------|
+1.Request to delete existing user   |                                    |                             |
+with 'ipmi, redfish' group          |                                    |                             |
+Webserver sends D-Bus command       |                                    |                             |
+to user-manager with User Name      |                                    |                             |
+to be deleted            (REQ)--------->                                 |                             |
+                                    | 2. Validate inputs, including      |                             |
+                                    | group restrictions.                |                             |
+                                    | if successful go to step 4, else   |                             |
+                                    | return corresponding error.        |                             |
+                                    | Can be user does not exist etc.    |                             |
+                            <-------------(FAILURE)                      |                             |
+3. Throw error to the user          |                                    |                             |
+                                    |                                    |                             |
+                                    | 4. Delete User Name, Group and     |                             |
+                                    | privileges along with password.    |                             |
+                                    | User Name deleted             ---(SIGNAL)->                      |
+                                    | (InterfacesRemoved)                | 5. IPMI & REDFISH can       |
+                                    |                                    | register for 'UserUpdate'   |
+                                    |                                    | signal handler and use      |
+                                    |                                    | the same to maintain 1:1    |
+                                    |                                    | mapping, if required        |
+                                    |                                    | IPMI must delete stored     |
+                                    |                                    | encrypted password.         |
+                            <-------------(SUCCESS)                      |                             |
+6. User deleted successfully,       |                                    |                             |
+                                    |                                    |                             |
+--------------------------------------------------------------------------------------------------------
+```
+
+## OpenBMC - User Management - User deletion from IPMI - 'ipmi' Group only
+
+```
+------------------------------------|---------------------------------- -|
+IPMI                                | Common User Manager                |
+------------------------------------|------------------------------------|
+1. User sends Set User Name command |                                    |
+to clear user name. Send D-Bus API  |                                    |
+to user-manager with User Name      |                                    |
+to delete                      (REQ)--------->                           |
+(Note: Configurations for other     |                                    |
+commands like Set User Access /     |                                    |
+Channel access has to be stored     |                                    |
+in IPMI NV along with User Name)    |                                    |
+                                    | 2. Validate inputs, including      |
+                                    | group restrictions.                |
+                                    | if successful go to step 4, else   |
+                                    | return a corresponding error (e.g. |
+                                    | User name doesn't exists etc.)     |
+                            <-------------(FAILURE)                      |
+3. Return error to the Set User     |                                    |
+Name command. User deletion failed. |                                    |
+                                    |                                    |
+                            <-------------(SIGNAL) 4. User Name deleted  |
+5. IPMI can register for            | (InterfacesRemoved)                |
+'UserUpdate' signal handler and use |                                    |
+the same to maintain 1:1 mapping,   |                                    |
+if required                         |                                    |
+                            <-------------(SUCCESS)                      |
+6. User deleted successfully        |                                    |
+                                    |                                    |
+--------------------------------------------------------------------------
+```
+
+## Recommended Implementation
+1. As per IPMI spec the max user list can be 15 (+1 for NULL User). Hence
+implementation has to be done in such a way that no more than 15 users are
+getting added to the 'ipmi' Group. Phosphor-user-manager has to enforce this
+limitation.
+2. Should add IPMI_NULL_USER by default and keep the user in disabled state.
+This is to prevent IPMI_NULL_USER from being created as an actual user. This is
+needed as NULL user with NULL password in IPMI can't be added as an entry from
+Unix user-management point of it.
+3. User creation request from IPMI / REDFISH must be handled in
+the same manner as described in the above flow diagram.
+4. Adding / removing a user name from 'ipmi' Group role must force a Password
+change to the user. This is needed as adding to the 'ipmi' Group of existing
+user requires clear text password to be stored in encrypted form. Similarly
+when removing a user from IPMI group, must force the password to be changed
+as part of security measure.
+5. IPMI spec doesn't support groups for the user-management. Hence the
+same can be implemented through OEM Commands, thereby creating a user in
+IPMI with different group roles.
+6. Do no use 'Set User Name' IPMI command to extend already existing
+non-ipmi group users to 'ipmi' group. 'Set User Name' IPMI command will not be
+able to differentiate between new user request or request to extend an existing
+user to 'ipmi' group. Use OEM Commands to extend existing users to 'ipmi' group.
+Note: 'Set User Name' IPMI command will return CCh 'Invalid data field in
+Request' completion code, if tried to add existing user in the system.