TKE setup for EP11

Edit online

You need to retrieve required files from the package of the EP11 support program and configure the TKE environment according to your EP11 requirements.

Required files for EP11 and TKE setup

You need to obtain the EP11 support program package. This package contains the EP11 host library and further files required for the configuration of the TKE environment according to your EP11 requirements.

Download the appropriate EP11 support program to a temporary directory:
EP11 Support Program
1. You need to logon to this page with your IBMid. If you do not have such an account, you are offered a link where you can create one.
2. Click on the View license link to read the license information.
3. Select the I agree check box to confirm that you had the opportunity to review the license agreement and to agree that you are to be bound by its terms..
4. Click on the I confirm button to need to confirm your acceptance of the license agreement.
5. On the opening page, you can then download the following items:
  - IBM Z EP11 Support Program files:
    You receive a zip-file containing three RPM and three DEB packages and further required files. At the time of writing, the name of the package was EP11-SupportProg42-pkg.zip.
  - IBM Z EP11 Support Program Release Information: RELEASE.txt
Before you continue, read the information provided in files README.md and RELEASE.txt. These files may contain important information which is more up to date than this publication.
The README.md file contains installation instructions for the EP11 host library, which are repeated for your ease of use in step 3 of this list. Further important topics in the README.md are the following:
- Hardware requirements
- Supported Linux® distributions
- Software requirements, especially:
  The Trusted Key Entry (TKE) version needs to be
  - 8.0 or later for CEX5P support
  - 9.0 or later for CEX6P support
  - 9.1 or later for CEX7P support
  - 10.0 or later for CEX8P support.
In a root shell, install the RPM or DEB package.
At the time of writing, the latest package names were the following:
- ep11-host-4.2.0-5.s390x.rpm or later is the standard RPM package that provides libraries (libep11.so) and tools (for example, the ep11info tool) to configure and use a CEX*P EP11 coprocessor. All other required libraries must be available and loaded at run time.
- libep11_4.2.0-5_s390x.deb or later is the equivalent Ubuntu (DEB) package.
- ep11-host-devel-4.2.0-5.s390x.rpm or later is the development RPM package which is required if you want to develop programs that link to the EP11 library.
- libep11_4.2.0-5_s390x.deb or later is the equivalent Ubuntu (DEB) package.
- ep11-host-static-4.2.0-5.s390x.rpm or later is the RPM package with all required additional libraries statically built in (for example, libc, librt, libpthread).
- libep11-static_4.2.0-5_s390x.deb or later is the equivalent Ubuntu (DEB) package.
Install the appropriate package using one of the following commands.
Note: All sudo commands shall be issued with full path, for example,
```
sudo  /bin/rpm/
```
- Installing RPM
```
rpm -i <package name>
```
  or upgrade with:
```
 rpm -U <package name>
```
  If you prefer sudo, install with
```
sudo rpm -i <package name>
```
  or upgrade with
```
sudo rpm -U <package name>
```
- Installing DEB
```
dpkg -i <package name>
```
  If you prefer sudo, install with
```
sudo dpkg -i <package name>
```
On some systems, you may need to update the shared library caches in a root shell with ldconfig. Or if you prefer sudo, use sudo ldconfig.

After a successful installation, you can perform the tasks described in Configuring the TKE environment for EP11.

Configuring the TKE environment for EP11

The IBM Z EP11 Support Program files package also contains a file called README_TKE.md which describes how to configure the connection between the TKE and the EP11 TKE daemon (EP11TKEd). For your convenience, here follows a formatted edition of the contents of the README_TKE.md file.

The EP11 TKE daemon (EP11TKEd) is used for receiving messages from a Trusted Key Entry workstation and routing those messages to the specified Crypto Express EP11 coprocessors (CEX5S - CEX8S). The EP11TKEd daemon uses the EP11 host library to communicate with EP11 CEX<n>S cards and uses network port 50004 or 50104 to communicate with the TKE.

The TKE can use the EP11 TKE daemon to authenticate with a Linux user that is a member of the ep11tke Linux group. The authentication can be disabled in the EP11TKEd configuration file.

EP11TKEd uses the Linux PAM subsystem to authenticate the user. The interaction with PAM can also be configured in a EP11TKEd specific PAM configuration file.

Stack Overview

Trusted Key Entry 
    | 
EP11 TKE daemon 
    | 
EP11 host library 
    | 
zcrypt device driver within the Linux kernel 
    | 
EP11 Coprocessor (CEX5P/CEX6P/CEX7P/CEX8P)

Software requirements

The EP11 TKE daemon requires the OpenSSL library version 1.1.x, or 3.x and the PAM library (distributed under the BSD license) for secure authentication with the TKE for the authentication process. OpenSSL versions other than 1.1.x or 3.x are not supported.

EP11TKEd uses systemd for daemonizing and logging. If you do not use systemd you need to do the daemonizing and routing of log messages to files yourself.

Only TKE versions equal or greater than 8.0 are supported with this version of EP11TKEd.

The Enhanced Password Encryption Policy needs to be activated on the TKE and the PKA key storage needs to be initialized.

Security notes

The EP11 TKE daemon typically runs as the ep11tke user. For the authentication process, EP11TKEd needs privileges to access the shadow file. For those cases EP11TKEd can be either a setGID program which uses the shadow group to gain access to the file or a setROOT program if the shadow group is not available. EP11TKEd uses these privileges of the shadow group or of the root user only throughout a small window during a running authentication process. Privileges are permanently dropped if authentication is disabled in the configuration file.

During the host package installation process the operating system is checked for its capabilities. If the shadow group is found, the EP11TKEd is made a setGID program, otherwise the sticky bit for the root user is set.

If supported by your Linux distribution, AppArmor rules are installed and enforced for this program.

Passwords consisting of less than eight characters are not supported and in general passwords must neither contain leading nor trailing spaces.

User ID maximum length was extended from 8 to 32 characters, which is supported together with TKE version 9.2 or later.

Configuration

You can configure the EP11 TKE daemon in file /etc/ep11/ep11tked.conf using the following options:

CipherMode: The two allowed values are AES and None. AES is the default value. If the value AES is set, the service uses the Linux PAM system to authenticate a user. The value None specifies that no user authentication is executed. If possible, AES should always be used!
use_tls: Allowed values are True and False. False is the default value. If this option is set to True, then the EP11 TKE daemon is configured for TLS connections. If the use_tls option is set to False, the EP11 TKE daemon uses a plain socket connection.
tls_version: Specifies the minimum required TLS version. Version tls_1.2 is the default value. Allowed values are tls_1.2 and tls_1.3. This option is ignored if the option use_tls is set to False.
key_file: Specifies the location of the private key file that is used for the TLS connection. This option is ignored if the option use_tls is set to False.
cert_file: Specifies the location of the public TLS certificate file. This option is ignored if the option use_tls is set to False.
port: Specifies the socket port to which the EP11 TKE daemon is listening. If this option is not set, the default listener port is 50004 and use_tls is set to False. Or the default listener port is 50104, if use_tls is set to True.

All keywords are case-insensitive.

The authentication process can be configured in the file /etc/pam.d/ep11tked. See the PAM module manuals for help on editing this file. Be careful when changing this file, as it involves the risk of rendering the authentication useless. The default setting is to allow any user who has a password configured and is member of the ep11tke group to gain access through the EP11 TKE daemon.

An AppArmor profile is installed to the /etc/apparmor.d directory and is activated with the reload of the AppArmor daemon. This must be done manually.

Control the daemon

The EP11 TKE daemon can be started manually by executing the following file /usr/sbin/ep11TKEd. This starts the EP11TKEd in the running shell and not as a daemon. Log messages are printed to the console. This is sometimes useful for troubleshooting, but usually, EP11TKEd should be started through systemd:

systemctl start ep11TKEd

To automatically start the daemon during boot use the following command:

systemctl enable ep11TKEd

To disable the automatic start use:

systemctl disable ep11TKEd

See the systemctl manual for help with the service manager. When using systemd for controlling the daemon, log messages are written to the systemd journal. See the journald manual for more information.

Default daemon enablement is handled via systemd preset. See the man page systemd.preset(5) for details. In case the daemon is upgraded from a previous version and was enabled, the daemon is restarted.

If systemd is not available on your distribution, you must use other means like nohup (see man nohup) if you need to start EP11TKEd as a daemon.

After a package upgrade, it may be required to restart the daemon. It may also be required to let systemd reload the systemd service file. This can be done using the following command:

systemctl daemon-reload

Enabling TLS support

The TKE supports a means to secure the connection to a host via TLS. If you want to make use of this feature, perform the following steps:

Create a new key-pair for TLS connections. By default, an OpenSSL self-signed certificate has been created and configured during installation of the EP11 TKE daemon. For test and debugging purposes, you may therefore skip this step. One way to create a TLS key pair is to invoke the following OpenSSL command:
```
sudo "openssl req -new -newkey rsa:4096 -x509 -sha256 -nodes \ 
     -out /etc/ep11/.tls/MyTlsCertificate.pem --subj \ 
     /CN=$HOSTNAME -keyout /etc/ep11/.tls/MyTlsKey.pem" -u ep11tke
```
Ensure that you have specified the server hostname in the CN setting of the created TLS certificate, otherwise the TKE would reject using this certificate for TLS connections. Also, check that the owner of the generated private key file is a member of the ep11tke group, and the permission flags for this file are 700.
Edit the file /etc/ep11/ep11tked.conf, review the following settings:
cert_file <path_to_certfile>
The path_to_certfile is for the location of the TLS certificate file. The example above would use the value /etc/ep11/.tls/MyTlsCertificate.pem.
key_file <path_to_keyfile>
The path_to_keyfile is for the location of the TLS private key file. The example above would use the value /etc/ep11/.tls/MyTlsKey.pem. Additionally ensure that the following options are set:
```
use_tls   True 
```
Next, restart the EP11 TKE daemon service to make the configuration changes active:
```
systemctl restart ep11TKEd
```
Receive the certificate at the TKE. The TKE supports two ways to import TLS certificates:
- Import via host access (3.a)
- Import via removable device (3.b)
1. Import TLS certificate via host access.
  - Login to the TKE console workplace in Privileged Mode Access.
  - Select the task Service Management -> Certificate Management.
  - Click the menu item Import -> From Remote Server.
  - Specify the hostname and port number of the host, and click OK..
2. Import TLS certificate via USB drive.
  For this task, you require an empty USB stick (minimum storage size: eight GB).
  - Insert the USB stick at the TKE workstation.
  - Login to the TKE console workplace in Privileged Mode Access.
  - Select the task Service Management" -> Format Media".
  - Choose the format media type Trusted Key Entry data.
  - Continue the panel flow to format the USB drive.
  - Remove the USB disk from the TKE.
  - Insert the USB disk at the host workstation.
  - Mount the USB drive at the host, and copy the certificate to the root directory of the mounted USB drive.
  - Remove the USB stick from the remote host.
  - Insert the USB stick at the TKE workstation.
  - Select the task Service Management -> Certificate Management.
  - Click the menu item Import -> From Removable Media.
  - Select the USB drive that you inserted, and click OK.
  - Select the filename of the certificate that you copied to the USB drive before.
In the TKE application, create or change a Host definition to support TLS:
- In the TKE application, either select Create Host or Change Host.
- Ensure that the option Enable SSL/TLS is checked.
- Keep in mind that the recommended port for host connection is changed to 50104.

Disabling TLS support

Since version 4.0.0, the EP11 TKE daemon is configured for TLS connections by default. That means, immediately after the daemon has been installed or updated, the EP11 TKE daemon does no more accept plain socket connections to port 50004.

If you want to disable the TLS support, the following steps are necessary:

Edit the file /etc/ep11/ep11tked.conf, and put a comment mark (#) before the configuration options use_tls and port, or remove the two options.
Restart the EP11 TKE daemon, in order to make the changes effective:
```
systemctl restart ep11TKEd
```