nvmesed Command

Purpose

Manages the nonvolatile memory express (NVMe) self-encrypting drives (SED).

Syntax

To set a user pin in platform keystore (PKS):

nvmesed -K -l nvmeX -n user_pin [ -t tag]

To initialize a drive to enable SED:

nvmesed -I -l nvme# -s sid_pin -a admin_pin -u user_pin

To revert a drive to disable SED:

nvmesed -R -l nvme# -a <admin_pin>

To return a drive to the original factory state (OFS):

nvmesed -O -l nvme# -s <sid_pin>

nvmesed -O -l nvme# -p psid_pin

To change user pins on a drive:

nvmesed -C -l nvme# -a admin_pin -n new_admin_pin

nvmesed -C -l nvme# -u user_pin -n new_user_pin

nvmesed -C -l nvme# -s sid_pin -n new_sid_pin

nvmesed -C -l nvme# -s sid_pin -r

To unlock a drive:

nvmesed -U -l nvme# -a admin_pin

nvmesed -U -l nvme# -u user_pin

To query the status of an SED:

nvmesed -Q -l nvme#

nvmesed -Q -l nvme# -a admin_pin

nvmesed -Q -l nvme# -u user_pin

Description

Starting from AIX 7.3 with Technology level 1, the AIX operating system supports NVMe self-encrypting drives (SED). The NVMe SED encrypts the user data with a secret pin. The pin is stored in platform keystore (PKS), which is a secure nonvolatile storage in Power Systems servers. As the pin is stored outside the drive, even when the drive is lost or stolen, the data in the drive is rendered meaningless without the pin.

The AIX device driver provides the pin to the drive, when required. The nvmesed user space utility handles the SED management. The pin cannot be used similar to the Media Encryption Key (MEK) that is used to encrypt the data. The MEK can be deciphered or unwrapped only when the pin is known. The drive only retains a wrapped MEK that was created by using the pin to encrypt a hardware-generated plain text MEK. The plain text MEK cannot be accessed from outside the drive and exists only in the drive after a valid pin is entered.

The nvmesed command manages the following SED functions:

NVMe drives are shipped without self-encryption. This state is known as Original Factory State (OFS). You can use the nvmesed command to enable self-encryption to protect the drive data with a pin. In most cases, self-encryption preserves existing data on the drive.
You can use the nvmesed command to revert the drive to its original state before initializing SED. This usage includes the following cases:
- Return to the OFS by securely purging all the user data on the drive.
- Revert to the original state before initializing SED by turning off the pin-controlled encryption while preserving the user data.

You can use the nvmesed command to change the pin periodically. The drive does not store the pin, but stores only a cryptographic hash of the pin so that it can determine whether the specified pin is valid. Thus, if you change the pin on the drive, a new hash of the pin on the drive is stored on the drive. Management includes the following authorities and types of pins:

Security Identifier (SID): The SID authority represents the drive owner. Enabling self-encrypting drives (SED) and returning the drive to OFS requires the SID authority. If the SID pin is lost, you must return the drive to OFS by using a pointer to the security identifier (PSID) pin that is a fixed pin and is printed on the drive label. You can establish a new set of pins by enabling the SED again as a new drive.
Admin: The Admin authority manages the data encryption, power on locking, and various access control policies of the SED. Enabling SED, reverting the SED, and unlocking the drive requires the Admin authority.
User: The locked device can only be unlocked by a user authority. The AIX operating system stores only the user pin with the most restricted capabilities in the PKS. In addition, both Admin and User authorities can query the status of a SED drive.

The following perquisites must be met to use the nvmesed utility:

PKS must be enabled for the AIX logical partition in the Hardware Management Console (HMC).
The logical partition must be running AIX 7.3 or later.
The host must be Power10 processor-based servers (or later) that support NVMe SED.
The drives must be NVMe drives that support SED. SED-capable drives other than NVMe do not suffice the requirement.

Review the following practices for using the nvmesed utility:

Each of the three pins must be unique and must be composed of 32 bytes of ASCII characters.
Maintain a record of all pins, including previously used pins, and track pin activities for future reference.
PKS stores only the User pin. An AIX logical partition contains a single user pin. All drives in the logical partition can use the same user pin. Therefore, use the same SID and Admin pins on a logical partition for ease of administration. SID and Admin pins are specified in the nvmesed command and are not stored in PKS.

If you are moving a drive to a system that supports SED, you must reinitialize the drive. If you know the existing SID and Admin pins, you can reinitialize the drive while preserving the existing data. If the data cannot be preserved, you must return the drive to the OFS before you can re-enable SED.

Flags

-a admin_pin: Specifies the existing Admin pin.
-C: Changes pins on a specific drive.; Each authority can change its own pin if the current pin is specified.
-I nvmeX | nvme#: Specifies the NVMe drive. nvmeX is any available drive on which SED is supported. nvme# is a specific target drive on which the nvmesed command is run.; Before you change the User pins, one drive at a time, you can first set the new pin on PKS as an alternative pin. After you change the User pin on all drives to the new User pin, the primary PKS pin is changed to the new pin, and the alternative pin must be erased. Because PKS does not store SID and Admin pins, these pins might not need coordination with PKS.
-I: Initializes a drive to enable SED.
-K: Sets a user pin that is stored in the PKS.; You must use this flag as the first step before you enable SED for the first time in the logical partition. Select a user pin that is shared by all drives and store it in PKS.
-n pin: Specifies a new SID, Admin, or User pin that must be used.
-O: Returns the drive to the original factory state (OFS).; You must specify the SID pin that was set during initialization or the PSID pin that is printed on drive label. After the drive is returned to the OFS successfully, the SID, Admin, and User pins become invalid on the drive. All existing data is purged cryptographically, and the drive can be considered as a new drive.
-p psid_pin: Specifies the existing PSID pin.
-Q: Queries the SED status.
-R: Disables SED and reverts the drive such that the data can be accessed without any pin.
-r: Omits the SID pin and returns the drive into OFS with unprotected data and no pins.
-s sid_pin: Specifies the existing SID pin.
-t tag: Specifies an optional tag which is an 8-character alternate name for the pin that is used when PKS pins are queried. PKS displays only this tag but not the 32-byte pin. The tag must be unique so that it can easily correlate to the pin.
-u user_pin: Specifies an optional tag which is an 8-character alternate name for the pin that is used when PKS pins are queried. PKS displays only this tag but not the 32-byte pin. The tag must be unique so that it can easily correlate to the pin.
-U: Unlocks the drive manually.; If the PKS pin is not available or does not match the User pin that was set on the drive, the drive remains locked after a power cycle. You can use this flag to unlock the drive manually by specifying either the User pin or the Admin pin that was set during initialization.

Error messages

start_session(xxx_sp) failed, status=0x30/0x1: This error is observed when drive has been partially impacted by an earlier command that altered the pin, which failed at a later stage.

cannot start_session(locking_sp) to unlock, status=0x30/0xc: This error is observed when the drive is not SED-enabled but the requested action needs the drive to be SED-enabled. To confirm, use the Query (-Q) option.

start_session(xxx_sp) failed, status=0x30/0x12: This error is observed when the drive fails to authenticate the pin several times in a row and the authority (SID, Admin, or User) is locked out.
Note: Do not run the nvmesed command unless you know the correct pins. If the authentication fails several times and results in this error, a valid pin cannot gain access until the drive is power cycled that can be disruptive.

# nvmesed -Q -l nvme0: This error is observed when nvme0 is not an SED-enabled drive and does not support security protocol.

Maintenance requirements for the SED

Consider the following maintenance requirements for the SED:

Namespace management: The same SED state is applicable to the entire drive and is shared by all namespaces, including the ones that will be created in the future. When namespaces do not exist, a drive can either enable or disable the SED. Certain namespace management operations cannot be performed on a locked drive. SED cannot be enabled or disabled for each namespace separately.

Format: The format operation (on any namespace) fails if the drive is locked.

Sanitize: The sanitize operation is used to purge all data on the drive. An SED-enabled drive turns off the sanitize command and the data can be purged by returning the drive to OFS.

Device Self-test (diagnostics): The device self-test is used for diagnostics. This command might fail if the drive is locked, depending on the drive vendor.

Moving a SED-enabled drive from another system: It is recommended to reinitialize the drive. In most cases, the drive can be reinitialized while preserving existing data if the SID and admin pins are known. The drive must be returned to OFS before the drive can be enabled for SED in an AIX operating system (if the data cannot be preserved).

Disabling Key Store

If the partition no longer owns or plans to own SED enabled drives, any PKS pins must be erased before the keystore can be disabled from the HMC. To disable the keystore, shut down the partition and set the keystore size to 0 by running the following commands:

# erase primary pin (-i 0)
nvmesed -K -l nvmeX -e -i 0


# erase alternate (secondary) pin (-i 1)
nvmesed -K -l nvmeX -e -i 1

Examples

The pins chosen for the user, admin, and SID authorities in the examples are AIX_PIN_USER, AIX_PIN_ADMIN, and AIX_PIN_SID. Pins from an earlier enablement, which may or may not be from an AIX environment, are identified as OLD_PIN_USER, OLD_PIN_ADMIN, and OLD_PIN_SID.

Note: It is recommended to, use 32-character pins during deployment.

To enable SED on a new drive, complete the following steps:
1. Verify that the drive is not SED-enabled by running the following command:
```
# nvmesed -Q -l nvme1
nvme1: SED_Enabled = No PKS pin, Drive Locked = No
```
  The command output displays that the PKS pin does not exist. If you run the same query command with the user pin that you want to use, the command output displays that the drive is not SED-enabled.
```
# nvmesed -Q -l nvme1 -u AIX_PIN_USER
nvme1: SED_Enabled = No, Drive Locked = No
```
2. Set the PKS pin by running the following command:
```
# nvmesed -K -l nvme1 -n AIX_PIN_USER
successfully set keystore pin (pri)
```
3. If you run the query command without specifying the PKS pin, the command output displays that the drive is not SED-enabled.
```
# nvmesed -Q -l nvme1
nvme1: SED_Enabled = No, Drive Locked = No
```
4. Enable self-encryption on the nvme1 drive by running the following command. When the operation is complete, the disk description is updated with the encrypted status. The data on the drive is preserved. In this example, only a single disk is present under the nvme1 (hdisk1) drive. However, if the disk is in use, the update in the encryption status cannot be determined until the disk is reconfigured or the system is rebooted.
```
# nvmesed -I -l nvme1 -s AIX_PIN_SID -a AIX_PIN_ADMIN -u AIX_PIN_USER
start_session(admin), hsn=0x1234, tsn=0x1024
MSID PIN, len = 32:83WX4EL50X2WYALH6KLWLM8MDLZN4FCK
Locking SP state = 8
max_ranges = 8
initialization completed successfully, drive encryption is enabled.
updating hdisk1...
# nvmesed -Q -l nvme1
nvme1: SED_Enabled = Yes, Drive Locked = No
# lsdev|grep hdisk1
hdisk1 Available 01-00 NVMe Encrypted 4K Flash Disk
```
To move an SED-enabled drive from another system to an AIX system, complete the following steps. In this example, you know the existing pins (OLD_PIN_XXX) from another system but the pins are different from the pins (AIX_PIN_XXX) that you want to use in the AIX system.
1. Query the self-encryption status by running the following command:
```
# nvmesed -Q -l nvme1
nvme1: SED_Enabled = Not Authorized, Drive Locked = No
```
  The command output reports "Not Authorized," which means that the user pin that is set on the drive does not match the AIX pin in the PKS. The query returns SED_Enabled=Yes only when the drive is SED-enabled.
2. To determine whether the self-encryption conforms with the AIX operating system, you need a valid pin to check various SED states in the drive. If the SED_Enabled field reports a value other than No, the drive might have some form of SED enablement.
```
# nvmesed -Q -l nvme1 -u AIX_PIN_USER
cannot start_session(locking_sp) to query, status=0x30/0x1
nvme1: SED_Enabled = Not Authorized, Drive Locked = No
```
  When such a drive is configured in the AIX system, the command output logs errors that indicate that the system might fail to unlock the drive since it does not have the correct pin.
```
LABEL: NVME_ERR4
Resource Name: nvme1
Description
NVME CONTROLLER SOFTWARE ERROR
...
ADDITIONAL INFORMATION
Drive has unknown SED enablement and may lock up
```
3. Re-initialize the drive by specifying the AIX pins for the AIX system in the following command. Even if the required pins are set for transferred drive, you must reinitialize the drive in the AIX system. You must use the existing SID and admin pins, but apply the AIX user pin.
```
# nvmesed -I -l nvme1 -s OLD_PIN_SID -a OLD_PIN_ADMIN -u AIX_PIN_USER
start_session(admin), hsn=0x1234, tsn=0x102f
MSID PIN, len = 32:83WX4EL50X2WYALH6KLWLM8MDLZN4FCK
Locking SP state = 9
locking is active, trying re-init...
reverted Locking SP back to inactive
Locking SP state = 8
max_ranges = 8
initialization completed successfully, drive encryption is enabled.
updating hdisk1...
```
  The output shows "locking is active," which indicates that the prior enablement is turned off and then re-activated.
4. Change the SID and admin pins to match the AIX pins by running the following commands:
```
# nvmesed -C -l nvme1 -s OLD_PIN_SID -n AIX_PIN_SID
change pin completed successfully.
# nvmesed -C -l nvme1 -a OLD_PIN_ADMIN -n AIX_PIN_ADMIN
change pin completed successfully.
# nvmesed -Q -l nvme1
nvme1: SED_Enabled = Yes, Drive Locked = No
```

To return the drive to OFS, run the following commands:

Note: All data is lost in the process. The drive shows it is no longer encrypted.

# nvmesed -O -l nvme1 -s AIX_PIN_SID
ofs completed successfully, drive is at factory default.
updating hdisk1...
# lsdev|grep hdisk1
hdisk1 Available 01-00 NVMe 4K Flash Disk
# nvmesed -Q -l nvme1
nvme1: SED_Enabled = No, Drive Locked = No

To revert an SED-enabled drive to a non-encrypted state and to disable pin-based protection, run the following command:

# nvmesed -R -l nvme1 -a AIX_PIN_ADMIN
revert completed successfully, drive encryption is disabled.
updating hdisk1...
# nvmesed -Q -l nvme1
nvme1: SED_Enabled = No, Drive Locked = No

This command preserves the existing data. A reverted drive retains the earlier SID pin but looses admin and user pins, whereas an OFS drive does not retain any pins. If you can try to re-initialize an OFS drive with a new set of pins by using the following command, the command reports an error because the SID pin (AIX_PIN_SID) is already set.

# nvmesed -I -l nvme1 -u AIX_PIN_NEW_USER -a AIX_PIN_NEW_ADMIN -s AIX_PIN_NEW_SID
start_session(admin), hsn=0x1234, tsn=0x10e8
MSID PIN, len = 32:83WX4EL50X2WYALH6KLWLM8MDLZN4FCK
start_session(admin_sp) failed, status=0x30/0x1
cannot start session as SID, try another SID pin or reset to OFS

You can use the pin with the -s flag in the re-initialization command or clear the pin on the drive by using the -C or -r flags and try to re-initialize an OFS drive.

# nvmesed -C -l nvme1 -s AIX_PIN_SID -r
reset sid pin successfully.
# nvmesed -I -l nvme1 -u AIX_PIN_NEW_USER -a AIX_PIN_NEW_ADMIN -s AIX_PIN_NEW_SID
start_session(admin), hsn=0x1234, tsn=0x10ed
MSID PIN, len = 32:83WX4EL50X2WYALH6KLWLM8MDLZN4FCK
Locking SP state = 8
max_ranges = 8
initialization completed successfully, drive encryption is enabled.
updating hdisk1...

To change the existing SID pin to the new SID pin, enter the following command:

# nvmesed -I -l nvme1 -u AIX_PIN_NEW_USER -a AIX_PIN_NEW_ADMIN -s AIX_PIN_SID
# nvmesed -C -l nvme1 -s AIX_PIN_SID -n AIX_PIN_NEW_SID

To move an SED-enabled drive with unknown pins from another system to the AIX system, complete the following steps:

Return the drive to OFS by running the running the following commands:

# nvmesed -O -l nvme1 -s AIX_PIN_SID
cannot start_session(admin_sp) to ofs, status=0x30/0x1
# nvmesed -O -l nvme1 -s OLD_PIN_SID
cannot start_session(admin_sp) to ofs, status=0x30/0x1

Locate the PSID pin that is printed on the drive label and run the following command:

# nvmesed -O -l nvme1 -p QLUVL1FD3N8299FTM31VFH0ACTPUDHCN
ofs completed successfully, drive is at factory default.
updating hdisk1...

Enable self-encryption as shown in Example 1.

To change the user pin for two SED-enabled drives where the user pin is set to AIX_PIN_USER as the PKS primary pin, complete the following steps:
1. Query the drives to determine the status of encryption and PKS primary and secondary pins by running the following commands:
```
# nvmesed -Q -l nvme1
nvme1: SED_Enabled = Yes, Drive Locked = No
# nvmesed -Q -l nvme2
nvme2: SED_Enabled = Yes, Drive Locked = No
# nvmesed -K -l nvme1 -d
Keystore pin (pri): set on Wed Jun 22 11:17:28 2022
Keystore pin (sec): erased
```
2. Set the PKS secondary pin to a new pin (AIX_PIN_NEW_USER) by running the following command:
```
# nvmesed -K -l nvme1 -n AIX_PIN_NEW_USER -i 1
successfully set keystore pin (sec)
```
  The PKS primary pin is still set to the old pin.
3. Change the user pin on each drive by running the following commands:
```
# nvmesed -C -l nvme1 -u AIX_PIN_USER -n AIX_PIN_NEW_USER
change pin completed successfully.
# nvmesed -C -l nvme2 -u AIX_PIN_USER -n AIX_PIN_NEW_USER
change pin completed successfully.
```
4. Change the PKS primary pin to the new pin by running the following command:
```
# nvmesed -K -l nvme1 -n AIX_PIN_NEW_USER -i 0
successfully set keystore pin (pri)
```
5. Clear the PKS secondary pin and verify that the pin is cleared and only the PKS primary pin is set by running the following commands:
```
# nvmesed -K -l nvme1 -e -i 1
successfully cleared keystore pin (sec)
# nvmesed -K -l nvme1 -d
Keystore pin (pri): set on Wed Jun 22 11:33:09 2022
Keystore pin (sec): erased
```
6. Query each drive by using new PKS pin and verify that the SED_Enabled field is set to Yes by running the following commands:
```
# nvmesed -Q -l nvme1
nvme1: SED_Enabled = Yes, Drive Locked = No
# nvmesed -Q -l nvme2
nvme2: SED_Enabled = Yes, Drive Locked = No
```
  If the old pin is used to query, the command fails and the SED_enabled field reports Not Authorized.

Limitation

SED-enabled drives are dependent on the PKS to save the keys to access SED drive content for that partition. Each partition can have its own unique PKS keys. However HMC allows multiple profiles for the same partition and hence the same PKS content. Thus, the HMC does not prevent multiple operating system instances (located on different boot disks in different profiles) from accessing the same PKS content. The keys might be shared and potentially modified. Sharing a partition's PKS for SED between different operating system instances is not supported. You can update the operating system to a newer level on an SED-enabled drive.