Crypto parameter descriptions

Edit online

The following crypto options in the image profile can be specified.

Assigned domains:

The assigned domains table displays the control domains and control and usage domain indexes which can be modified in the logical partition.

Control domain

The logical partition's control domains are those cryptographic domains which remote secure administration functions can be established and administered from the logical partition when set up as the TCP/IP host for the TKE Workstation.

If you are setting up the host TCP/IP in this logical partition for communicating with the TKE Workstation, the partition will be used as a path to this and the other domains' keys. Indicate all the domains you want to access, including this partition's own domain, from this partition as control domains.

Note: You can manage both master keys and operational keys from a TKE Workstation.

For more TKE Workstation information, refer to the z/OS Cryptographic Services ICSF TKE Workstation User's Guide.

Control and Usage Domain

The logical partition's control and usage domains are domains in the cryptos that can be used for cryptographic functions. The usage domains cannot be removed if the crypto is online. A logical partition's control domains can include the usage domains of other logical partitions. Assigning multiple logical partitions usage domains as control domains of a single logical partition allows using it to control their software setup.

If running z/OS®, one of the usage domain index(es) selected must match the domain number entered in the Options dataset when starting this partition's instance of ICSF. As of z/OS 1.2 the usage domain specification in the Options dataset is only required if multiple usage domain index(es) are selected.

If running z/VM® in a logical partition with guests, such as Linux® or z/OS, a range of usage domain indices should be selected when assigning access to the cryptographic accelerator or coprocessor. A range will allow more than one guest to have dedicated or shared access to the cryptographic queues. For further information, see the z/VM CP Planning and Administration and z/VM Running Guest Operating Systems documents.

The Usage Domain assignment, in combination with the Cryptographic Number must be unique across all partitions defined to the CPC. If you assign Usage Domain 1 on Crypto Adapter 1 to LP 1 and LP 11, then the first of those LPs to be activated is given access to that Usage Domain and the second LP cannot be activated because that Usage Domain is already assigned and no longer available.

The maximum number of LPs that can have a cryptographic adapter assigned depends on how many cryptographic adapters are available. Each cryptographic adapter can support up to 16 Usage Domains, so the maximum number of LPs that can be assigned cryptographic hardware is 16, the number of adapters. In this case, each LP would be assigned one and only one adapter. There would be no additional crypto capacity for these LPs nor would there be any redundancy in case of a failure on one of the crypto devices. The Crypto Express feature has a single adapter available.

LPs that are predominately for development or testing may only need a single adapter assigned to provide functionality. Production LPs will likely need at least two adapters assigned for redundancy and may need multiple adapters assigned to provide acceptable performance and throughput of the crypto workload.

The type configuration of the adapter (coprocessor, accelerator or EP11 mode) means that the adapter can only be used in that mode. If you only have a small EP11 mode workload on a single LP, configuring an adapter in EP11 mode means that the adapter will only be used for EP11 mode for that particular LP. If you need two EP11 adapters (for redundancy) those adapters will be unavailable for any other work.

Consider an environment where you have multiple LPs supporting various types of workload (coprocessor, accelerator and EP11 mode) and the assignment of adapters and Usage Domains across those LPs.

You can have Crypto Express hardware installed. The following example includes each type of device. Your configuration will likely be much simpler, probably with only one type of adapter, or at most two types.

Table 1. Example Selection of Usage Domain Assignment
Feature Adapter Crypto Configuration Crypto Number Crypto Label
Crypto Express 1 X - Coprocessor 06 X06
Crypto Express 1 A- Accelerator 07 X07
Crypto Express 1 P-EP11 08 P08
Crypto Express 1 P-EP11 09 P09
Note: For availability reasons, it is recommended that at least two cryptographic adapters with the same capability be assigned to each partition that executes cryptographic operations. Because accelerators do not contain any internal security data (cryptographic keys), all accelerators are equivalent. Coprocessors and EP11 Coprocessors will contain cryptographic keys and it is recommended that at least two coprocessors with the appropriate domains and cryptographic keys be assigned to a logical partition (LP) that requires secure key operations.

There are multiple LPs which require access to crypto hardware. These include LPs that will only perform SSL workload and require access only to accelerators. Some LPs only need access to secure key coprocessors. These LPs may perform SSL workload, but volume is sufficiently low that work can be performed on the coprocessor and an accelerator is not required. Other LPs perform both secure key work and sufficient SSL workload that also assigning an accelerator makes sense. There is also a need for a VM environment with multiple guests sharing access to cryptographic adapters. There are multiple LPs that will be performing EP11 workload.

Table 2. Example Selection of Usage Domain Assignment
LP and Crypto Use Usage Domain Assignment Adapter Assignment Second Assigned Adapter (for capacity and/or redundancy)
PRODSSL0 Prod SSL only UD=0 A00 A04
PRODSSL0 Prod SSL only UD=1 A00 A04
PRODCOM2 Prod SSL & secure key UD=2 A00 & X02 A04 & A05
PRODSSL3 Prod SSL only UID=0 A01 A07
PRODSSL4 Prod SSL only UD=3 A00 A01
PRODSSLF Prod SSL only UD=3 A04 A07
PRODCOM3 Prod SSL & secure key3 UD=4 A00 & X05 A04 & X06
TESTSEC1 secure key only UD=5 X02 X05
PRODSEC2 secure key only UD=6 X03 X06
TESTSSL9 Test SSL only UD=6 A07 A04
TESTSEC1 secure key only UD=5,12 X03 X06
DEVVM UD=7,8,9,10 X05  
TESTPKCS UD=0 P08 P09
For example:
  • The LP PRODSSL0 only performs SSL work and therefore only needs an accelerator. It is assigned A00 (A for Accelerator and Crypto Number 00). And for redundancy, it is also assigned A04 (A for Accelerator and Crypto Number 04) to provide additional capacity and/or redundancy in case the first card fails.

    This LP is also assigned Usage Domain 0. Even though an accelerator does not have master keys loaded, it is still assigned a Usage Domain. This means that Usage Domain 0 on cryptographic adapters 00 and 04 are no longer available to be used by any other LPs.

  • The PRODSSL1 LP also only performs SSL workload so it can be assigned the same two adapters (A00 and A04), however this LP will be assigned Usage Domain 1.
  • The PRODSSL3 is a third LP that only performs SSL workloads and therefore only needs to have an accelerator assigned. We assign A07 (on a Crypto Express) to this LP. This LP is assigned Usage Domain 0.
    Note: This is not in conflict with the PRODSSL0 LP, which also uses Usage Domain 0, but on different crypto adapters.
  • The PRODCOM2 has a different workload requirement. It performs SSL workload and will benefit from having an accelerator assigned, but it also performs secure key operations and must have a coprocessor assigned as well. It is also assigned to use A00 and A04. Iit is sharing the same accelerator as PRODSSL0 and PRODSSL1, but with a different Usage Domain.
  • The PRODSSLF is another LP with only SSL workload. It has been assigned A07 (Crypto Express) and uses Usage Domain 3 on those two cards. Even though PRODSSL4 and PRODSSLF are both using Usage Domain 3, they use it on two different adapters, so there is no conflict.
  • The PRODCOM3 LP is similar to PRODCOM2 in that it has combined SSL workload and secure key work, so it is assigned X06 (Crypto Express) for coprocessors. It is assigned Usage Domain 4 on these cards.
  • The PRODSEC1 is a secure key only partition. If it does any SSL work, it's a trivial amount that can be handled by the secure key cards without impacting the other secure key work going on in the LP.
  • The PRODSEC2 is a secure key only partition, possibly running in a Sysplex with PRODSEC1. It is assigned Usage Domain 6 on X06 (Crypto Express). If these two LPs are using the same ICSF repositories, the same master keys will be loaded into both Usage Domains.
  • The TESTSSL9 is an LP for testing new applications that only require System SSL. It is assigned A07 (Crypto Express). It is assigned two accelerators not for throughput, but for redundancy. Testing can continue even if one of the two accelerators should have a problem. It is assigned Usage Domain 6 on these cards.
  • The TESTSEC1 LP is primarily intended for testing applications that require secure key technology. It has two Usage Domains assigned, but only one can be used at a time. It is assigned two coprocessors, and X06 (Crypto Express), and it will normally use Usage Domain 5 on those cards. However, in an emergency, this LP can also be IPL'd as a production LP to provide additional capacity for the Sysplex that includes PRODSEC1 & PRODSEC2. That is, if the workload on the Sysplex exceeds the capacity of those two LPs, then this test LP could be shut down and another copy of the production LP IPL'd here. In this configuration, it would still use X03 and X06, however ICSF would point to Usage Domain 12 and the same key repositories as PRODSEC1 and PRODSEC2. This Usage Domain would contain the same master key as used by PRODSEC1 and PRODSEC2, so it can access the key material in the shared ICSF repositories.
  • The DEVVM LP is a development LP that provides multiple guest operating systems, which require access to a secure key device. The LP is also assigned 4 Usage Domains (7 through 10). Presumably there will be four guests running in this LP, each assigned there own unique Usage Domain via the VM User Directory. Since this environment is only for development, there is no backup crypto adapter assigned. If X05 is unavailable, secure key work will stop on these guests.
  • The TESTPKCS LP is for testing new PKCS #11 applications running on the EP11 coprocessor. It is assigned to use P08 (Crypto Express) and P09 (Crypto Express) and Usage Domain 0 on these coprocessors. Once these PKCS #11 applications have been sufficiently tested and are ready for production, there would be another LP defined, PRODPKCS, which would also be assigned P08 and P09, but would have a different Usage Domain assigned.

Assigned cryptos

The assigned cryptos table displays the cryptographic candidate list and cryptographic candidate and online list which can be modified in the logical partition.

Candidate

The Candidate identifies the cryptographic numbers that are eligible to be accessed by this logical partition. Select from the list the number(s), from 0 to 15, that identify the coprocessor or accelerator to be accessed by this partition.

When the partition is activated, an error condition is not reported if a cryptographic number selected in the Assigned Cryptos table is not installed in the system. Selecting a cryptographic number that is not installed prepares the settings in the active partition in the event that you wish to nondisruptively install the crypto in the future.

A Crypto Express contains single adapter which can be configured as a CCA coprocessor, EP11 coprocessor, or an accelerator. The default configuration is CCA coprocessor. A crypto adapter can be shared across all partitions utilizing usage domains.

It is possible to select all 16 candidate numbers (0-15) even before a crypto feature is installed. When a new crypto feature is installed and its cryptographic number(s) have been previously selected in the Candidate list of an active partition, it can be configured on to the partition from the Support Element using the Configure On/Off task.

Selecting all the values will not cause a problem if you have 16 or fewer partitions in your configurations that will be using the Crypto Express feature. If you have more than 16 partitions that require access to cryptographic coprocessors or accelerators, carefully assign the cryptographic numbers across the partitions in conjunction with unique Usage Domain selections.

Table 3. Example Selection of Crypto Numbers
Feature Adapter Crypto Configuration Type Crypto Number
Crypto Express8S/7S 1 1 Accelerator A 00
1 Accelerator A 01
Crypto Express8S/7S 2 1 Coprocessor X 02
1 Coprocessor X 03
Crypto Express8S/7S 3 1 Accelerator A 04
1 Coprocessor X 05
Crypto Express8S/7S 4 1 Coprocessor X 06
1 Accelerator A 07
It is recommended that at least two cryptographic adapters of the same type and capability be assigned to each partition that executes cryptographic operations. Because accelerators do not contain any internal security data (cryptographic keys), all accelerators are equivalent. coprocessors, on the other hand, will contain cryptographic keys and it is recommended that at least two coprocessors with the appropriate domains and cryptographic keys be assigned to a logical partition (LP) that requires secure key operations.
Table 4. LP & crypto assignments
LP & Crypto Use Usage Domain Assignment Logical Partition Assignment Backup Required? Specify 2nd Logical Partition
ACME0 Prod SSL only1,2 UD=0 A00 A04
ACME1 Prod SSL only1 UD=1 A00 A04
ACME2 Prod SSL & secure UD=2 A00 & X02 A04 & X05
ACME3 Prod SSL only2 UD=0 A01 A07
.......... SSL only UD=3...10 A00 A01
ACMEF Prod SSL only UD=0 A04 A07
ACM17 Prod SSL & secure3 UD=4 A00 & X05 A01 & X06
ACM18 Test SSL & secure3 UD=5, 24 A00 & X02 A04 & X05
ACM19 Test SSL only UD=6 A07 A04
ACM5VM Prod VM UD=7, 8, 9, 10 A07 & X05  
Notes:
  1. LPs ACME0 and ACME1 both use Accelerator cards A00 and A04, however, they use two different Usage Domains on these cards.
  2. LPs ACME0 and ACME3 both use Usage Domain 0, but they use them on different accelerator cards, A00/A04 and A01/A07.
  3. LPs ACM17 and ACM18 both use Crypto Coprocessor X05, but they use different Usage Domains on those cards, so there is no conflict.
  4. ACM18 has two Usage Domains assigned, but only one can be used at a time. Normally, this TEST LP will provide SSL and Secure support for the Test environment using Usage Domain 5 on crypto accelerator cards A00 and A01, and crypto coprocessor card X02. By defining this LP with access to Usage Domain 2 it can be a backup LP for ACME2. If and when there is a problem with LP ACME2, that operating system can be IPL'd in this LP, with the ICSF started task pointing to UD=2, and it will be able to access the cryptographic keys for ACME2, which are stored in Usage Domain 2 on X05.
Note: It is important to make the correct crypto number assignments from the Assigned Cryptos table for each of these logical partitions to avoid assignment conflicts.
If the customer plans to use ICSF or the optional cryptographic hardware, the CP Crypto Assist functions (CPACF DES/TDES) must be enabled. Many IBM® products will take advantage of the cryptographic hardware using ICSF, so enabling CPACF is recommended. See the z/OS ICSF Administrator's Guide and the z/OS ICSF System Programmer's Guide for complete information.
Candidate and Online

The Candidate and Online identify the cryptographic numbers that are automatically brought online during logical partition activation. The cryptographic numbers selected in the assigned table must also be selected in the Candidate.

When the logical partition activation is complete, installed Cryptographic features that are in the Candidate column but not in the Candidate and Online Column are in a configured off state (Standby). They can be later configured on to the partition using the Configure On/Off task.

When the partition is activated, an error condition is not reported if the cryptographic number selected from the assigned table is not installed in the system. The cryptographic number is ignored and the activation process continues.

If a cryptographic number selected from the assigned cryptos table has been configured off to the partition, it is automatically configured back on during the next partition activation.