Setting a master key on the Crypto Express EP11 coprocessor

Setting up the TKE environment

For a Crypto Express EP11 coprocessor, a TKE workstation is required to perform certain key management functions.

A TKE version 7.3 is required to detect EP11 adapters and set and manage wrapping keys (master keys) correctly.

To use the EP11 functions of the TKE, the EP11 library (libep11.so) and the TKE daemon (ep11TKEd) must be installed. The ep11TKEd daemon is used for receiving messages from a Trusted Key Entry workstation and for routing those messages to the specified Crypto Express EP11 coprocessor (CEX*P card).

service ep11TKEd start

systemctl start ep11TKEd.service

The ep11TKEd TKE daemon uses the EP11 host library to communicate with a CEX*P EP11 coprocessor and is listening on port 50004 for administrative TKE commands. These commands are translated into ioctl commands to talk to the zcrypt device driver.

Create and initialize an EP11 smart card

Step 1

As a prerequisite, you need a valid CA (Certificate Authority) smart card to be authorized to create EP11 smart cards (see Step 4).

The Trusted Key Entry console automatically loads on start-up with a set of commonly used tasks. After the TKE console started, the initial Trusted Key Entry Console window appears.

This initial window provides access to applications and utilities available on the TKE workstation.

Step 2

Click the Smart Card Utility Program application as shown in Figure 1.

When you open a TKE application or utility, you must sign on with a profile that is on the TKE workstation crypto adapter. Therefore, depending on how you have initialized your environment, the Crypto Adapter Logon window is displayed with profile IDs that represent a single or group passphrase logon. The individual or group profile you choose must have enough authority to do the functions that are performed by the application or utility. The steps described here use the default TKEADM user name.

Step 3

After a successful log-on, the Smart Card Utility Program opens and shows a table for each smart card reader for all detected plugged-in smart card types. The tables are still empty at this point in time, because the EP11 smart card is not yet created. The missing information is provided during the process of initializing and personalizing the smart card as described in the remainder of this topic.

To continue, select Initialize and enroll EP11 smart card from the EP11 Smart Card pulldown choice.

Step 4

The Smart Card Utility Program prompts you to insert the CA smart card into the smart card reader 1 and then press the OK button. For detailed information, read the TKE documentation.

Step 5

As next step, the Smart Card Utility Program prompts you to insert a smart card to be initialized as an EP11 smart card into smart card reader 2 and then press the OK button.

Step 6

The Smart Card Utility Program initializes and builds the EP11 smart card and displays a message when the creation was successful. This may take some time. When the processing is finished, you see the new EP11 card information in an updated view from Figure 3 (lower part) as shown in Figure 6.

Step 7

The Smart Card Utility Program now goes back to the window shown in Figure 3, where you now select item Personalize EP11 smart card from the EP11 Smart Card pull-down choice.

To personalize the EP11 smart card, the Smart Card Utility Program prompts you to enter a PIN to be used for this smart card on the smart card reader PIN pad. The PIN must be entered twice for confirmation.

The TKE also prompts you for an optional description for the smart card.

The Smart Card Utility Program informs you of a successful personalization of the EP11 smart card. This smart card now contains a certificate signed by the CA authority, and a PIN to access the smart card.

The EP11 smart card is needed whenever you want to set a new master key on the adapter.

Step 8

Repeat Step 3 through Step 7 to create the second EP11 smart card.

Creating a master key on the TKE workstation

Read an outline of the required steps for creating a master key and installing it on the CEX*P adapter. For detailed information about how to use the TKE workstation, refer to z/OS Cryptographic Services ICSF Trusted Key Entry Workstation User's Guide.

Step 1

Step 2

Click the Trusted Key Entry application as shown in Figure 9. Then proceed with the logon procedure as described in Step 2 of Create and initialize an EP11 smart card.

Step 3

Select the default profile ID TKEUSER, click OK, and in the upcoming Passphrae Logon dialog for this profile, logon with the passphrase associated to TKEUSER.

Step 4

The Trusted Key Entry main window is displayed (Figure 10). Open the context menu for hosts and select action Create Host.

Step 5

In the Create New Host dialog, enter the required values of the host for which you want to create the master key. It is assumed that this host is a Linux® on Z system running the ep11TKEd TKE daemon. Press OK to return to the Trusted Key Entry main window.

Step 6

The new host is visible now within the list of host IDs.

Before you continue to work on the new host, ensure the following:

• The ep11TKEd TKE daemon is started on the host.
• The TKE has connectivity to the host.

Then open the new host's context menu and select action Open Host.

Step 7

If you accepted the default settings when installing and configuring the ep11TKEd TKE daemon as recommended, you are prompted by the TKE workstation to log on to the selected host with the appropriate Linux user credentials. Do not forget to activate the Enable Mixed Case Passwords check box (see Figure 13). This user must be a member in the ep11tke group defined in /etc/group of the system.

If you specified CipherMode=None in the TKE daemon configuration file /etc/ep11/ep11tked.conf, the values that you enter as the user ID and password are not relevant, because they are not validated. You just need to press the OK button.

For details about configuring the ep11TKEd TKE daemon, read Installing the host part of the EP11 library or refer to file README_TKED.md coming with the EP11 installation package.

Step 8

The TKE now requests a verification of any new crypto adapter. Press the Yes button to continue.

Step 9

The Crypto Modules list now displays the available adapters. In the sample from Figure 15, there is just one adapter available with host ID p2314002. Select a crypto adapter of your choice and trigger action Open Crypto Module from its context menu.

Step 10

The Crypto Module Administration window for the selected crypto adapter opens. Now you can start to configure the domains. Click on the Domains tab at the top. On the right side, the window now shows an Index tab for each available domain. Choose one of these indexes and select the Domain Administrators tab at the bottom of the window to add a new administrator role. In this documentation, the configuration is outlined for the domain with index 13. For detailed information on domain configuration, refer to the TKE documentation.

Step 11

Now create a user ID with administrator role in the Crypto Module Administration window for the selected crypto adapter. Open the context menu by right-clicking into the white space of the window. Select action Add Administrator.

From the opening Select Source window, TKE requests certain information from the previously CA prepared smart card that contains the administrator key and certificate.

After a successful authentication on the smart card reader, the TKE workstation imports the administrator key and certificate and creates an administrator profile.

Step 12

Now select the Domain Attributes tab at the bottom of the window. This selection opens the window that is shown in Figure 19 where you can specify the required permissions and attribute controls for the current domain.

Per default, the Signature Threshold and the Revocation Signature Threshold are set to 0. Both values must be changed at least to 1 to release the card from the IMPRINT mode. For more information, see the TKE documentation. Press Send updates to apply your settings.

Step 13

Now select the Domain Keys tab from the bottom of the Crypto Module Administration window.

The new Crypto Module Administration window with verification patterns for the new and current master key is displayed. The patterns are all set to 0, because the current and new master keys are empty yet.

Open the context menu by right-clicking in the white space, and select action Generate key part.

Step 14

The TKE workstation now prompts you to enter the total number of key parts to be generated. You must at least generate two parts. Enter your input and press the OK button.

Step 15

In a similar way as in the previous step, you are now prompted to insert an EP11 smart card and to enter a name and description for each generated key part. The TKE workstation informs you about a successful storage of all generated key parts and descriptions. The new master key can now be generated by the TKE component.

Step 16

During the current process, the new master key now needs to go through three stages:

Load

The key is just stored on the adapter, but not active.

Commit

The key is activated and is now present on the adapter as the new master key. In this state, the existing objects encrypted under the current master key can be re-encrypted by using this new master key.

Set

The new master key is now switched to become the current key to be used.

Start with the Load step: Load the new generated master key parts from the cards to the target crypto adapter. For this purpose, open the context menu from the Crypto Module Administration window and select action Load new master key. TKE now prompts you for the total number of key parts to be loaded. Type the number of previously generated key parts. TKE then prompts you to load each key part separately.

The TKE workstation opens the window Select key part from smart card as shown in Figure 23. From this window, you can commit the single parts of your key. From the list of shown key parts, select that part that you now want to commit and press OK.

Step 17

After you loaded all single master key parts, the complete master key is successfully loaded onto the CEX*P adapter.

The TKE workstation switches back to the Crypto Module Administration window. You can see that the new master key is full/complete, but yet uncommitted. To commit the new master key, invoke the context menu and select action Commit new master key. The status switches to Full Committed, as shown in Figure 25.

Step 18

You can now immediately set the new master key. From the context menu, start action Set, immediate.

Before you actually perform the action, the TKE comes up with a warning. If this is the first time you generated a master key, or if there are no keys stored on your host that are wrapped by the current master key, you can ignore the warning by pressing the OK button.

If there are keys wrapped by the current master key on your host, then you should not generate a new master key, but follow the procedure described in Migrating master keys with the pkcsep11_migrate tool.

See the result in Figure 27: The new master key is now switched to the Current Master Key, and its status is Valid.

If you need to change the master key, see Migrating master keys with the pkcsep11_migrate tool.

Trusted Key Entry (TKE) videos about managing EP11 master keys