Purpose
Provides the cryptographic management of logical volumes (LV).
Syntax
hdcryptmgr action [-h] [flags] devicename
Description
Starting from IBM® AIX® 7.2 with Technology Level 5, you can run
the hdcryptmgr command by specifying the action parameter to
perform one of the following operations:
Displaying encryption settings
You can run the following actions with the hdcryptmgr command to display
encryption settings:
- showvg
- Syntax:
hdcryptmgr showvg [-h] [device]
- Displays the data encryption status of the specified volume groups. If you do not specify a
volume group, this command shows the encryption status of all the volume groups.
# hdcryptmgr showvg
VG NAME / ID ENCRYPTION ENABLED
EVG1 yes
INSTALLVG yes
rootvg no
- showlv
- Syntax:
hdcryptmgr showlv [-h] [-v] device
- Displays the data encryption status of a logical volume. You must specify the device name of a
volume group or a logical volume by using the -v flag. When you specify a
volume group, this command displays the data encryption status of all the logical volumes in the
volume group. When you specify a logical volume, this command displays the data encryption status of
the specified logical volume. If the data encryption capability is not enabled for the volume group,
a message, which indicates that encryption is not enabled on the volume group, is displayed.
# hdcryptmgr showlv vg00
NAME CRYPTO_STATUS %ENCRYPTED NOTE
lv00 unlocked 100
lv01 unlocked 100
lv03 not_enabled 0
lv04 locked 100
lv02 uninitialized 0
lv06 uninitialized n/a not_accessible
lv07 locked 100
fslv00 locked 1 encrypting
- showmd
- Syntax:
hdcryptmgr showmd [-h] [-v] device
- Displays encryption metadata for a specific logical volume, volume group, or physical volume.
You must specify the device name of a logical volume, volume group, or a physical volume. When you
specify a volume group, only the header and trailer encryption metadata of the specified volume
group are displayed. When you specify a physical volume, the metadata of encrypted logical volumes
are displayed even if the corresponding volume group is not varied on. When you specify a logical
volume, the entire encryption metadata of the specific logical volume is displayed.
# hdcryptmgr showmd ELV1
.....
..... Wed Jun 17 13:25:46 2020
..... Device type : LV
..... Device name : ELV1
.....
=============== B: LV HEADER ================
Version : 0
MasterKey : Defined
MasterKey size : 16 bytes
Encryption status : Fully encrypted
Data crypto algorithm : AES_XTS
=============== E: LV HEADER ================
============= B: LV AUTH METHODS ============
---- Index #0 -------------------------------
Method defined : yes
Method name : initpwd
Authentication type : Passphrase
Auto-auth method : no
MasterKey crypto algorithm : AES_GCM
---- Index #1 -------------------------------
Method defined : no
---- Index #2 -------------------------------
Method defined : no
---- Index #3 -------------------------------
Method defined : no
---- Index #4 -------------------------------
Method defined : no
---- Index #5 -------------------------------
Method defined : no
============= E: LV AUTH METHODS ============
- showconv
- Syntax:
hdcryptmgr showconv [-h]
- Displays the status of both active and stopped processes of logical volume that are being
converted.
# hdcryptmgr showconv
NAME TID/STATUS %ENCRYPTED DIRECTION START_TIME
lv03 29557045 3 plain2crypt Sun Feb 14 09:43:10 2021
fslv00 stopped/dirty 1 plain2crypt
Controlling authentication methods
The encryption function of the logical volume supports the following key-protection methods:
passphrase, key file, key server management solution (such as IBM Security Key Lifecycle Manager), and Platform Keystore (PKS). The passphrase and key file
protection methods require you to specify a password or a key file location manually. The key server
management and PKS protection methods can be used to automatically unlock and activate the encrypted
logical volume. For the key server authentication method to qualify as an automatic method, you must
either store the client certificate password in PKS or choose no password for the client
certificate. You can run the following actions with the
hdcryptmgr command to
control authentication methods:
- authinit
- Syntax:
hdcryptmgr authinit [-h] [-e algo_detail] [-n name] device
- Initializes the primary key and encryption metadata for an encrypted logical volume. For each
encrypted logical volume, the primary key and encrypted metadata must be initialized only once. A
first passphrase that is obtained from the key-protection method is added to the encryption metadata
of the LV. You can specify the following flags or values for this action parameter:
- -e
- Specifies the data encryption algorithm, mode, and key length. The valid values of the
-e flag are as follows:
- prompt
- Specifies that the encryption algorithm details will be prompted when the command runs.
- [algorithm]:[b|B][key_len][:w]
- Specifies the encryption algorithm details. The supported algorithms are Advanced Encryption
Standard XTS mode (AES-XTS) 128 bits or 256 bits. The character b refers to bits (default) of
the key, character B refers to bytes of the key, and the key_len variable
refers to the length of the key. The :w parameter overwrites the default values
of the volume group with the specified values. By default, when a volume group, in which encryption
is enabled, is created, the default encryption algorithm is AES-XTS 128 bits.
- -n
- Specifies a name for the key-protection method. Name can range from 1 to 15 characters and can
only contain the following characters: A through Z, a through z, 0 through 9, or "_" (the
underscore), "-" (the minus sign), or "." (the period). All other characters are considered
invalid.
- device
- Specifies the device name of the logical volume for which the key-protection method must be
initialized.
- authadd
- Syntax:
hdcryptmgr authadd [-h] [-t type [-m method_detail]] [-n name] device
- Adds an additional key-protection method to an encrypted logical volume in which a
key-protection method is already initialized. To activate the authentication method that you added
to an encrypted LV, the encrypted LV must be unlocked. This action parameter can
be specified with the following flags or values:
- -t
- Specifies the key-protection type. The valid values are
pwd,
keyfile, keyserv, and pks.
- -m
- Specifies any additional information about the key-protection method that might include the
following details:
- Input path to the authentication key file
- Key server ID in the
KeySvr Object Data Manager (ODM) class
- -n
- Specifies a name for the key-protection method. Name can range from 1 to 15 characters and can
only contain the following characters: A through Z, a through z, 0 through 9, or "_" (the
underscore), "-" (the minus sign), or "." (the period). All other characters are considered
invalid.
- device
- Specifies the device name of the logical volume for which the key-protection method must be
added.
If you do not specify the required flags or values when you run the hdcryptmgr
authadd command, you are prompted to specify the same. For information about registering
key server information, see the keysvrmgr command.
- authdelete or authdel
- Syntax:
hdcryptmgr authdelete [-h] [-t type [-m method_detail]] [-i index] [-n name] [-f] device
- Removes an initiated key-protection method. This action parameter can be
specified with the following flags:
- -t
- Specifies the key-protection type. The valid values are
pwd,
keyfile, keyserv, and pks.
- -m
- Specifies any additional information about the key-protection method that might include the
following details:
- Input path to the authentication key file
- Key server ID in the
KeySvr ODM class
- -i
- Specifies the index of the key-protection method that must be deleted.
- -n
- Specifies the name of the key-protection method that must be deleted. Name can range from 1 to
15 characters and can only contain the following characters: A through Z, a through z, 0 through 9,
or "_" (the underscore), "-" (the minus sign), or "." (the period). All other characters are
considered invalid.
- -f
- Specifies the force option. This flag bypasses the authentication method checks to remove the
key-protection method.
- device
- Specifies the device name of the logical volume for which the key-protection method must be
deleted.
Only one key-protection method can be removed at a time. If you know the correct index or
name of the key-protection method, you can specify the key-protection method by using the
-i or -n flags. You can use the -t
and -m flags to filter the list of existing key-protection methods. If multiple
entries match the specified criteria, you are prompted to choose the key-protection method that must
be removed.
Before the key-protection method is removed, the validity of the key-protection
method is checked, unless the -f flag is used. You must authenticate to the LV
with the selected key-protection method.
Note: Ensure that the logical volume has at least a
passphrase key-protection method after performing the authdelete
operation.
- authunlock or authunl
- Syntax:
hdcryptmgr authunlock [-h] [-t type [-m method_detail]] [-A] device
- Authenticates to the encrypted LV and unlocks the encrypted logical volumes. This
action parameter can be specified with the following flags or values:
- -A
- Authenticates to the encrypted LV by using the automatic key-protection methods that do not
require any user inputs. You can use this flag at a volume group (VG) level only if the VG uses
automatic key-protection methods, such as a key server management solution or PKS.
- -t
- Specifies the type of the key-protection method. The valid values are
pwd,
keyfile, keyserv, and pks.
- -m
- Specifies any additional information about the key-protection method that might include the
following details:
- Input path to the authentication key file
- Key server ID in the
KeySvr ODM class
- device
-
Specifies the device name of the logical volume which must be authenticated and then the
key-protection method must be unlocked. You must specify this value with the -A
flag.
When you specify an LV device name, you can specify the key-protection method by using the
-t and -m flags. If more than one key-protection methods
meet the criteria, you are prompted to select a specific key-protection method.
Note: For encrypted logical volumes that use key server authentication methods during the boot
operation to decrypt the logical volume, the server or the client certificate must be located in the
/etc directory or in the file systems that are mounted early in the boot
operation sequence.
- authcheck or authchk
- Syntax:
hdcryptmgr authcheck [-h] [-t <type> [-m <method_detail>]] [-i <index>] [-n <name>] <device>
- Checks the validity of an authentication method. This action parameter can be
specified with the following flags or values:
- -h
- Displays help information.
- -t
- Specifies the type of the key-protection method. The valid values are
pwd,
keyfile, keyserv, and pks.
- -m
- Specifies any additional information about the key-protection method that might include the
following details:
- Input path to the authentication key file
- Key server ID in the
KeySvr ODM class
- -i
- Checks the authentication of only the specified index. Authentication type is automatically
forced according to the selected index.
- -n
- Specifies the name of the key-protection method that must be checked. Name can range from 1 to
15 characters and can only contain the following characters: A through Z, a through z, 0 through 9,
or "_" (the underscore), "-" (the minus sign), or "." (the period). All other characters are
considered invalid.
- device
- Specifies the device name of the logical volume that must be checked.
Managing PKS keys
The platform keystore (PKS) is a secure key-protection method that is available in IBM
PowerVM® firmware of the IBM
Power® System E950. You can add the PKS key-protection method
to an encrypted LV. You can use the following action parameters to manage the PKS
keys for authentication.
- pksshow
- Syntax:
hdcryptmgr pksshow [-h]
- Displays the logical volume IDs that are associated with the PKS keys and the status of the PKS
keys. The LV IDs that are stored in both the PKS and in the LV metadata are displayed.
# hdcryptmgr pksshow
PKS uses 317 bytes on a maximum of 65536 bytes.
PKS_Label (LVid) Status
00fb293100004c0000000174c0a994b7.1 VALID
00fb293100004c0000000174c0a994b7.2 UNKNOWN
00fb293100004c0000000174c0a994b7.3 UNKNOWN
PKS_Label (objects)
ksvr:gpfs-pw-t2
- pksclean
- Syntax:
hdcryptmgr pksclean [-h] lvid
- Removes an invalid key from the PKS. You must specify the logical volume ID that is associated
with the invalid key that you want to remove. This command must be used to remove the keys that are
listed in the hdcryptmgr pksshow command output with the status as O.
- pksexport
- Syntax:
hdcryptmgr pksexport [-h] -p ExportFile device
- Exports the PKS keys into the specified file. If you specify an LV device name, the PKS key that
is associated with the specified LV is exported. If you specify a VG device name, all PKS keys that
are associated with the logical volumes in the volume group are exported.
- pksimport
- Syntax:
hdcryptmgr pksimport [-h] -p ExportFile [device]
- Imports the PKS keys into the specified file. If you specify an LV device name, the PKS key that
is associated with the specified LV is imported. If you specify a VG device name, all PKS keys that
are associated with the logical volumes in the volume group are imported. If you do not specify a
device name, all PKS keys are imported.
Converting the encryption status of the logical volume
You can convert a regular logical volume to an encrypted logical volume, and vice versa. You can
perform this conversion operation only on the logical volume that is active and online.
Warning: You must back up your data before you run the following conversion commands.
You can use the following
action parameters:
- plain2crypt
- Syntax:
hdcryptmgr plain2crypt [-h] [-e algo_detail] [-n name] [-f] device
- Enables encryption in a logical volume, configures the encryption settings, and encrypts the LV
data. This action parameter can be specified with the following flags and values:
- -e
- Specifies the data encryption algorithm, mode, and key length. The valid values of the
-e flag are as follows:
- prompt
- Specifies that the encryption algorithm details will be prompted when the command runs.
- [algorithm]:[b|B][key_len][:w]
- Specifies the encryption algorithm details. The supported algorithms are Advanced Encryption
Standard XTS mode (AES-XTS) 128 bits or 256 bits. The character b refers to bits (default) of
the key, character B refers to bytes of the key, and the key_len variable
refers to the length of the key. The :w parameter overwrites the default values
of the volume group with the specified values. By default, when a volume group, in which encryption
is enabled, is created, the default encryption algorithm is AES-XTS 128 bits.
- -n
- Specifies a name for the key-protection method. Name can range from 1 to 15 characters and can
only contain the following characters: A through Z, a through z, 0 through 9, or "_" (the
underscore), "-" (the minus sign), or "." (the period). All other characters are considered
invalid.
- -f
- Specifies the force option. If you do not use this flag, the hdcryptmgr
command prompts you to confirm that data have been backed up. The force option suppresses this
prompt.
- device
- Specifies the device name of the logical volume for which the encryption status must be
converted.
- crypt2plain
- Syntax:
hdcryptmgr crypt2plain [-h] [-f] device
- Decrypts the encrypted data of the specified logical volume and disables the encryption status
of the specified logical volume. This action parameter can be specified with the
following flags and values:
- -f
- Specifies the force option. If you do not use this flag, the hdcryptmgr
command prompts you to confirm that data have been backed up. The force option suppresses this
prompt.
- device
- Specifies the device name of the logical volume for which the encryption status must be
converted.
Commands and function restrictions for encrypted LV
For more information about the logical volume commands or functions that are not supported when
the LV is encrypted, see the Limitations section in Encrypting logical volumes.
Examples
Scenario: Creating an encrypted logical volume with the
passphrase key-protection method
- Create a volume group in which encryption is enabled.
# mkvg -k y hdisk1 hdisk2
vg00
- Create an encrypted LV with a size of 32
MB.
# mklv -k y vg00 32M
mklv: Please run :
# hdcryptmgr authinit lvname [..] to define LV encryption options.
lv00
- Initialize the encryption configuration on the logical volume by using a primary key and the
passphrase key-protection method.
# hdcryptmgr authinit -n default lv00
Enter Passphrase:
Confirm Passphrase:
Password authentication method added successfully
Scenario: Creating a file system in an encrypted LV
- Create volume group in which encryption is enabled, and then create a logical volume with a size
of 32 MB, and then initialize the encryption configuration for the logical
volume.
# mkvg -k y hdisk1 hdisk2
vg00
# mklv -t jfs2 -k y vg00 32M
mklv: Please run :
# hdcryptmgr authinit lvname [..] to define LV encryption options.
fslv00
# hdcryptmgr authinit -n default fslv00
Enter Passphrase:
Confirm Passphrase:
Password authentication method added successfully
- Create a file system in the encrypted logical volume similar to creating it in a regular logical
volume.
# crfs -v jfs2 -d fslv00 -m /mnt/myfs -A no
File system created successfully.
32560 kilobytes total disk space.
New File System size is 65536
Scenario: Authenticating to a logical volume in which encryption is enabledWhen the
volume group is varied off or the system is restarted, the authentication to the encrypted LV
expires. You must authenticate to the encrypted LV to access its data. You must use the configured
key-protection method for the encrypted LV. To authenticate an encryption-enabled LV, complete the
following steps:
- Vary on the VG.
# varyonvg vg00
- Authenticate by using the passphrase key-protection
method.
# hdcryptmgr authunlock -t pwd fslv00
Enter Passphrase:
Password authentication succeeded
Files
- /usr/sbin/hdcryptmgr
- Contains the hdcryptmgr command.