Dovetailed Technologies

2. Exploiting ICSF acceleration

2.1 Enabling ICSF Cipher and MAC support

Note: Apply the PTF for APAR 0A45548 ("AES CTR MODE ENCRYPTION SUPPORT"). This PTF must be applied in order to enable ICSF accleration of the aes-ctr* ciphers.

To use ICSF to accelerate Cipher and MAC algorithms in IBM Ported Tools OpenSSH, all z/OS userids that use the ssh client or login to the sshd server, including "SSHDAEM" and "SSHD" (the SSHD privileged and privilege separation userids) will require read access to the following SAF/RACF profiles in the CSFSERV class:

  • CSFIQA - ICSF Query Algorithm

  • CSF1TRC - PKCS #11 Token record create

  • CSF1TRD - PKCS #11 Token record delete

  • CSF1SKE - PKCS #11 Secret key encrypt

  • CSF1SKD - PKCS #11 Secret key decrypt

  • CSFOWH - One-Way Hash Generate

Some installations may wish to create a SAF/RACF GROUP with access to these profiles and then connect required users to this group. Given the nature of these services, many installations will choose to permit all users to these resources:

RDEFINE CSFSERV CSFIQA UACC(NONE)
RDEFINE CSFSERV CSF1TRC UACC(NONE)
RDEFINE CSFSERV CSF1TRD UACC(NONE)
RDEFINE CSFSERV CSF1SKE UACC(NONE)
RDEFINE CSFSERV CSF1SKD UACC(NONE)
RDEFINE CSFSERV CSFOWH  UACC(NONE)

PERMIT  CSFIQA  CLASS(CSFSERV) ID(*) ACCESS(READ)
PERMIT  CSF1TRC CLASS(CSFSERV) ID(*) ACCESS(READ)
PERMIT  CSF1TRD CLASS(CSFSERV) ID(*) ACCESS(READ)
PERMIT  CSF1SKE CLASS(CSFSERV) ID(*) ACCESS(READ)
PERMIT  CSF1SKD CLASS(CSFSERV) ID(*) ACCESS(READ)
PERMIT  CSFOWH  CLASS(CSFSERV) ID(*) ACCESS(READ)

SETROPTS CLASSACT(CSFSERV)
SETROPTS RACLIST(CSFSERV) REFRESH 

Note: Starting with ICSF version HCR77A0, the CSF1TRC API used by P.T. OpenSSH will check for the existence of a SAF/RACF resource: CLEARKEY.SYSTOK-SESSION-ONLY CLASS(CRYPTOZ). IBM suggests that you do you not define this specific resource or a matching generic resource. If you do, then you must permit all SSH/SSHD userids READ access.

If you are using ICSF version HCR77A1, then you should definitely consider defining the following two profiles. This will disable SAF/RACF checking for CSFRNG (random number; /dev/random) and CSFOWH (MACs). Since MAC generation occurs for each SSH packet, this can save a couple of points off CPU usage.

RDEFINE XFACILIT CSF.CSFSERV.AUTH.CSFOWH.DISABLE
    UACC(READ)
RDEFINE XFACILIT CSF.CSFSERV.AUTH.CSFRNG.DISABLE
    UACC(READ)
SETROPTS CLASSACT(XFACILIT)
SETROPTS RACLIST(XFACILIT) REFRESH 

Next, you must update both /etc/ssh/zos_ssh_config and /etc/ssh/zos_sshd_config and add the following two lines:

CiphersSource any
MACsSource any 

Now, verify that you can still open an ssh connection from your workstation into the SSHD server. Then, using that z/OS UNIX shell session issue a dummy ssh client command to verify ICSF functionality. It should look something like this:

$ ssh -vv foo@bar
debug1: sshd version OpenSSH_6.4, OpenSSL 1.0.1c 10 May 2012
...
debug1: zsshVerifyIcsfSetup: ICSF FMID is 'HCR77B0 '
debug1: zsshVerifyIcsfSetup (163): CSFIQA successful: return code = 0, reason code = 0
debug2: -----------------------------------
debug2: CRYPTO   SIZE     KEY      SOURCE  
debug2: -----------------------------------
debug2: AES      256      SECURE   COP     
debug2: AES      256      SECURE   CPU     
debug2: DES      56       SECURE   COP     
debug2: DES      56       SECURE   CPU
...     
debug2: SHA-1    160      NA       CPU     
debug2: SHA-2    512      NA       CPU     
debug2: TDES     168      SECURE   COP     
debug2: TDES     168      SECURE   CPU     
debug2: ssh_connect: needpriv 0
FOTS1336 ssh: Could not resolve hostname bar: EDC9501I The name does not resolve ...

In the above ICSF CRYPTO table display, we can see that:

  • the AES Cipher is supported up through 256 bits. This corresponds to OpenSSH Cipher algorithms: aes128-ctr, aes192-ctr, aes256-ctr, aes128-cbc, aes192-cbc, and aes256-cbc. Older processors support less than 256 bit AES Ciphers. The value listed here is the maximum strength support by your processor.

  • SHA-1 is supported, which corresponds to OpenSSH MAC algorithms: hmac-sha1 and hmac-sha1-96

  • SHA-2 is supported, which corresponds to OpenSSH MAC algorithms: hmac-sha2-512 and hmac-sha2-256

  • Triple-DES is supported, which corresonds to OpenSSH Cipher 3des-cbc

Note: The entries with SOURCE=CPU correspond to ICSF facilities that are implemented with CPACF, which is what is used by IBM Ported Tools OpenSSH. For Ciphers and MACs, these are more efficient than using a co-processor anyway.

Reference: PTUG: "Setting up OpenSSH to use ICSF ciphers and MAC algorithms"

2.2 Configure OpenSSH Ciphers and MACs

In this section, you will review the Cipher and MAC algorithms that your ssh client and sshd server will use. Choosing ICSF algorithms implemented via CPACF can result in CPU savings upward of 50%, so this is important to understand and implement correctly.

The default OpenSSH 6.4p1 Cipher and MAC algorithm names can be seen (commented out) in the sample /etc/ssh/ssh_config (ssh client) and /etc/ssh/sshd_config (sshd server) configuration files.

Following the commented lines are the z/OS recommended defaults, which are uncommented (active). These defaults have been selected to best optimize ICSF acceleration while maintaining a high level of compatability with non-z/OS OpenSSH implementations. For reference, these are (each entry is a single line, shown wrapped below):

# /etc/ssh/ssh_config changes

MACs hmac-sha1-etm@openssh.com,hmac-sha2-256-etm@openssh.com,
hmac-sha2-512-etm@openssh.com,hmac-sha1-96-etm@openssh.com,
hmac-sha1,hmac-sha2-256,hmac-sha2-512,hmac-sha1-96,
hmac-md5-etm@openssh.com,hmac-md5-96-etm@openssh.com,hmac-md5,
hmac-md5-96,umac-64-etm@openssh.com,umac-128-etm@openssh.com,
hmac-ripemd160-etm@openssh.com,umac-64@openssh.com,
umac-128@openssh.com,hmac-ripemd160,hmac-ripemd160@openssh.com
    
Ciphers aes128-ctr,aes192-ctr,aes256-ctr,aes128-cbc,aes192-cbc,
aes256-cbc,rijndael-cbc@lysator.liu.se,3des-cbc,aes256-gcm@openssh.com,
aes128-gcm@openssh.com,arcfour128,arcfour256,blowfish-cbc,cast128-cbc,arcfour

These lists specify the Cipher and MAC algorithms that are supported by the ssh client and server. When an ssh client connects to an ssd server, they exchange these lists and negotiate which Cipher and MAC algorithm will be used for this session.

[Note]Cipher and MAC negotiation rule

The first algorithm in the client list that appears anywhere in the server list will be selected.

Configuring SSH client Ciphers and MACs

Note: we recommend that you leave the z/OS options unchanged unless you have a compelling reason to modify them. These lists will use ICSF acceleration when possible, and fall back to software when required. However, some sites may prefer that only hardware accelerated Ciphers and MACs should be allowed.

Considering the ssh client configuration first, and mindful of the rule above, we can customize the client configuration file, with the following considerations:

  • sites should prefer (list first) the minimum strength aes*-ctr algorithm that meets their requirements, followed by stronger aes*-ctr Ciphers up through the maximum bit length supported by CPACF on their processor (see the table in the previous section).

  • sites may choose not to support the aes*-cbc or older 3des-cbc algorithms, or other non-ICSF Ciphers that do not meet their security requirements.

  • The Host and Match configuration keywords can be used in SSH client configuration files to conditionally assign different algorithm lists to specific hosts, userids, etc.

To implement the ICSF only strategy, update the /etc/ssh/ssh_config file, comment out the existing MACs and Cipher lines, and replace with the following (each entry is a single line, shown wrapped below):

# /etc/ssh/ssh_config changes

# Only support ICSF/CPACF SHA-1 and SHA-2 MACs:
MACs hmac-sha1-etm@openssh.com,hmac-sha2-256-etm@openssh.com,
hmac-sha2-512-etm@openssh.com,hmac-sha1-96-etm@openssh.com,
hmac-sha1,hmac-sha2-256,hmac-sha2-512,hmac-sha1-96
    
# Only allow AES ICSF/CPACF Ciphers, exclude 3des-cbc
Ciphers aes128-ctr,aes192-ctr,aes256-ctr,aes128-cbc,aes192-cbc,aes256-cbc

Configuring SSHD server Ciphers and MACs

The negotiation rule implies that your have fewer choices for selecting Ciphers and MACs in your SSHD server configuration. To allow only ICSF/CPACF accelerated Ciphers and MACs and fail otherwise, make the following changes to your /etc/ssh/sshd_config file:

# /etc/ssh/sshd_config changes

# Only support ICSF/CPACF SHA-1 and SHA-2 MACs:
MACs hmac-sha1-etm@openssh.com,hmac-sha2-256-etm@openssh.com,
hmac-sha2-512-etm@openssh.com,hmac-sha1-96-etm@openssh.com,
hmac-sha1,hmac-sha2-256,hmac-sha2-512,hmac-sha1-96
    
# Only allow AES ICSF/CPACF Ciphers, exclude 3des-cbc
Ciphers aes128-ctr,aes192-ctr,aes256-ctr,aes128-cbc,aes192-cbc,aes256-cbc

Optionally, if you wish to support only a subset of the accelerated algorithms, remove selectively from these lists

2.3 Verifying ICSF usage

To verify that ICSF is being used in the IBM Ported Tools ssh client, run it with the verbose debugging options. You can run the client from a TSO OMVS shell directly (the ISCF information will be displayed before you are asked to authenticate):

/SYSTEM/home/user> ssh -vvv myuser@127.0.0.1
...
debug1: mac_setup_by_alg: hmac-sha1 from source ICSF 1
debug1: zsshIcsfMacInit (402): CSFPTRC successful: return code = 0, reason code = 0, 
 handle = 'SYSTOK-SESSION-ONLY 00000000S'
...
debug1: cipher_init: aes128-ctr from source ICSF 2
debug1: zsshIcsfCipherInit (930): CSFPTRC successful: return code = 0, reason code = 0,
 handle = 'SYSTOK-SESSION-ONLY 00000001S'
...

1

These messages confirm that ICSF is being used for the selected MAC: hmac-sha1

2

These messages confirm that ICSF is being used for the selected Cipher: aes128-ctr

To confirm that ICSF is being used for an IBM Ported Tools SSHD server session, you must enable debugging for SSHD by making the following temporary change in /etc/ssh/sshd_config and restart SSHD.

Note: this will generate lots of trace information to syslogd, so you will not want to do this when there (many) other sessions starting in this period. Also, you can do an in-place restart of SSHD by sending the "HUP" signal to the top-level daemon, which does not disrupt existing SSHD sessions. See the P.T User's Guide for details.

# file /etc/ssh/sshd_config
...
#SyslogFacility AUTH         
#LogLevel INFO               
LogLevel DEBUG3             
...

Copyright© 2009-2017 Dovetailed Technologies, LLC. All rights reserved.
Co:Z® is a registered trademark of Dovetailed Technologies, LLC.