Skip to main content

Techdocs Library > Flashes >

Changes to the CSNDSYG API on the Crypto Express3 on zEnterprise 196

Document Author:
Additional Author(s):

Sheri DeGroodt
Anne Dames

Document ID:


Doc. Organization:

IBM Systems

Document Revised:


Product(s) covered:

IBM eServer zSeries; IBM System z; ICSF; z196; zEnterprise; zEnterprise 196

Abstract: The Driver 86 microcode that supports the Crypto Express3 card on the zEnterprise 196 introduced a change to the Symmetric Key Generate API which MAY require application changes. This Flash is for account teams and customers that plan to install a zEnterprise as it describes the applications and products that need to be reviewed before migrating to the 196.

When operational keys need to be shared with partners, those keys must be protected while in transit to the partner. The Symmetric Key Generate (CSNDSYG) API provides a way to create a symmetric key and store it securely within your own environment while preparing the key for transmission. The API is used to generate and encrypt an AES or DES data key in two formats: enciphered under a symmetric key and encrypted under an RSA public key. The symmetric key may be either a Key Encrypting Key (KEK) or the master key. If the key is enciphered under the master key, it is protected by that master key within the z/OS and ICSF environment for local use. If it is enciphered under a KEK, it can be securely shared with a partner who has a copy of that same KEK. The copy that is encrypted under an RSA public key can be securely shared with a partner who has the corresponding RSA private key.
The CSNDSYG API can be used to generate a DES importer or exporter key under an RSA public key according to the PKA92 formatting structure. PKA92 was adapted from methods used in the IBM Transaction Security System which was an early IBM encryption solution. The PKA92 process includes the Control Vector for the DES key in the RSA-encrypted block so that the key type information is transported with the key.

The documentation for the CSNDSYG API (SA22-7522, ICSF Application Programmer’s Guide) requires that when using PKA92 format, the Control Vector used in the RSA-encrypted copy of the generated key must be provided in an internal CCA format. However, this parameter was not validated and in fact, an external CCA format could be used (and was used by some customers) to provide the Control Vector.

In an attempt to provide more structure in the CCA environment, the microcode on the CEX3 on the z196 implemented additional validation for input parameters and this documented restriction is now being enforced. So an application invoking the CSNDSYG API on a pre-z196 system using an external CCA format key token would execute successfully even though the parameters were not correctly specified. However, when that application was moves to the z196 it will fail with a return code of 8 and reason code 181 (decimal). To correct the problem the application needs to use an internal CCA format, which might require application changes to define the key earlier in the program.

During the investigation of the problem it was determined that either an externally or internally formatted key token can meet the needs of passing the Control Vector to the CSNDSYG verb, and IBM plans to update the microcode to allow either format to be used. However, for the time being customers installing a z196 at the current Driver 86 level (Common Cryptographic Architecture code level 4.1.0z) will need to review their applications looking for the CSNDSYG API. If those applications are using the API with a PKA92 format then they need to confirm that the RSA_enciphered_key parameter is referencing an internal format key token. If so, no changes are required. If the application is using an external format for that key, then either that key will need to be changed to an internal format, or the application should not be used on a z196 until the updated MCL is available.

The MCL that supports both internally or externally formatted key tokens on the CSNDSYG API will be N29766.014 through 021, and will be part of Driver 86E. This MCL is specific to the z196 and became available on December 1, 2010. Customers can use the HMC ‘System Information’ display to show the highest MCL level received and applied for an EC. They can also review their received and applied MCLs via the ‘MCL Report’ under Machine Information on Resource Link.

Since ICSF already works with either format, there are no software changes. The ICSF manuals will be updated in a future release to reflect the new options on the API. Please contact your local account team for the latest info on the new LIC.


Hardware; Software


Operational Management


IBM System z Family

S/W Pillar(s):

IBM System z Software




zEnterprise, z196, 196, System z

The Techdocs Library
Is this your first visit to Techdocs (the Technical Sales Library)?

Learn more

Techdocs QuickSearch