Installing the host part of the EP11 library

Edit online

Read the contained information about how to install the host part of the EP11 library as a component of the EP11 stack.

About this task

As a part of the EP11 stack, you need to install the host part of the EP11 library on your IBM Z®, as shown in Figure 1.

Also, to use the EP11 functionality, the TKE daemon (ep11TKEd) must be available and running to perform certain communication tasks. This communication path is necessary, for example, for the initial key personalization or for key updates (see also Setting a master key on the Crypto Express EP11 coprocessor).

Procedure

  1. Obtain the appropriate EP11 software package for use on IBM Z mainframe servers, that contains the Linux® on Z EP11 enablement from the software package selection page:
    IBM PCIe Cryptographic Coprocessors

    RPM is the installation package format for Red Hat Enterprise Linux and SUSE Linux Enterprise Server distributions. DEB is the package format for the Ubuntu distribution. The names of the packages are as follows:

    • ep11-host-2.0.0-2.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.
    • libep11_2.0.0-2_s390x.deb or later is the equivalent Ubuntu package.
    • ep11-host-devel-2.0.0-2.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-dev_2.0.0-2_s390x.deb or later is the equivalent Ubuntu package.

    To see a complete list of files contained in the packages, you can download the associated RELEASE.txt file from the software-package selection page.

    Note: The host part of the EP11 library is developed and maintained by IBM® and therefore not part of any commercial Linux distribution.
  2. Install the RPM or DEB by issuing one of the following commands: 
    
rpm -Uvh <rpm_packet>  /* for RPM new installation or updates*/
dpkg -i <deb_packet>   /* for DEB new installation or updates*/
  3. The EP11 TKE daemon (ep11TKEd), which comes along with the standard RPM or DEB packages obtained in step 1 is also installed during the installation. It is required and must be running for handling administrative commands and for managing communication between the TKE workstation and the CEX*P EP11 coprocessor.

What to do next

Starting with EP11 library version 2.0, the TKE can use the ep11TKEd daemon to authenticate with a Linux user who is member of the ep11tke group which is defined in /etc/group of the system. This is the default, and it is recommended not to change this.

However, you could disable the authentication in the ep11TKEd configuration file as described hereafter.

The ep11TKEd daemon uses the Linux pluggable authentication modules (PAM) subsystem to authenticate the user. The interaction with PAM can also be configured in a ep11TKEd-specific PAM configuration file.

Software requirements: As of EP11 software package 2.0.0, the EP11 TKE daemon requires the OpenSSL library version 1.0.x for secure authentication with the TKE. It also requires the PAM standard modules for the authentication process. Refer to your Linux distribution documentation for supported versions of OpenSSL.

The ep11TKEd daemon 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.

Security notes: The ep11TKEd daemon typically runs as the nobody user. For the authentication process, ep11TKEd needs privileges to access the shadow file. For those cases, ep11TKEd can be a setGID program which uses the shadow group, or a setUID to root program to gain access to the file.

The ep11TKEd daemon uses these privileges of the shadow group or the read or search capability only through a small window of a running authentication process. Privileges are permanently dropped, if authentication is disabled in the configuration file.

In the host package installation process, Linux is checked for its capabilities. If the shadow group is found, then the sticky bit for the shadow group is set. If the group is not found, the sticky bit for the root user is set.

If supported by your Linux distribution, AppArmor rules are installed. If they are not already enforced for the ep11TKEd daemon, you can enforce them manually.

Configuration:
Note: It is recommended to use the default settings. The configuration features described hereafter may be used in special environments.
  • Configuration files:

    • The EP11 TKE daemon can be configured in file /etc/ep11/ep11tked.conf.

      The only allowed option is CipherMode. The two allowed values are AES and None. AES is the default value.

      AES
      Use the Linux PAM system to authenticate a user.
      None
      Do not use any authentication.
      Note: If possible, AES should always be used!
    • 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 that has a password configured and is member of the ep11tke group to gain access through the ep11TKEd daemon.

  • How to control the daemon:

    The program can be started manually by executing the file /usr/sbin/ep11TKEd.

    This starts 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 the following command: 
    systemctl disable ep11TKEd

    See the systemd documentation 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.

Restrictions:

The versions of the ep11TKEd daemon delivered with an EP11 host library starting with version 2.0 cannot be used on an IBM zEnterprise EC12 (zEC12) system. On these zEC12 systems, you must use version 1.x of the EP11 package together with the contained ep11TKEd daemon.