OpenSSL 1.1.1: Hardware acceleration for OpenSSH via IBMCA engine

IBM Documentation

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.

Note: Use the IBMCA engine only with OpenSSL versions up to 1.1.1, but not with versions starting with 3.0.

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.

Figure 1. lszcrypt output

 
[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).

Figure 2. icastats output

[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 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
...

Hint on how to exploit a CCA coprocessor: For the same use case, you can also apply EC cryptography (instead of RSA). For processors earlier than IBM z15, EC cryptography is performed on CCA coprocessors, if available and configured, and else is performed by OpenSSL out of the box . For this purpose, configure OpenSSL with 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).

Parent topic:

Use cases for the IBMCA provider and the IBMCA engine