1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
|
# 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________|| | |**********************| ||
||====|===============|=================|===========^===================|| Network
| | | ||**********************||
V Storage | |--------------------------|| MaxPrivilege - max ||
|**************|********************| V ^ || allowed privilege on ||
| pam_unix - | pam_ipmi- encrypted| | | || channel ||
| /etc/shadow | password (only if | | | NET-IPMID **************************
| (hashed) or | user in ipmi group)| | | =========================== |
| pam_ldap | | | | || _____________________ || |
|***********************|***********| | | || | 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 | ||
|| |********************| ||
||========================||
```
## User management - overview
```
user management
+---------------------------------------------------------+
| phosphor-user-manager |
| +---------------------------------------------+ |
| | Local user management: | |
| | I: Manager | |
| | M: CreateUser, RenameUser | |
| | P: AllPrivileges, AllGroups | |
| | S: UserRenamed | |
| | | |
| | I: Attributes | |
| | PATH: /xyz/openbmc_project/user/<name> | |
| | P: UserGroups, UserPrivilege, UserEnabled, | |
| | UserLockedForFailAttempt | |
| | | |
| | I: AccountPolicy | |
| | P: MaxLoginBeforeLockout, MinPasswordLength | |
| | AccountUnlockTimeout, RememberOldPassword | |
| | | |
| | General API (Local/Remote) | |
| | M: GetUserInfo() | |
| | | |
| +---------------------------------------------+ |
| |
| Remote User Management - Configuration |
| +--------------------------+------------------+ |
| | Provides interface for remote | |
| | user management configuration | |
| | (LDAP / NIS / KRB5) | |
| +---------------------------------------------+ |
| |
+---------------------------------------------------------+
```
## 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 | |
| |
--------------------------------------------------------------------------
```
## Authentication flow
Applications must use `pam_authenticate()` API to authenticate user.
Stacked PAM modules are used such that `pam_authenticate()` can be used
for both local & remote users.
```
+----------------------------------+
| Stacked PAM Authentication |
| +-----------------------+ |
| | pam_unix.so / local | |
| | user authentication | |
| | module. | |
| +-----------------------+ |
| ... |
| +-----------------------+ |
| | nss_pam_ldap.so / any | |
| | remote authentication | |
| | pam modules | |
| +-----------------------+ |
+----------------------------------+
```
## Password update
Applications must use `pam_chauthtok()` API to set / change user password.
Stacked PAM modules allow all 'ipmi' group user passwords to be stored
in encrypted form, which will be used by IPMI. The same has been performed
by `pam_ipmicheck` and `pam_ipmisave` modules loaded as first & last modules
in stacked pam modules.
```
+------------------+---------------+
| Stacked PAM - Password |
| |
| +----------------------------+ |
| | pam_ipmicheck.so. Checks | |
| | password acceptance for | |
| | 'ipmi' group users | |
| +----------------------------+ |
| |
| +-------------+--------------+ |
| | pam_unix.so - to update | |
| | local user's password | |
| | | |
| +----------------------------+ |
| |
| +-----------------+----------+ |
| | pam_ipmisave.so - stores | |
| | 'ipmi' group user's | |
| | password in encrypted form | |
| +----------------------------+ |
| |
+----------------------------------+
```
## Authorization flow (except IPMI)
```
+
|
|
+-------------v--------------+
|pam_authenticate() to |
|authenticate the user |
|(local / remote) |
+-------------+--------------+
|
|
+-------------v--------------+
|Read user properties using |
|GetUserInfo() (for local & |
|remote users). |
|Allow group access based on |
|group property |
+-------------+--------------+
|
|
+-------------v--------------+
|Read Channel MaxPrivilege |
|from /xyz/openbmc_project/ |
|network/ethX. Use the |
|minimum of user & channel |
|privilege as the privilege |
|Note: Implementation can |
|elect to skip the same, if |
|authorization based on |
|channel restriction is not |
|needed. |
+----------------------------+
```
## 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.
## Deployment - Out of factory
### Guidelines
As per [SB-327 Information Privacy](https://leginfo.legislature.ca.gov/faces/billTextClient.xhtml?bill_id=201720180SB327), Connected devices must avoid
shipping with generic user name & password. The reasonable security expected is
1. Preprogrammed password unique to each device
2. Forcing user to generate new authentication account, before using the device.
### Generating user during deployment:
To adhere above mentioned guideline and to make OpenBMC more secure, this design
specifies about forcing end-user to generate a new account, during deployment
through any of the system in-band interfaces (like KCS etc.).
IPMI 2.0 specification provides commands like `SetUserName`, `SetUserPassword`,
`SetUserAccess`, which must be used to create a new user account instead of
using any generic default user name and password. Accounts created through this
method have access to IPMI, REDFISH & Webserver and can be used to create more
accounts through out-of-band interfaces.
### Special user - root – user id 0:
Exposing root account (user id 0) to end-user by default (other than debug /
developer scenario) is security risk. Hence current architecture recommends not
to enable root user by default for end-user.
For general login for debug / developer builds, a new default user with password
can be created by specifying the same in local.conf.sample file. This can be
used to establish a session by default (CI systems etc. can use this account).
From OpenBMC package user name `openbmc` with password `0penBmc$` can be added.
#### Debugging use-case
`root` user / sudo privilege access are required during development / debug
phase of the program. For this purpose a new IPMI OEM command (TBD) / REDFISH
OEM action(TBD) to can be used to set password for the root user, after which
`root` user can be used to login to the serial console and for further debugging
(Note: `root` user will not be listed as user account in any interfaces like
IPMI / REDFISH from user management point of view).
### Deployment for systems without in-band interfaces:
Any systems which doesn’t have in-band system interface can generate passwords
uniquely for each & every device or can expose a default user name & password
forcing end-user to update the same, before using the device (TBD).
|
