II13369: MUSTGATHER: READ FIRST FOR TN3270 TELNET SSL COMMON PROBLEMS

APAR status

• INTRAN

Error description

• ****************************************************************
  *                                                              *
  *  Information in this APAR is no longer being updated.        *
  *  Please use the following URL for the most current           *
  *  information:                                                *
  *                                                              *
  * http://www.ibm.com/support/docview.wss?rs=852&uid=swg21318807
  *                                                              *
  ****************************************************************
    Readfirst: This info apar provides information that will aide
    in configuring and diagnosing problems for TN3270 SSL
    connections.
    .
    Additional Keywords:
    5655HAL00 R50A R120 R140 R150 R160 SSL SYSTEM SSL HANDSHAKE
    FAILS SECURE PORT SAF SAFCERT KEYRING ENCRYPTION EXPRESS
    LOGON FEATURE ELF GSKKYMAN SKIT ERROR CODES
  
      TCPIPINFO
    .
  ***********************************************************
                         SSL REFERENCES
  ***********************************************************
  WEBSITES:
  
  SSL 3.0 SPECIFICATION -
    http://wp.netscape.com/eng/ssl3/,
  TLS V1.0 SPECIFICATIONS
    ftp://ftp.rfc-editor.org/in-notes/rfc2246.txt
  Examples of client and server traces -
    http://home.netscape.com/eng/ssl3/traces/index.html,
  IBM Redbooks -
    http://www.redbooks.ibm.com,
  .
      This return code may be received if the name in the
  IBM MANUALS:
  FOR DETAILS ON CONFIGURING TN3270 SERVER
    OS/390 V2R10.0 System SSL Programming Gde and Ref
    z/OS Communications Server: IP Config Guide and Reference,
    Redbook SG24-5629, OS/390 Security Server 1999 Updates:
    Installation Guide, Chapter 10.
    Redbook SG24-5227, IBM Communication Server for OS/390 V2R10,
    TCP/IP Implementation Guide, Chapter 13.
  - REDBOOK SG24-6840-00, Communications Server for z/OS
    V1R2 TCP/IP Implementation Guide Volume7: Security
  FOR INFORMATION ON USING GSKKYMAN UTILITY.
    z/OS System Secure Sockets Layer Programming.
  FOR INFORMATION ON RACDCERT CERTIFICATE MANAGEMENT.
    OS/390 Secureway Server RACF Command Language and Reference,
    SC28-1919.
    z/OS SecureWay Security Server, RACF Security Administrator's
    Guide.
  FOR DETAILS ON CONFIGURING TELNET CLIENT.
    IBM SecureWay Host On-Demand: Enterprise Communications
    in the Era of Network Computing.
    Redbook SG24-6182, IBM HOST Access Client Package
    Redbook SG24-6540, Putting the Latest Security Features
    to Work.
  FOR ADDITIONAL INFORMATION ON ICSF HARDWARE ENCRYPTION.
    z/OS ICSF Administrator's Guide
  .
  ***********************************************************
                      SYSTEM SSL RETURN CODES
  ************************************************************
  For a detailed description of return codes see
  OS/390 V2R10.0 System SSL Programming Gde and Ref.
  .
  /* The following may be returned by gsk_secure_soc_init */
  GSK_ERROR_NO_CIPHERS                    -1 = FFFFFFFF
  GSK_ERROR_NO_CERTIFICATE                -2 = FFFFFFFE
  GSK_ERROR_BAD_CERTIFICATE               -4 = FFFFFFFC
  GSK_ERROR_UNSUPPORTED_CERTIFICATE_TYPE  -6 = FFFFFFFA
  GSK_ERROR_IO                            -10 = FFFFFFF6
  GSK_ERROR_BAD_MESSAGE                   -11 = FFFFFFF5
  GSK_ERROR_BAD_MAC                       -12 = FFFFFFF4
  GSK_ERROR_UNSUPPORTED                   -13 = FFFFFFF3
  GSK_ERROR_BAD_CERT_SIG                  -14 = FFFFFFF2
  GSK_ERROR_BAD_CERT                      -15 = FFFFFFF1
  GSK_ERROR_BAD_PEER                      -16 = FFFFFFF0
  GSK_ERROR_PERMISSION_DENIED             -17 = FFFFFFEF
  GSK_ERROR_SELF_SIGNED                   -18 = FFFFFFEE
  GSK_ERROR_BAD_MALLOC                    -20 = FFFFFFEC
  GSK_ERROR_BAD_STATE                     -21 = FFFFFFEB
  GSK_ERROR_SOCKET_CLOSED                 -22 = FFFFFFEA
  GSK_ERROR_GSK_INITIALIZATION_FAILED     -23 = FFFFFFE9
  GSK_ERROR_HANDLE_CREATION_FAILED        -24 = FFFFFFE8
  GSK_ERROR_BAD_DATE                      -25 = FFFFFFE7
  GSK_ERROR_BAD_KEY_LEN_FOR_EXPORT        -26 = FFFFFFE6
  GSK_ERROR_NO_PRIVATE_KEY                -27 = FFFFFFE5
  GSK_BAD_PARAMETER                       -28 = FFFFFFE4
  GSK_ERROR_INTERNAL                      -29 = FFFFFFE3
  GSK_ERROR_WOULD_BLOCK                   -30 = FFFFFFE2
  GSK_ERROR_LOAD_GSKLIB                   -31 = FFFFFFE1
  GSK_ERROR_API_NOT_AVAILABLE             -32 = FFFFFFE0
  GSK_ERROR_BAD_KEYPAIR                   -33 = FFFFFFDF
  GSK_ERROR_BAD_CRL                       -34 = FFFFFFDE
  GSK_ERROR_VALIDATION                    -35 = FFFFFFDD
  GSK_ERROR_CRYPTO                        -36 = FFFFFFDC
  GSK_ERROR_ASN                           -37 = FFFFFFDB
  GSK_ERROR_LDAP                          -38 = FFFFFFDA
  GSK_SOC_BAD_V2_CIPHER                   -40 = FFFFFFD8
  GSK_SOC_BAD_V3_CIPHER                   -41 = FFFFFFD7
  GSK_SOC_BAD_SEC_TYPE                    -42 = FFFFFFD6
  GSK_SOC_NO_READ_FUNCTION                -43 = FFFFFFD5
  GSK_SOC_NO_WRITE_FUNCTION               -44 = FFFFFFD4
  GSK_SOC_BAD_SEC_TYPE_COMBINATION        -45 = FFFFFFD3
  GSK_ERROR_UNKNOWN_ERROR                 -99 = FFFFFF9D
  .
  /* The following may be returned by gsk_secure_soc_read */
  GSK_ERROR_BAD_BUFFER_SIZE               -100 = FFFFFF9C
  GSK_ERROR_BAD_SSL_HANDLE                -101 = FFFFFF9B
  GSK_ERROR_TIMEOUT                       -102 = FFFFFF9A
  GSK_ERROR_BAD_BUFFER                    -103 = FFFFFF99
  /* The following may be returned by gsk_secure_soc_reset */
  GSK_ERROR_NOT_SERVER                    -50 = FFFFFFCE
  GSK_ERROR_NOT_SSLV3                     -51 = FFFFFFCD
  GSK_ERROR_NOT_SSLV3_CLIENT              -52 = FFFFFFCC
  GSK_SECURE_SOC_RESET_OK                   0
  .
  /* The following may be returned by gsk_uninitialize */
  GSK_CLOSE_OK                    0
  GSK_ERROR_CLOSE_FAILED         -1
  
  .
  ************************************************************
                      EXPRESS LOGON FEATURE
  ************************************************************
  Common Problems:
  ICH408I message logging onto selected application is usually
  the result of invalid application name defined in RACF
  PTKTDATA Profile. To resolve this problem see
  SA22-7683-00 SecureWay Security Server RACF Security
  Administrator's Guide, section Defining Profiles in the
  PTKTDATA class.
  .
  The pass ticket is validated by RACF when the application
  sends the RACROUTE command to RACF. RACF compares the
  application name passed in RACROUTE command to the application
  name defined in PTKTDATA Profile. There are several ways to
  determine the application name.
  1) To determine application ID for APPC, CICS, IMS,TSO, VM,
     and MVS Batch, see SA22-7683-00, section Defining Profiles
     PTKTDATA class.
  2) Some applications do not pass any application name to
     RACF on the RACROUTE command.  For these applications,
     RACF uses the default definition defined for MVS
     Batch Jobs.
  3) Some other applications (mostly OEMs) pass the VTAM
     defined application name. For these applications
     refer to the product's reference manual to determine
     how RACF is called or obtain the applicaion name from
     RACF msg ICH408I for a logon attempt.
  .
  Once the correct application name has been defined to RACF
  PTKTDATA Profile, the application ID defined must be coded
  in the application ID popup window of the client.
  ************************************************************
  .
  NOTE: For z/OS Commserver hints and tips go to:
  http://www.ibm.com/software/network/commserver/support/
  ====================================================
  SSL INITIALIZATION AND HANDSHAKE FAILURES
  ====================================================
  P1)  Telnet SSL Handshake Fails, FFFFFFFE (-2),
       GSK_ERROR_NO_CERTIFICATE, after IPLing system. RACF
       database s used to store certificate.
  S1)  SOLUTION-
        A: Ensure that the server certificate is marked as the
          default certificate.
        B: Recreate certificate and keyring in RACF database
                                                                 X
  P2)  EZZ6035I TELNET DEBUG CLIENT IPADDR..PORT xx.xx.xx.xx..xxx
         CONN: 00009AF1  LU:           MOD: EZBTTSMT
         RCODE: 6002-00  SSL/TLS handshake failed.
         PARM1: 000001F7 PARM2:   PARM3: GSK_SECURE_SOCKET_INIT ,
         (PARM1,1F7 = (503),Socket read request would block)
  S2)  SOLUTION:
        If this is a HOD client that does not accept negotiated
        SSL, then change the Telnet-negotiated setting from YES
        to NO.
                                                                 x
  S2)  SOLUTION:
        If this is a PCOMM client, ensure that the password for
        the key database file (.kdb) has not expired.  Use the
        certificate management utility (v5.7) to check.
        Programs->IBM Personal Communications->Utilites->
        Certificate Management and then open under the
        key database file pulldown.  If the password has
        expired, the client will terminate the connection
        during the handshake.
  P3) EZZ6035I TELNET DEBUG PROFILE WARNING,LINE:     0 MOD:
       RCODE: 600F-00  SSL task setup failed.
       PARM1: 00000004 PARM2:          PARM3:
       (PARM1 04 = means, GSK_KEYFILE_BAD_PASSWORD)
      EZZ6035I TELNET DEBUG PROFILE ERROR,LINE:   127 MOD: EZBTDPR
       RCODE: 6004-00  SSL initialization failed.
  S3) SOLUTION:
       - verify the password is correct
       - verify the stash file is in the same directory as the
         keyring file.
                                                                 x
  P4) EZZ6035I TELNET DEBUG CLIENT IPADDR..PORT 10.40.2.11..1690
       CONN: 00000017  LU:           MOD: EZBTTSMT
       RCODE: 6002-00  SSL/TLS handshake failed.
       PARM1: 00000006 PARM2:   PARM3: GSK_SECURE_SOCKET_INIT
       (PARM1,06 = GSK_KEY_LABEL_NOT_FOUND)
  S4) SOLUTION:
        List the certificates in the keyring database and check to
        ensure they are defined correctly on both the server and
        client.
                                                                 x
  P5) EZZ0677I THE CLIENT CONFIG SOCKET 3 TIMED OUT, after
       customizing TN3270 SECURE port.
  
       Could also inhibit the stack from coming down cleanly,
       a force may be required.
  S5) SOLUTION:
       Check the following-
       1) Check system log for 0C4 abend prior to EZZ0677I
          message. Proceed to steps 2-4.
       2) Make sure that hlq.SGSKLOAD and CBC.SCSBDLL are APF
          authorized. Issue MVS display prog command to confirm.
       3) The STEPLIB DD in the TCPIP started proc has library
          hlq.SGSKLOAD.
       4) If RACF is used to manage certficates, make sure that
          hlq.SGSKLOAD is program controlled.
       Refer to SecureWay Security Server RACF Command Language
       Ref. for the correct command to check if the library is
       program controlled.
                                                                 x
  P6) EZZ6035I TELNET DEBUG PROFILE WARNING,LINE:
        RCODE: 600F-00  System SSL initiation failed.
        PARM1: 0000006A PARM2: PARM3: GSK_ENVIRONMENT_INIT
        (PARM1,6A = (106), The System SSL runtime is unable
        to decrypt a key database, Either the supplied
        database password is incorrect or the database is damaged.
  S6) SOLUTION:
       1) Ensure that the correct key database password is used.
       2) Recreate the database if the error persists.
                                                                 x
  P7) EZZ6035I TELNET DEBUG 207.133.71.245..53663 768
       CONN: 00000CF7  LU:   MOD: EZBTTSMT
       RCODE: 6002-00  SSL handshake failed.
       PARM1: FFFFFFF1 PARM2: 00000000 PARM3: 00000000
       (PARM1, FFFFFFF1= (-15) means GSK_ERROR_BAD_CERT)
  S7) SOLUTION:
       Ensure that the server certificate in the keyring database
       specified in TELNETPARMS section of Profile matches the
       server certificate stored in the client's keyring database.
                                                                 x
  P8) EZZ6035I TELNET DEBUG 10.77.57.6..1071 493
       CONN: 0001E295  LU:   MOD: EZBTTSMT
       RCODE: 6002-00  SSL handshake failed.
       PARM1: FFFFFF9D PARM2: 00000000 PARM3: 00000000
       (PARM1 FFFFFF9D,(-99) means GSK_ERROR_UNKNOWN_ERROR
  S8) SOLUTION:
       - Ensure keyring is defined in RACF database
       - Ensure the CASE is correct for the name of the keyring
       - Ensure the userid for the TCPIP started task and the
         owner of the keyring are the same.
       - If using hardware encryption -
           * CSFSERV facility class must be actvie and userid for
             TCPIP started task must have read access to CSFSERV
             resource.
           * ensure apar OW52700 and OW50359 are installed.
                                                                 x
  P9) EZZ6034I TELNET CONN 0001CC01 LU **N/A**  CONN DROP ERR 6002
       IPADDR..PORT 10.66.16.46..1047        EZBTTSMT
       Received after adding renewed CA certificate to RACF
       keyring database.
  S9) SOLUTION:
       - Add the certificate using the same userid as the one used
         for the original certificate.
       - Try using the RACDCERT REMOVE command to delete the
         expired certificate from the keyring. This will ensure
         the server is getting the correct certificate.
  .
  P10) EZZ6035I TELNET DEBUG DETAIL CLIENT 598
       IP..PORT: xxx.xx.xx.xx..xxxx
       CONN: 00001179  LU:           MOD: EZBTTSMT
       RCODE: 6002-00  SSL/TLS handshake failed.
       PARM1: 000001B5 PARM2:00000000 PARM3:GSK_SECURE_SOCKET_INIT
       where x1B5 = 437 decimal = GSK_ERR_CONNECTION_CLOSED
  S10) SOLUTION:
      This return code may be received if the name in the
      server's certificate does not match the exact
      name representing the ipaddress on System z. The system
      programmer can request that a DNS alias be created with an
      alias that matches the name on the certificate and retry
      to establish the secure session.
  

Local fix

Problem summary

Problem conclusion

Temporary fix

Comments

APAR Information

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

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

Fix information

Applicable component levels