If you're moving z/OS 2.5 or 3.1 to z/OS 3.2, you may start seeing AT-TLS connection failures. As you work through the z/OSMF upgrade workflows for z/OS 3.2, you’ll notice updates to System SSL and AT-TLS defaults that could impact environments relying on legacy configurations or default TLS settings.

This article outlines common issues we've observed during upgrades and practical steps to help you troubleshoot and resolve them.

Key changes to TLS defaults in z/OS 3.2

•  TLS Protocols: Only TLSv1.2 is enabled by default (unless TLSv1.3 is explicitly enabled). All other TLS protocol versions are disabled by default.
•        Cipher Suites: The default cipher list now includes only 4-character specifications, all requiring ICSF
  •        C030 - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  •        C02C - TLS_ECDHE_ECDSA_WITH_AES_256_ GCM_SHA384
  •        C02F - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  •        C02B - TLS_ECDHE_ECDSA_WITH_AES_128_ GCM_SHA256
•        Signature Algorithms: SHA1, SHA224 and DSA signature algorithms are removed from the default signature algorithms used by X.509 certificates and TLS handshake messages
•        New parameter CrlSigAlgPairs is added to the AT-TLS policy statement TTLSGskAdvancedParms to specify the allowed signature algorithms for a Certificate Revocation List (CRL) retrieved from a LDAP or an HTTP server during revocation checking
•       Elliptic Curve order: Default client elliptic curve list order has changed. 

With the changes outlined above, environments most affected will be those that rely on SSL default policies or legacy configurations using outdated environment variables.

Troubleshooting AT-TLS Failures

To help troubleshoot AT-TLS connection issues, IBM provides diagnostic messages:

• EZD1286I is issued to the Syslog Daemon (SYSLOGD) when AT-TLS encounters an error and trace level 2 (Error) is enabled.
• EZD1287I is issued to the TCP/IP job log when an error occurs, and trace level 1 (Error) is enabled.

For comprehensive diagnostics, it's recommended to set the trace level to 255. You can enable this by adding TRACE 255 to either the TTLSEnvironmentAction or TTLSConnectionAction statements in your AT-TLS policy file. Alternatively, if you're using the Network Configuration Assistant, you can set trace level 255 directly within each Connectivity Rule or at the System Image Level. The resulting trace output will be directed to SYSLOGD.

Example on how to do it in Network Configuration Assistant at the Connectivity Rule level:

Regardless of where you update the logging/trace level, once you save the modified AT-TLS policy file, you have to update the Policy Agent with the MODIFY PAGENT,UPDATE command to put the change into effect.

Verify Policy

Now that you've identified the return code from the AT-TLS messages, use the z/OS Unix pasearch -t command to view active AT-TLS policy details. This shows the currently installed policy on the TCP/IP stack, including timestamps for creation and updates.

Keep in mind that the output from pasearch -t reflects what is configured in the AT-TLS policy. zERT records, on the other hand, show the negotiated values during a TLS handshake, not what’s configured.

Common Issues & Fixes

With the changes introduced in z/OS 3.2 Communications Server, the most commonly observed return codes are 402, 467 and 455. These codes are typically associated with configuration mismatches or unsupported parameters between the client and server applications.

1. Return code 402 - An SSL cipher suite could not be agreed upon between the client and server. [NR1] 
   Fix: Instead of selecting the "SSL Defaults" cipher in Network Configuration Assistant, configure your ciphers directly under the Security Level – Ciphers tab.

To do this:

1. 1.        Select the appropriate Security Level.
   2.        Navigate to the Ciphers tab.
   3.        Choose "Use only selected ciphers".
   4.        In the "Select Cipher Suites for SSL and TLS V1.0–1.2" section, click Actions → Choose Ciphers... to manually select the desired cipher suites.

Save the change and install the policy rule.

---

     2. Return code 467- Signature algorithm not in signature algorithm pairs list.

In z/OS 3.2, the following SignaturePairs in red have been removed from the default.

0601 SHA-512 with RSA

0603 SHA-512 with ECDSA

0501 SHA-384 with RSA

0503 SHA-384 with ECDSA

0401 SHA-256 with RSA

0403 SHA-256 with ECDSA

0402 SHA-256 with DSA

0301 SHA-224 with RSA

0303 SHA-224 with ECDSA

0302 SHA-224 with DSA

0201 SHA-1 with RSA

0203 SHA-1 with ECDSA

0202 SHA-1 with DSA

If the remote peer does not support or is not configured to accept the new default hash and signature pairsz, you will need to either explicitly include those SignaturePairs in your AT-TLS policy or update the remote peer’s configuration accordingly. This requirement also applies to the local side: if the hash and signature algorithm specified in the SignaturePairs does not match the certificate used locally, you must update the AT-TLS policy to include the appropriate SignaturePairs.

For example, if you are using an RSA certificate with a 1024-bit key length, you need to include SignaturePair 0201 to ensure compatibility.

Please note that the fields highlighted in red above are not deprecated, they are simply no longer included by default. You must now define them explicitly in your policy if needed.

Here is an example to add SignaturePairs value(s) in Network Configuration Assistant:

       3. Return code 455 ICSF services are not available

ICSF must be active to support the four ciphers that System SSL now defaults to:

• •       These are the four-character ciphers: C030, C02C, C02F, and C02B.
  •       They use Elliptic Curve Diffie-Hellman Ephemeral (ECDHE) key exchange with AES-GCM encryption and SHA-256/SHA-384 hashing.
  •       These ciphers are only supported with TLS 1.2 and require ICSF to be running.
  •       To use these ciphers, access is required to the following profiles in the CSFSERV class: CSF1GKP, CSF1GAV, and CSF1TRD.

Note: After making any changes to the AT-TLS policy, update the Policy Agent with the MODIFY PAGENT,UPDATE command to put the change into effect. Then use the the pasearch -t output to confirm that the ‘Policy created’ and ‘Policy updated’ timestamps your expected changes. 

Guideline: Do not rely on defaults and configure the values you require for your application. The following table summarizes key AT-TLS parameters, their defaults, and how they interact with System SSL settings. Use this as a quick reference when reviewing or updating your AT-TLS policies.

	AT-TLS statement/parameter	AT-TLS has a default?	Uses System SSL defaults?	System SSL Environment variables that override System SSL defaults
TLS protocol versions	TTLSEnvironmentActionParms statement:     TLSv1.3     TLSv1.2     TLSv1.1     TLSv1.0     SSLv3     SSLv2	Yes, TLSv1.2 On All other parameters set to Off	No	N/A
Cipher suites	TTLSCipherParms statement     V3CipherSuites4Char     V3CipherSuites     V2CipherSuites	No	Yes	GSK_V3_CIPHER_SPECS_EXPANDED
Signature pairs for certificates and TLS handshake messages	TTLSSignatureParms statement: SignaturePairs parameter	Yes	No	N/A
Client ecurves	TTLSSignatureParms statement: ClientECurves parameter	Yes	No	N/A
Signature algorithms for signing the OCSP response	TTLSGskOcspParms statement: OcspResponseSigAlgPairs	No	Yes	GSK_OCSP_RESPONSE_SIGALG_PAIRS
Signature pairs for signing the CRL response	TTLSGskAdvancedParms CrlSigAlgPairs	No	Yes	GSK_CRL_SIGALG_PAIRS

In this article, we highlighted several issues frequently observed during our in-house testing. Our goal is to help you quickly identify and resolve these problems independently. If issues persist, IBM Support is here to help—don’t hesitate to open a case.

- By Panit Nakajitti