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:
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
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;
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
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@bardebug1: 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 CPUdebug2: DES 56 SECURE COP debug2: DES 56 SECURE CPU ...
debug2: SHA-1 160 NA CPU
debug2: SHA-2 512 NA CPUdebug2: TDES 168 SECURE COP
debug2: TDES 168 SECURE CPUdebug2: 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:
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:
SHA-2 is supported, which corresponds to OpenSSH MAC algorithms:
Triple-DES is supported, which corresonds to OpenSSH Cipher
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"
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)
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 firstname.lastname@example.org,email@example.com, firstname.lastname@example.org,email@example.com, hmac-sha1,hmac-sha2-256,hmac-sha2-512,hmac-sha1-96, firstname.lastname@example.org,email@example.com,hmac-md5, hmac-md5-96,firstname.lastname@example.org,email@example.com, firstname.lastname@example.org,email@example.com, firstname.lastname@example.org,hmac-ripemd160,email@example.com Ciphers aes128-ctr,aes192-ctr,aes256-ctr,aes128-cbc,aes192-cbc, aes256-cbc,firstname.lastname@example.org,3des-cbc,email@example.com, firstname.lastname@example.org,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.
|Cipher and MAC negotiation rule|
The first algorithm in the client list that appears anywhere in the server list will be selected.
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*-ctralgorithm that meets their requirements, followed by stronger
aes*-ctrCiphers 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
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 email@example.com,firstname.lastname@example.org, email@example.com,firstname.lastname@example.org, 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
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 changes # Only support ICSF/CPACF SHA-1 and SHA-2 MACs: MACs email@example.com,firstname.lastname@example.org, email@example.com,firstname.lastname@example.org, 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
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):
ssh -vvv email@example.com... debug1: mac_setup_by_alg: hmac-sha1 from source ICSF debug1: zsshIcsfMacInit (402): CSFPTRC successful: return code = 0, reason code = 0, handle = 'SYSTOK-SESSION-ONLY 00000000S' ... debug1: cipher_init: aes128-ctr from source ICSF debug1: zsshIcsfCipherInit (930): CSFPTRC successful: return code = 0, reason code = 0, handle = 'SYSTOK-SESSION-ONLY 00000001S' ...
These messages confirm that ICSF is being used for the selected MAC: hmac-sha1
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 ...