docs/designs/expired-password.md

# Initial expired passwords

Author:
  Joseph Reynolds <josephreynolds1>

Other contributors:
  None

Created:
  2019-07-24

## Problem Description
OpenBMC has a default password, connects to the network via DHCP, and
does not have a mechanism to require administrators to change the
BMC's password.  This may lead to BMCs which have default passwords
being on the network for long time periods, effectively giving
unrestricted access to the BMC.

## Background and References
Various computer systems ship with default userid and passwords and
require the password be changed on the initial signon.  This reduces
the time window when the system is accessible with a default password.

Various BMC interfaces require authentication before access is
granted.  The authentication and account validation steps typically
result in outcomes like this:
1. Success, when the access credentials (such as username and password)
   are correct and the account being accessed is valid.
2. Failure, when either the access credentials are invalid or the
   account being accessed is invalid.  For example, the account itself
   (not merely its password) may be expired.
3. PasswordChangeRequired, when the access credentials are correct and
   the account is valid except the account's password is expired (such as
   indicated by PAM_CHANGE_EXPIRED_AUTHTOK).

OpenBMC currently implements the first two outcomes; it treats
PasswordChangeRequired the same as an account that is invalid for any
other reason.  Some servers (such as the OpenSSH server) handle the
PasswordChangeRequired by implementing a "password change dialog".

The [Redfish Specification version 1.7.0][] section 13.2.6.1 ("Password
change required handling") provides the ManagerAccount resource v1.3
with a PasswordChangeRequired property which supports a password
change dialog.

[Redfish Specification version 1.7.0]: https://www.dmtf.org/sites/default/files/standards/documents/DSP0266_1.7.0.pdf

Note the terminology:
An "expired password" is a special case of "password change required".

The meaning of the term "access" varies by context.  It could mean:
 1. Access to the BMC's network interfaces.
 2. Access to the BMC's authentication mechanisms together with
    correct credentials, whether or not those credentials have
    expired and must be changed.
 3. Access to the BMC's function via an authenticated interface, for
    example, such as establishing a session after you've changed your
    initial password.
 4. Access to the BMC's function via an unauthenticated interface such
    as host IPMI or physical control panel (example: power button).

This design uses meanings 3 and 4 except where indicated.

## Requirements
The requirements are:
 - The BMC's initial password must be expired when the new
   EXPIRED_PASSWORD image feature is used.
 - An account with an expired password must not be allowed to use the
   BMC (except to change the password).
 - There must be a way to change the expired password using a
   supported interface.

The use case is:
 - The BMC automatically connects to its management network which
   offers administrative or operational interfaces (whether or not the
   BMC is normally operated via its host).
 - The BMC is operated from its management network.

Preconditions for the BMC include:
 - The BMC has at least one account with a default password built in.
 - The BMC can update the password; for example, the `/etc/passwd`
   file is writeable.

## Proposed Design
This design has three main parts:

1. There is a new image feature EXPIRED_PASSWORD. When
   EXPIRED_PASSWORD is enabled, the BMC's default password will
   initially be expired as if via the `passwd --expire root` command.
   This administratively expires the password and is not based on
   time.  An account with an expired password is neither locked nor
   disabled.

   This feature is intended to be enabled by default, with a staging
   plan: the feature will be disabled to give time for the continuous
   integration (CI) and test automation efforts to adapt, then enabled
   for the overall project.

2. The BMC's network interfaces (such as REST APIs, SSH, and IPMI)
   disallow access via an account which has an expired password.  If
   the access credentials are otherwise correct and the reason for the
   authentication failure is an expired password (determined by the
   usual Linux practices), where possible, the interface should
   indicate the password is expired and how to change it (see below).
   Otherwise the usual security protocols apply (giving no additional
   information).

   The `/login` URI is enhanced.  If it is used with correct
   credentials (userid and password) and the password needs to be
   changed the request will fail to create a session and indicate a
   password change is needed.  If it is used with correct userid and
   incorrect password, or with an incorrect userid, the behavior must
   not change.  Note the `/login` URI is deprecated.

   The '/redfish/v1/SessionService/Sessions/<session>' and
   '/redfish/v1/AccountService/Accounts/<account>' resources are
   enhanced to indicate PasswordChangeRequired per the Redfish spec.

   The `ipmitool` command treats an expired password the same as an
   invalid password.  Note the RMCP+ standard, such as used for the
   BMC's network IPMI interface, does not support changing the
   password when establishing a session.  The ipmitool is not being
   enhanced by this design.

   The Secure Shell access (via the `ssh` command) already correctly
   indicates when the password is expired.  No change is needed.  But
   see the next bullet for the expired password dialog.

3. There is a way for an account owner to change their own expired
   password.  This can be either from a network-facing or in-band
   password changing protocol.  For example:
    - Redfish: This design adds the Redfish PasswordChangeRequired
      handling to BMCWeb.  See below for details.
    - SSH server: The SSH servers may have an expired password change
      dialog.  For example, OpenSSH implement this feature.  However,
      the Dropbear SSH server announces the password is expired, but
      does not implement the dialog to change it.
    - Access via the BMC's host: for example, via the `ipmitool user
      set password` command when accessed in-band.

When Redfish creates a session with PasswordChangeRequired, every
response contains a PasswordChangeRequired message.  The session
effectively has only the ConfigureSelf privilege which allows it to
only change the password and terminate the session.  The usage
pattern is:
 1. Create a session.
 2. If the PasswordChangeRequired message is present:
     1. PATCH the new password into the ManagerAccount object.
     2. Any other use of the session will get HTTP status code 403
        Forbidden.
     3. DELETE the Session object to terminate the session.
     4. Create a new session and continue.

This design is intended to cover any cause of expired password,
including both the BMC's initial expired password and password expired
for another cause such as aging or via the `passwd --expire` command.

This design is intended to enable the phosphor-webui web application
to implement a password change dialog for the signon screen.

Per the above design, when the web app uses either `/login` or
`/redfish/v1/SessionService` to establish a session and the account
has an expired password:
 - If the `/login` URI was used, the HTTP response indicates the
   password must be changed, and will not establish a session.  In
   this case, the web app must use the Redfish API to establish a
   session.
 - POST to `/redfish/v1/SessionService/Sessions` will establish a
   session which will have the PasswordChangeRequired message.
 - At this point the web app can display a message that the password
   is expired and must be changed, then get the new password.
 - PATCH the password to the account specified in the
   PasswordChangeRequired message.
 - DELETE the Session object to terminate the session.
 - Create a new session and continue.

## Alternatives Considered
The following alternate designs were considered:
- Unique password per machine.  That approach requires additional
  effort, for example, to set and track assigned passwords.
- Default to having no users with access to the BMC via its network.
  When network access is needed, a technician would create or modify
  the userid to have network authority and establish a password at
  that time.  This may be through the BMC's host system or via the
  BMC's serial console.  That approach requires the tech to have
  access, and requires re-provisioning the account after factory reset
- Disable network access by default.  That approach requires another
  BMC access vector, such as physical access or via the BMC's host, to
  enable network access.
- Provision the BMC with a certificate instead of a password, for
  example, an SSH client certificate.  That approach suffers from the
  same limitations as a default password (when the matching private
  certificate becomes well known) and requires the BMC provide SSH
  access.
- Require physical presence to change the password.  For example,
  applying a jumper, or signing in via a serial cable.  That approach
  is not standard.
- Have LDAP (or any authentication/authorization server) configured
  and have no local users which have default passwords configured in
  the BMC firmware image.  That approach requires the customer have an
  LDAP (or similar) server.  Also, how we can configure the LDAP, as
  we don't know the customer LDAP server configuration?
- Have a new service to detect if any password has its default value,
  and write log messages for that condition, with the idea to alert
  the system owner of this condition. That approach doesn't solve the
  problem and burdens BMC resources.

Warning.  This design may leave the BMC with its default password for
an extended period of time if the use case given in the requirements
section of this design does not apply.  For example, when the host is
operated strictly via its power button and not through the BMC's
network interface.  In this case, the alternatives listed above may
mitigate this risk.  Another alternative is a design where the BMC is
initially in a provisioning mode which does not allow the BMC to
operate its host.  The idea is that you have to establish access to
the BMC (which includes changing its password) before you can leave
provisioning mode.

The BMCWeb Redfish server could be enhanced so that when the Password
is successfully patched, the session no longer asserts the
PasswordChangeRequired condition and re-asserts the user's usual
authority immediately without requiring a new session.  This is
allowed by the Redfish spec, but was not implemented because it would
be more difficult to code and test.

## Impacts
Having to change an expired password is annoying and breaks
operational procedures and scripts.  Documentation, lifecycle review,
and test are needed.  Expect pain when this is enabled.

To help with this, the [REDFISH-cheatsheet][] will be updated with
commands needed to detect and change an expired password.

[REDFISH-cheatsheet]: https://github.com/openbmc/docs/blob/master/REDFISH-cheatsheet.md

This design does not affect other policies such as password aging.

## Testing
Scenarios:
1. Ensure that when the BMC is in its initial state:
    - All available network interfaces deny access.
    - Selected interfaces allow the password to be changed.
2. Ensure factory reset resets the password to its initial expired
   state (repeat the tests above).
3. Ensure the password change is effective for users entering from all
   supported interfaces.  For example, change the password via the
   Redfish API, and validate that the old password does not work and
   the new password does work via IPMI for the same user.
4. Handle BMC code update scenarios.  For example, (A) Ensure code
   update does not cause a previously set password to change to
   default or to expire.  (B) Validate what happens when the BMC has a
   default password and does code update to a release which has the
   default expired password design (this design).
5. Ensure the BMC continues to operate its host, for example, when the
   BMC is factory reset while the host is running.  Ensure the power
   button can be used to power off the host while the BMC's password is
   expired.
6. Test on BMC using Linux PAM both with and without LDAP or
   ActiveDirectory configured.
7. Validate you can to change an IPMI user's expired password, such as
   with: ipmitool user set password 1 NEWPASSWORD.  This can be from
   another IPMI user's session or from unauthenticated access.