// Copyright (c) 2018, Intel Corporation.
// SPDX-License-Identifier: BSD-3-Clause

ifdef::manpage[]
ipmctl-change-device-security(1)
================================
endif::manpage[]

NAME
----
ipmctl-change-device-security - Changes the PMem module security lock state

SYNOPSIS
--------
[verse]
ipmctl set [OPTIONS] -dimm [TARGETS] Lockstate=(Unlocked|Disabled|Frozen)
Passphrase=(string)

DESCRIPTION
-----------
Changes the data-at-rest security lock state for the persistent memory on one or more
PMem modules.

ifdef::os_build[]
NOTE: This command is subject to OS Vendor (OSV) support. It will return "Not Supported."
An exception is if the PMem module is Unlocked Seurity State, then transitioning to Disabled
is permitted.
endif::os_build[]

OPTIONS
-------
-h::
-help::
  Displays help for the command.

-ddrt::
  Used to specify DDRT as the desired transport protocol for the current invocation of ipmctl.

-smbus::
  Used to specify SMBUS as the desired transport protocol for the current invocation of ipmctl.

NOTE: The -ddrt and -smbus options are mutually exclusive and may not be used together.

ifdef::os_build[]
-o (text|nvmxml)::
-output (text|nvmxml)::
  Changes the output format. One of: "text" (default) or "nvmxml".
endif::os_build[]

-source (path)::
  File path to a local file containing the new passphrase (1-32 characters).

TARGETS
-------
-dimm [DimmIDs]::
  Changes the lock state of a specific PMem modules by supplying one or more comma
  separated PMem module identifiers. However, this is not recommended as it may put
  the system in an undesirable state. The default is to modify all manageable
  PMem modules.

PROPERTIES
----------
LockState::
  The desired lock state.
  - "Disabled": Removes the passphrase on an PMem module to disable security. Permitted
    only when LockState is Unlocked.
  - "Unlocked": Unlocks the persistent memory on a locked PMem module.
  - "Frozen": Prevents further lock state changes to the PMem module until the next
    reboot.

Passphrase::
The current passphrase (1-32 characters). For better passphrase protection, specify an
empty string (e.g., Passphrase="") to be prompted for the current passphrase or to use
a file containing the passphrases with the source option.

EXAMPLES
--------
Unlocks device 0x0001.
[verse]
ipmctl set -dimm 0x0001 LockState=Unlocked Passphrase=""

Unlocks device 0x0001 by supplying the passphrase in the file "mypassphrase.file". In this
example, the format of the file would be:

#ascii +
Passphrase=myPassphrase
[verse]
ipmctl set -source myfile.file -dimm 0x0001 LockState=Unlocked
Passphrase=""

LIMITATIONS
-----------
In order to successfully execute this command:

- The caller must have the appropriate privileges.

- The specified PMem modules must be manageable by the host software, have security enabled,
  not be in the "Frozen" or "Exceeded" lock states, and not executing a long operation
  (ARS, Overwrite, FWUpdate).

ifdef::os_build[]
The command is subject to OS Vendor (OSV) support. If OSV does not provide support,
the command may return "Not Supported." An exception is if the PMem module is Unlocked
(via UEFI or OSV tool), then transitioning to Disabled is possible regardless of
OSV support.
endif::os_build[]

RETURN DATA
-----------
If an empty string is provided for the passphrase property and the source option is not
included, the user will be prompted (once for all PMem modules) to enter the current
passphrase. The passphrase characters are hidden.

Current passphrase: ****

For each PMem module, the CLI will indicate the status of the security state change.
If a failure occurs when changing multiple PMem modules, the process will exit and
not continue updating the remaining PMem modules.

SAMPLE OUTPUT
-------------
[verse]
Unlock PMem module (DimmID): Success
Unlock PMem module (DimmID): Error (Code) - (Description)
Remove passphrase from PMem module (DimmID): Success
Remove passphrase from PMem module (DimmID): Error (Code) - (Description)
