II13516: MustGather: Read first for FTP Client and Server TLS Support for Z/OS COMMUNICATIONS SERVER

APAR status

• INTRAN

Error description

• ================================================================
  1) Implicit TLS connections over port 990
  The use of port 990 to implicitly protect FTP sessions was
  included in the early drafts of the IETF documents that describe
  how to use TLS with FTP, but has been removed from the latest
  drafts. We strongly recommend not starting the FTP server on
  port 990 - if a server is started on this port, not all secure
  FTP clients will be able to connect to it. The FTP server can
  provide equivalent support on a different port by specifying the
  following in FTP.DATA:
     EXTENSIONS AUTH_TLS
     SECURE_FTP REQUIRED
     SECURE_CTRLCONN PRIVATE
     SECURE_DATACONN PRIVATE
  We also recommend not using our FTP client port 990 to connect
  to the FTP server. The FTP client may not be able to connect to
  all servers on this port.  The FTP client can be configured to
  require TLS security by invoking the FTP client with the -r TLS
  option.
  Common Errors using port 990 for a TLS FTP based connection:
  FTP Server trace, option SEC, may show:
  authClient: init failed with rc = 410 (GSK_ERR_BAD_MESSAGE)
  EZYFT96I TLS handshake failed
      or
  authClient: init failed with rc = 406 (GSK_ERR_IO)
  EZYFT96I TLS handshake failed
  The FTP client trace, option SEC, may show:
  authServer: secure_socket_init failed with rc = 410
  (GSK_ERR_BAD_MESSAGE) EZA2897I Authentication negotiation failed
      or
  authServer: secure_socket_init failed with rc = 406 (GSK_ERR_IO)
  EZA2897I Authentication negotiation failed
  2) AUTH SSL support
  AUTH SSL support was included in early drafts of the IETF
  documents that describe how to secure FTP sessions. It was
  replaced by the AUTH TLS command.  The z/OS FTP server will
  accept the AUTH SSL command.  The z/OS FTP client does support
  the AUTH SSL command with a PTF.  The PTFs are UQ96093, UQ90239,
  and UQ90240.
  In the client FTP.DATA code the following to have the
  client send AUTH SSL.
  SECURE_MECHANISM SSL
  3) TLS connections through Firewalls
  TLS connections through firewalls can pose multiple challenges.
   3A) NAT Firewall on Client side:
       Firewalls doing Network Address Translation(NAT) may alter
       the FTP commands being sent, like the PORT command.  These
       firewalls require access to the data, which is not possible
       when the data has been encrypted.  We recommend using
       Firewall Friendly data connections for the z/OS FTP client,
       by coding FWFRIENDLY TRUE in FTP.DATA. The z/OS FTP client
       will send the PASV command instead of the PORT command.
   3B) NAT Firewall on Server side:
       If a NAT firewall is running on the server side, the PORT
       command can be used to open data connections, but the PASV
       command may not work.  The NAT firewall will need to alter
       the response to the PASV command, which is not possible
       when the data has been encrypted.  Ensure FWFRIENDLY is set
       to FALSE.
   3C) NAT Firewall on both Client and Server:
       The EPSV command must be used by the client and understood
       by the server.  The EPSV command is supported by the z/OS
       FTP server with release z/OS 1.4 or above and by the z/OS
       FTP client for z/OS 1.4 or above with APAR PQ80281 applied.
   3D) Firewalls which place requirements on data being sent on
       the control connection:
       TLS encrypted FTP sessions may not work through firewalls
       which require data on the control connection to follow
       specific formats. Since the data is encrypted, rules can't
       be applied to the format of the data being sent. If a
       firewall requires each packet end in a Carriage Return and
       Line Feed, the TLS encrypted packets may be rejected and
       the FTP session may be terminated abnormally. The firewall
       may need to be configured to allow TLS FTP traffic.
  4) Common TLS Configuration Problems:
      FTP Client fails with message EZA2897I Authentication
      negotiation failed.
       Obtain a FTP client trace with the SEC CMD SOC(3) and FLO
       options. If trace shows:
       P1- ftpAuth: TLS init failed with rc = 408
           (GSK_ERR_BAD_KEYFILE_PASSWORD)
       A1- This can occur when using gskkyman. Ensure that the
           password is stored in a stash file
           and that the FTP client can access this file.
       P2- authClient: init failed with rc = 410
           (GSK_ERR_BAD_MESSAGE)
       A2- No keyring file was specified in FTP.DATA.
       P3- authClient: 068 init failed with rc = 422
           (GSK_ERR_BAD_V3_CIPHER)
       A3- If using CIPHERSUITE keyword in FTP.DATA, ensure the
           proper System SSL FMIDs have been installed for the
           ciphers specified & the CIPHERSUITE statements need to
           be coded in the order of preferred usage.
  5) Documentation needed for FTP TLS problems
     5A) FTP trace with DEBUG options SOC(3), SEC, CMD, FLO
         The client joblog already contains this information.
     5B) System SSL API trace -
         For z/OS 1.2 and 1.3, the trace is turned on by setting
         the environment variable GSK_TRACE_FILE to a HFS file
         where output should be directed.
         The following ENVAR statement should be added to the FTP
         server started proc or the FTP client's JCL:
         ENVAR("GSK_TRACE_FILE=/tmp/trace.filename")
         For z/OS 1.4 and above, the trace is turned on by setting
         the GSK_TRACE variable and optionally coding the
         GSK_TRACE_FILE.  The default filename for GSK_TRACE_FILE
         is /tmp/gskssl.%.trc, where the % becomes the process ID.
         Set the GSK_TRACE variable to 0xFFFF.  The following
         ENVAR statement should be added to the FTP server started
         proc or the FTP client's JCL:
         ENVAR("GSK_TRACE=0xFFFF")
         After obtaining the trace, format the trace file with the
         following OMVS command:
         gsktrace source_file > formatted_file
         Please review the System SSL Programming manual for more
         information.
  Note: After collecting the System SSL trace and formatting
  it in the /tmp directory.  It is recommended that this
  file be ftp'd to another system or moved to an MVS dataset.
  The reason is that the /tmp dataset is typically not
  a huge dataset and if it becomes full it can cause applications
  that use the /tmp for their STDOUT to fail during
  initialization.
     5C) Use the RACF RACDCERT command to list information on
         Certificate being used.
         ex. RACDCERT ID(user) LIST to list cert. information
             RACDCERT ID(user) LISTRING(ringname) for ring info.
             note: 'ringname' is the name associated with the
                              KEYRING keyword in the FTP.DATA file
                   'user'     is name of certificate being used.
                              For the default certificate for the
                              FTP Server, status must be TRUST.
  6)  Additional Sources of Information on for information on
      setting up the FTP client and server to use TLS.
      - Redbook, Communications Server for z/OS V1R2 TCP/IP
        Implementation Guide Volume 7: Security, SG24-6840-00
      - z/OS V1R2.0 CS: IP Configuration Guide, SC31-8775-01
      - System SSL Programming manual
  7) Applicable APARs
     PQ83233 - R14,R15 will only load kerberos DLC when needed
     PQ80281 - R14 EPSV (IPV4) support added for FTP client.
               Usefull when passing thru a NAT firewall. Also,
               ability for Server to restrict ephemeral ports
               obtained.
               Adds PASSIVEDATAPORTS + EPSV4 keywords to FTP.DATA
     PQ84185 - R14, allow ftp client to bypass password prompt if
               using TLS and the server certificate contains the
               client userid and password.
               Adds SECURE_PASSWORD statement support to FTP.DATA
     PQ82774 - R12, PQ78314 R14, provide capability to configure
               the Secure FTP port or to disable it. Can be used
               to allow non-secure traffic over port 990.
               Adds TLSPORT statement support to FTP.DATA
     PQ72957 - R12,R14, FTP transfer failure due to Close Notify
               Also needs SSL Apar OA02499 on R12
     PQ69309 - R12,R14 Home directory not set correctly when
               using TLS
     PQ55642 - R12, Replaces -A option with the -r option on
               the FTP client.
     PQ82774 - R12, New Function to provide the ability to FTP
               using Port 990 in a non-secure environment.
     PQ78314 - R14, New Function to provide the ability to FTP
               using Port 990 in a non-secure environment.
  8) Keywords: R120 R140 R150 R160 R170 R180 R190 FTP SSL TLS
               TCPIPINFO 5655HAL00 FTPS
  

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