chzcrypt - Modify the zcrypt configuration

Edit online

6.18 LPAR mode z/VM guest KVM guest

Use the chzcrypt command to configure cryptographic devices that are managed by zcrypt and modify zcrypt's AP bus attributes.

In sysfs, AP queues are listed as children of a cryptographic device with a name of the form: <card>/<adapter_id>. For example, if cryptographic devices with the adapter IDs 00 and 02 are selected, and the domain IDs 0002, 0003 and 000e have been configured, then the following cryptographic devices and AP queues are defined to Linux®: 
/sys/devices/ap/card00
/sys/devices/ap/card00/00.0002
/sys/devices/ap/card00/00.0003
/sys/devices/ap/card00/00.000e
/sys/devices/ap/card02
/sys/devices/ap/card02/02.0002
/sys/devices/ap/card02/02.0003
/sys/devices/ap/card02/02.000e

Setting a cryptographic device online or offline with chzcrypt affects its AP queues.

chzcrypt syntax


1  chzcrypt
1 
2.1 --config-on
2.1 --config-off
2.1 -a
2.1 + <device_ID>
1 
2.1 -e
2.1 -d
2.1 -a
2.1 + 
2.2.1 <device_ID>
2.2.1 <ap_queue>
1 
2.1 -se-associate<secret><ap_queue>
2.1 -se-bind<ap_queue>
2.1 -se-unbind<ap_queue>
2.1 -p
2.1 -n
1 -c <timeout>
1 -t <time>
1 -q <domain>
Where:
--config-on
For Linux in LPAR mode, configures cryptographic devices and all associated AP queues for the LPAR.
--config-off
For Linux in LPAR mode, sets the LPAR configuration status of cryptographic devices and all associated AP queues to not configured, displayed as deconfig by lszcrypt and stopped standby on the SE or HMC. As a result, the devices and all associated AP queues are set offline in Linux.
-e or --enable
sets the given cryptographic devices and AP queues online in Linux. Cryptographic devices can be set online only if they are configured at the LPAR level (see --config-on).
-d or --disable
sets the specified cryptographic devices and AP queues offline in Linux.
-a or --all
can be combined with the -e, -d, --enable, --disable, --config-on, or --config-off option to act on all available cryptographic devices.
<device_ID>
specifies a cryptographic device. A cryptographic device can be specified either in decimal notation or hexadecimal notation with a '0x' prefix.
<ap_queue>
specifies an AP queue in hexadecimal notation, omitting the '0x' prefix.
-se-associate <secret><ap_queue>
On a KVM guest running in secure-execution mode: Associates the secret with the specified AP queue. The secret is given as a numeric index value referring to the list of secrets known to the ultravisor for this guest. The AP queue needs to be successfully bound to this guest before an associate action can be performed.
-se-bind <ap_queue>
On a KVM guest running in secure-execution mode: Binds the specified AP queue to the guest.
-se-unbind <ap_queue>
On a KVM guest running in secure-execution mode: Unbinds the specified AP queue from the guest.
-p or --poll-thread-enable
enables zcrypt's poll thread. You cannot use the poll thread in environments that support AP adapter interrupts, see AP adapter interrupts.
-n or --poll-thread-disable
disables zcrypt's poll thread.
-c <timeout> or --config-time <timeout>
sets configuration timer for rescanning the AP bus to <timeout> seconds.
-t <time>or --poll-timeout=<time>
sets the high-resolution polling timer to <time> nanoseconds. To display the value, use lszcrypt -b.
-q or --default-domain <domain>
changes the default domain. Specify the domain as either a hexadecimal or decimal value.
Important: Be sure to enter an existing domain. The Trusted Key Entry (TKE) workstation does not find the cryptographic adapters if a non-existing domain is entered here. All CCA applications use the default domain, and do not work correctly if the specified domain does not exist.
-h or --help
displays help information for the command. To view the man page, enter man chzcrypt.
-v or --version
displays version information.

Examples

These examples illustrate common uses for chzcrypt.

  • To configure cryptographic devices with the adapter IDs 0, 1, 4, 5, and 12 and their associated AP queues for the LPAR (in hexadecimal notation): 
    # chzcrypt --config-on 0x00 0x01 0x04 0x05 0x0C
  • To set the cryptographic devices with the adapter IDs 0, 1, 4, 5, and 12 and their associated AP queues online (in hexadecimal notation): 
    # chzcrypt -e 0x00 0x01 0x04 0x05 0x0C
  • To set all available cryptographic devices, including all AP queues, offline: 
    # chzcrypt -d -a
  • To set the AP queue defined by adapter ID 00 and domain 77 (0x4d) offline: 
    # chzcrypt -d 00.004d
  • To set the configuration timer for rescanning the AP bus to 60 seconds and disable zcrypt's poll thread: 
    # chzcrypt -c 60 
# chzcrypt -n
  • To change the default domain to 77 (0x4d): 
    # chzcrypt -q 0x4d