OpenSSL 1.1.1: Hardware acceleration for OpenSSH via IBMCA engine
In the presented use case, you learn how to exploit OpenSSL's HW acceleration for involved cryptographic algorithms while establishing and using connections based on SSH (secure shell). Two scenarios are shown: the first one without support of the IBMCA engine and the second one with enabled IBMCA engine support. Both scenarios outline how to verify that HW acceleration was used. Also, both scenarios use two separate systems, a client and a server system, to ensure individual tracking of operations by the used counting mechanisms. The server is required to run on a Linux® on IBM® Z system, the client is only required to run a secure shell client application.
SSH usage scenario without HW support
In this scenario, the IBMCA engine is not configured in the system-wide used openssl.cnf file. To check this, run the openssl engine command and verify that only one single line is returned as output.
[tester@server ~]$ openssl engine (dynamic) Dynamic engine loading support
To connect to a remote Linux system on IBM Z or LinuxONE which provides CPACF as well as IBM cryptographic adapters configured as accelerators, use the ssh command similar to the one shown in the following example. With this command, and the used parameters, you specify the RSA private key for authentication of a previously generated public/private key pair, for example, using the ssh-keygen tool. You also specify the ecdh-sha2-nistp521 algorithm for key exchange and connection encryption.
[tester@client ~]$ ssh -i .ssh/id_rsa -o KexAlgorithms=ecdh-sha2-nistp521 tester@server
To show that no asymmetric cryptographic algorithms had been performed on the accelerator card, run the lszcrypt command.
[tester@server ~]$ lszcrypt CARD.DOM TYPE MODE STATUS REQUESTS ---------------------------------------------- 01 CEX6C CCA-Coproc online 1 01.000e CEX6C CCA-Coproc online 1 02 CEX6P EP11-Coproc online 0 02.000e CEX6P EP11-Coproc online 0 04 CEX5C CCA-Coproc online 0 04.000e CEX5C CCA-Coproc online 0 05 CEX5P EP11-Coproc online 0 05.000e CEX5P EP11-Coproc online 0 06 CEX7A Accelerator online 0 06.000e CEX7A Accelerator online 0 07 CEX7A Accelerator online 0 07.000e CEX7A Accelerator online 0
The non-zero counts shown in Figure 1 refer to random data requested from the card during the Linux system boot and are not related to SSH activities.
The icastats command does not show any activities, as libica functions are not called to perform RSA or EC based workload (see also icastats - Show use of libica functions).
[tester@server ~]$ icastats
function | hardware | software
----------------+------------------------------+-----------------------------
| ENC CRYPT DEC | ENC CRYPT DEC
----------------+------------------------------+-----------------------------
... | |
ECDH | 0 | 0
ECDSA Sign | 0 | 0
ECDSA Verify | 0 | 0
ECKGEN | 0 | 0
Ed25519 Keygen | 0 | 0
Ed25519 Sign | 0 | 0
Ed25519 Verify | 0 | 0
Ed448 Keygen | 0 | 0
Ed448 Sign | 0 | 0
Ed448 Verify | 0 | 0
... | |
RSA-ME | 0 | 0
RSA-CRT | 0 | 0
...
The provided samples from Figure 2 show that the cryptographic calculations are performed by the built-in hardware and software implementations and not by the libica functions. The software column shows all zeros, because the libica library was not used in this scenario. In SSH usage scenario including HW support, the use of the HW acceleration components is demonstrated using the same commands as in this current scenario (without HW support).
SSH usage scenario including HW support
The example outlined in this section is using the same type of RSA cryptography as the one shown in SSH usage scenario without HW support, however, this time with HW acceleration via attached cryptographic adapters configured in accelerator mode (CEX*A cards).
Configure the IBMCA engine appropriately. Read Configuring OpenSSL to use the IBMCA engine for more information. The IBMCA engine should be enabled for the asymmetric algorithms RSA, DSA, and DH only, and only for processors earlier than IBM z15® additionally for the EC algorithms. Before continuing, verify that the IBMCA engine is configured globally in the system:
[tester@server ~]$ openssl engine (dynamic) Dynamic engine loading support (ibmca) Ibmca hardware engine support
In addition to CPACF being used for symmetric algorithms and hash functions by OpenSSL itself, the workload for RSA runs on the attached cryptographic adapters used for acceleration by the IBMCA engine.
To visualize the exploitation of HW acceleration on different levels, you can check the following counters:
- for CPACF, use the cpacfstats command.
- for libica, use the icastats command.
- for the cryptographic coprocessors, use the lszcrypt -V command.
In this scenario the cryptographic accelerators are counting requests. The cpacfstats command is only available on the LPAR virtualization layer, and after additional configurations. The subsequent screen shots show at first an ssh command to login to a test server, which is the same command as in SSH usage scenario without HW support, and three example outputs of cpacfstats, icastats, and lszcrypt commands showing resulting output of cryptographic processing.
[tester@client ~]$ ssh -i .ssh/id_rsa -o KexAlgorithms=ecdh-sha2-nistp521 tester@server
[tester@server ~]$ cpacfstats des counter: 54 aes counter: 677 sha counter: 302 rng counter: 399 ecc counter: 1
For a description how to set up the CPACF statistics, read the information from the Device Drivers documentation or use the following direct link: cpacfstats - Monitor CPACF cryptographic activity.
[root@server ~]$ icastats
function | hardware | software
----------------+------------------------------+-----------------------------
| ENC CRYPT DEC | ENC CRYPT DEC
----------------+------------------------------+-----------------------------
... | |
RSA-ME | 2 | 0
RSA-CRT | 1 | 0
... | |
The statistics of the IBM cryptographic adapters in accelerator mode counted two requests per login, distributed among two cards and domains, summarized for the cards 06 and 07. Note that in this scenario the root user issues the icastats command. For more detailed information see Statistics from icastats.
[tester@server ~]$ lszcrypt -V CARD.DOM TYPE MODE STATUS REQUESTS PENDING HWTYPE QDEPTH FUNCTIONS DRIVER -------------------------------------------------------------------------------------------- 06 CEX7A Accelerator online 2 0 13 08 -MC-A-NF- cex4card 06.0016 CEX7A Accelerator online 2 0 13 08 -MC-A-NF- cex4queue 07 CEX7A Accelerator online 1 0 13 08 -MC-A-NF- cex4card 07.0016 CEX7A Accelerator online 1 0 13 08 -MC-A-NF- cex4queue 08 CEX7C CCA-Coproc offline 0 0 13 08 S--D--NF- cex4card ...
default_algorithms = RSA,DH,DSA,EC and issue the following
ssh command: [tester@client ~]$ ssh -i .ssh/id_ed25519 -o KexAlgorithms=ecdh-sha2-nistp521 tester@server
For processors starting with IBM z15, you can use OpenSSL out of the box (see Figure 1).