Purpose of domains

Edit online

When you configure your system on the Support Element (SE), you can specify how a logical partition (LPAR) uses coprocessors and accelerators. In this context, the Crypto Express cards support a concept of cryptographic domains. Each domain is protected by a master key, thus preventing access across domains and effectively separating the contained keys.

For information on how to configure domains, refer to zEnterprise System Support Element Operations Guide, which you can download from the IBM Resource Link.

There are two types of access to a cryptographic domain:

for usage of cryptographic functions
for management (control) of the domain, which includes the management of the master keys

A domain, which is assigned to an LPAR for usage access is called a usage domain of that LPAR. A domain, which is assigned to an LPAR for management (control) access is called a control domain of that LPAR. Every domain, which is a usage domain of an LPAR must also be a control domain of that LPAR, but not the other way round.

Usage domains

A logical partition's usage domains are domains in the coprocessors that can be used for cryptographic functions.

In Linux®, you can use the lszcrypt -b command to find out which usage domain is configured for that Linux system:

$ lszcrypt -b

ap_domain=0x1a
ap_max_domain_id=0x54
ap_interrupts are enabled
config_time=30 (seconds)
poll_thread is disabled
poll_timeout=250000 (nanoseconds)

Control domains

A logical partition's control domains are those cryptographic domains for which remote secure administration functions can be established and administered from this logical partition.

This logical partition's control domains must include its usage domains. So for each index that is selected in the Usage domain index list, you must select the same index in the Control domain index list.

But a logical partition's control domains can also include the control domains of other logical partitions. Assigning multiple logical partitions' control domains as control domains of a single logical partition allows using the partition to perform administrative functions from the TKE .

If you are using the Integrated Cryptographic Service Facility (ICSF) from z/OS, select at least one control domain with its matching usage domain. Refer to the ICSF documentation for information about ICSF basic operations.

If you are using a Trusted Key Entry (TKE) workstation to manage cryptographic keys, you can define your TKE host and the control domains for a logical partition. See Setting a master key on the Crypto Express EP11 coprocessor for more information.

Control domain exposure

For configuration and management purposes the TKE needs to know which control domains are configured on the system.

In Linux, use a sysfs attribute called ap_control_domain_mask in /sys/bus/ap/ to display the configured control domains. This information is set automatically from the device driver.

The attribute ap_control_domain_mask is read-only and contains a 32-byte field in hexadecimal notation, representing the installed control domain facilities. Each bit position represents a dedicated control domain. Thus, a maximum number of 256 domains could be addressed.

Example:

cat /sys/bus/ap/ap_control_domain_mask
0x0004000000000000000000000000000000000000000000000000000000000000

Byte: Meaning
1: domain 0-7
2: domain 8-15
...: ...

In this example, the control domain 13 was configured.