PH63197: NEW FUNCTION - zERT monitoring enhancements

Obtain the fix for this APAR.

APAR status

• Closed as new function.

Error description

• NEW FUNCTION - zERT monitoring enhancements
  

Local fix

Problem summary

• ****************************************************************
  * USERS AFFECTED:                                              *
  * All users of the IBM Communications Server for z/OS 2.5 and  *
  * 3.1 IP: TCP/IP stack                                         *
  ****************************************************************
  * PROBLEM DESCRIPTION:                                         *
  * NEW FUNCTION - zERT has been enhanced to distinguish between *
  * TLS/SSH connections (successful and failed) and unprotected  *
  * connections. SMF 119 subtype 11 and 12 zERT records are      *
  * updated to indicate when a connection has a failed TLS/SSH   *
  * handshake. Also, SMF 119 subtype 12 zERT record is updated   *
  * to include additional certificate information.               *
  ****************************************************************
  * RECOMMENDATION:                                              *
  ****************************************************************
  

Problem conclusion

Temporary fix

Comments

• SMF 119 subtype 12 records have been updated for TLS and IPsec
  security sessions to include the certificate expiration and the
  serial number.
  When a TLS/SSH handshake fails:
  - zERT discovery will write a SMF119 subtype 11 record with a
  TLS/SSH section and set a flag to indicate a failed TLS/SSH
  handshake for the connection.
  - zERT aggregation will write a SMF 119 subtype 12 record with
  counts of failed handshakes for TLS/SSH security sessions during
  an SMF interval.
  
  Documentation updates have been made in the IP Configuration
  Guide, in the "How does zERT discovery provide the information?"
  section:
  For connections where a TLS, SSL, or SSH handshake was attempted
  but failed, the zERT connection detail record (SMF 119 subtype
  11) contains a protocol-specific section with an indicator that
  the handshake failed and all cryptographic attributes indicating
  unknown. This allows a failed handshake to be distinguished from
  an unprotected connection where no cryptographic protection was
  attempted.
  
  Documentation updates have been made in the IP Configuration
  Guide, in the "How does zERT aggregation provide the
  information?" section:
  For security sessions that represent TLS, SSL, or SSH failed
  handshakes, the zERT summary record (SMF 119 subtype 12)
  contains a non-zero failed handshake count in the zERT Summary
  Common section and a protocol-specific section with all
  cryptographic attributes indicating unknown.
  
  Documentation updates have been made in the IP Configuration
  Guide, in the "How does zERT enforcement work?" section:
  For a connection where a TLS, SSL, or SSH handshake is attempted
  but fails, the connection is evaluated against the zERT
  enforcement policy rules for the security protocol that is
  attempted. No cryptographic information beyond the attempted
  handshake type (TLS or SSH) is known for a failed handshake. For
  example, a connection with a failed attempt to negotiate a TLS
  security session will not match a TLS rule with specific TLS
  protocol values defined. However, it will match a TLS rule with
  no other characteristics defined.
  
  
  In the "zERT connection detail records (subtype 11)" topic in
  the z/OS Communications Server IP Programmer's Guide and
  Reference, documentation for the following sections have been
  updated:
  
  "zERT connection detail common section":
  SMF119SC_SAFlags
  -X'10': The local socket of this session is acting as the server
  (only meaningful when SMF119SC_SAIPProto indicates TCP)
  -X'08': The local socket of this session is acting as the client
  (only meaningful when SMF119SC_SAIPProto indicates TCP)
  
  "zERT TLS protocol attributes section":
  -SMF119SC_TLS_Handshake_Type - X'03': Failed handshake. When
  set, all the fields in the TLS protocol attributes section will
  contain binary zeroes or blanks except the SMF119SC_TLS_Source,
  SMF119SC_TLS_Protocol_Provider, SMF119SC_TLS_Handshake_Type, and
  SMF119SC_TLS_Neg_Cipher.
  -SMF119SC_TLS_Neg_Cipher - New EBCDIC value of 'FFFFFF' defined
  to indicate Unknown.
  
  "zERT SSH protocol attributes section":
  -SMF119SC_SSH_Prot_ver
  -SMF119SC_SSH_Flags - X'80': Failed handshake. When set, all the
  fields in the SSH protocol attributes section will contain
  binary zeroes or blanks except the SMF119SC_SSH_Source,
  SMF119SC_SSH_Protocol_Provider, and SMF119SC_SSH_Flags
  
  
  In the "zERT summary records (subtype 12)" topic in the z/OS
  Communications Server IP Programmer's Guide and Reference,
  documentation for the following tables have been updated:
  
  "zERT summary record common section":
  -SMF119SS_SAInitFailedHsConnCnt - Count of failed TLS or SSH
  handshakes for the life of this security session at the
  beginning of the summary interval.
  -SMF119SS_ SAEndFailedHsConnCnt - Count of failed TLS or SSH
  handshakes for the life of this security session at the end of
  the summary interval.
  
  "zERT summary record TLS protocol attributes section":
  -When the failed handshake count (SMF119SS_SAEndFailedHsConnCnt)
  is > 0, all the fields in this TLS section will contain binary
  zeroes or blanks except SMF119SS_TLS_Source and
  SMF119SS_TLS_Neg_Cipher.
  -SMF119SS_TLS_Neg_Cipher - New EBCDIC value of 'FFFFFF' defined
  to indicate Unknown.
  
  "zERT summary record SSH protocol attributes section":
  - When the failed handshake count
  (SMF119SS_SAEndFailedHsConnCnt) is > 0, all the fields in this
  SSH section will contain binary zeroes or blanks except except
  SMF119SS_SSH_Source.
  
  "zERT summary record TLS protocol attributes section" for server
  certificate information:
  -SMF119SS_TLS_SCert_Serial_Len - Server certificate serial
  number length in bytes.
  -SMF119SS_TLS_SCert_Serial - Server certificate serial number,
  left justified.
  -SMF119SS_TLS_SCert_Time_Type - Format of server certificate
  "not after" time (X'01': UTC, X'02': GT).
  -SMF119SS_TLS_SCert_Time - Server certificate "not after" time.
  
  "zERT summary record TLS protocol attributes section" for client
  certificate information:
  -SMF119SS_TLS_CCert_Serial_Len - Client certificate serial
  number length in bytes.
  -SMF119SS_TLS_CCert_Serial - Client certificate serial number,
  left justified.
  -SMF119SS_TLS_CCert_Time_Type - Format of client certificate
  "not after" time (X'01': UTC, X'02': GT).
  -SMF119SS_TLS_CCert_Time - Client certificate "not after" time.
  
  "zERT summary record IPSec protocol attributes section" for IKE
  local certificate information:
  -SMF119SS_IPSec_LclCert_Serial_Len - Local IKE certificate
  serial number length in bytes.
  -SMF119SS_IPSec_LclCert_Serial - Local IKE certificate serial
  number, left justified.
  -SMF119SS_IPSec_LclCert_Time_Type - Format of local IKE
  certificate "not after" time (X'01': UTC, X'02': GT).
  -SMF119SS_IPSec_LclCert_Time - Local IKE certificate "not after"
  time.
  
  "zERT summary record IPSec protocol attributes section" for IKE
  remote certificate information:
  -SMF119SS_IPSec_RmtCert_Serial_Len - Remote IKE certificate
  serial number length in bytes.
  -SMF119SS_IPSec_RmtCert_Serial - Remote IKE certificate serial
  number, left justified.
  -SMF119SS_IPSec_RmtCert_Time_Type - Format of remote IKE
  certificate "not after" time (X'01': UTC, X'02': GT).
  -SMF119SS_IPSec_RmtCert_Time - Remote IKE certificate "not
  after" time.
  

APAR Information

• APAR is sysrouted FROM one or more of the following:

• APAR is sysrouted TO one or more of the following:

  UO03557 UO03558

Modules/Macros

• EZBTCUTL EZASMF   EZBTCZRT EZASMF77 EZBDGHTB EZBITIN2 EZBSMZAM
  EZBSMZAI EZBTCPTM EZBSMSEC EZBTIGBL
  

Fix information

• Fixed component name

  TCP/IP MVS

• Fixed component ID

  5655HAL00

Applicable component levels

• R250 PSY UO03557

     UP25/07/10 P F507  

• R310 PSY UO03558

     UP25/07/10 P F507  

Fix is available

• Select the PTF appropriate for your component level. You will be required to sign in. Distribution on physical media is not available in all countries.