(C) Copyright IBM Corporation, 2012, All Rights Reserved. =================================================================== Package: IBM CEX3C Host Libraries and Tools Name: csulcca-version-arch.rpm Target* Arch: Linux on System z 64 Bit (s390x) Last updated: June 28, 2012 =================================================================== Title: RELEASE NOTES for CCA 4.2 on Linux on System z Description: This document describes release specific notes and restrictions for compatibility and maintenance awareness. =================================================================== Contents: --------- 0. UPDATE SUMMARY 1. PREREQUISITES 2. RESTRICTIONS 2.1 Restriction: Handle the more flexible CCA 4.2-requests correctly 2.1.1 Summary of Restriction 2.1.2 Circumvention and Fixes 2.1.3 Detailed Description of Restriction 2.1.4 Restriction scenarios/examples =================================================================== 0. UPDATE SUMMARY 2012 06 28 (June 28) --2.1.2 updated with details of fixes available from Linux distribution owners. --------------------------------------------------------------- 1. PREREQUISITES In order to use the full set of CCA Release 4.2 functions, a Linux on System z distribution with support for the CEX3C feature is required: --SUSE Linux Enterprise Server 11 SP2 (SLES 11 SP2) 64-bit only --SUSE Linux Enterprise Server 10 SP4 (SLES 10 SP4) 64-bit only --Red Hat Enterprise Linux 5 Update 7 (64-bit only) --Red Hat Enterprise Linux 6 Update 2 (64-bit only) --Distributions listed for CCA 4.1.0 below The following Linux on System z distributions support CCA Release 4.1.0 host software for use with CEX3C. Support also extends to CEX2C within the functional scope of the CEX2C feature: --SUSE Linux Enterprise Server 11 SP1 (SLES 11 SP1) --SUSE Linux Enterprise Server 10 SP3 (SLES 10 SP3) --Red Hat Enterprise Linux 5 Update 6 --Red Hat Enterprise Linux 6 Notes --Applications linked with prior CCA host software will continue to function if the CCA host software is upgraded in place, however IBM always recommends full testing of upgrades before implementing production roll-out. --CCA 4.2 host software supports all prior levels of CEX3C adapter firmware and may also be used for support of the CEX2C subset of functionality. Full CEX2C support is included in CCA Release 4.2 and 4.1.0. However, note that because of limits in the CEX2C hardware and firmware available, this is a limited subset of the CEX3C functions described in this document. --Refer to http://www.ibm.com/security/cryptocards/pciecc/ordersoftware.shtml for current information about restrictions and recommendations about usage of CCA 4.2 with Linux on System z distributions, a summary follows below. --Only 64-bit versions of CCA for Linux on System z host software are provided. 31-bit support is not provided. --------------------------------------------------------------- 2. RESTRICTIONS 2.1 Restriction: Handle the more flexible CCA 4.2 requests correctly 2.1.1 Summary of Restriction For CCA 4.2, the CCA host library (libcsulcca.so) was changed to allow more flexible preparation of requests to be sent to the adapter. The change allows very large key block support, among other changes. The z90crypt device driver as it exists in currently available Linux distributions has the same limitation as older CCA host library code, and therefore can not handle all requests issued by CCA 4.2 correctly. Refer to the next section for distribution updates that no longer have the restriction. 2.1.2 Circumvention and Fixes No circumvention can be recommended at this point in time. Availability of Linux on System z distribution-updates which include a fix will be documented on http://www.ibm.com/security/cryptocards/pciecc/ordersoftware.shtml as an update to this document (RELEASENOTES). The following distribution releases and maintenance updates (for kernel) include the fix for the restriction. You will not run into the restriction if your kernel has the indicated (or a higher) level: Red Hat Enterprise Linux (RHEL) distributions: - RHEL 5.8 maintenance update kernel-2.6.18-308.8.1.el5 available since May 2012 - RHEL 6.2 maintenance update kernel-2.6.32-262.el6 available since June 2012 - RHEL 6.3 kernel-2.6.32-279.el6 available since June 2012 SUSE Linux Enterprise Server (SLES) distributions: - SLES 10 SP4 maintenance update kernel 2.6.16.60-0.97.1 available since June 2012 - SLES 11 SP2 maintenance update kernel 3.0.31-0.9.1 available since June 2012 2.1.3 Detailed Description of Restriction Verbs that may send or return a lot of data (of certain types, such as lists of key labels or key tokens) or large key tokens are limited by an issue in the current version of the z90crypt device driver buffer handling to a smaller amount of data or key token size than would normally be allowed. The following scenarios clarify what to avoid to prevent this restriction from leading to errors. 2.1.4 Restriction scenarios/examples (1) sending or requesting a large amount of certain types of data: CSNDRKL: This verb returns a list of labels or tokens for a specified set of retained keys. Specifying a large number for the key_labels_count or retained_keys_count parameter can result in more return data than the cryptographic device driver can handle. Because a key label is 64 bytes, do not specify key_labels_count values greater than 75. Crossing this limit results in return code 8 reason code 1106 error, indicating the data is too large to be returned (it would be truncated). CSNDRKX: This verb has the potential to send large objects for parameters certificate, certificate_parms and extra_data. Avoid using a combined value for these parameters that greatly exceeds 4096 Bytes. The actual value of the threshold varies with the size of other parameters and so cannot be specified exactly. Crossing this limit results in error return code 8 reason code 343. (2) processing extremely large key tokens. CSNBT31I, CSNBT31X, CSNBKYT2 These verbs handle TR-31 key blocks, which can be up to 9992 Bytes (if 9 KB or more of optional block sections have been added). Due to the z90crypt restriction, TR-31 key blocks should be built specifying no more than 4096 Bytes of optional block sections. Crossing this limit results in error return code 8 reason code 343. ---------------------------------------------------------------