Steps for customizing the FTP client for TLS

You can customize the FTP client for TLS, but a better way to implement TLS security is by using AT-TLS.

Before you begin

Understand the following information:

The FTP client can be enabled to use either TLS or Kerberos, but not both at the same time.
To support TLS, the FTP server always provides server certificate authentication to all the clients to validate that the server is what it says it is. Therefore, a client key ring database is required to contain at least the certificate for the CA that signed the server certificate (or the server certificate if the server certificate is self-signed). For more information about key ring databases, see TLS/SSL security.
The FTP client can implement TLS security by itself, or the FTP client can be configured to use Application Transparent Transport Layer Security (AT-TLS) as a controlling application. For more information on AT-TLS, see Application Transparent Transport Layer Security data protection.
Guideline: Using AT-TLS is the best way to implement TLS security. With AT-TLS, for example, you can have the following implementation:
- Specify the label of the certificate to be used for authentication instead of using the default certificate
- Support SSL Session Key Refresh
- Support SSL Sysplex Session ID Caching
- Trace decrypted SSL data for FTP in a data trace
- Receive more detailed diagnostic messages in syslogd
Requirement: AT-TLS requires Policy Agent to be configured, and the TCP/IP stack to be enabled for AT-TLS. To configure AT-TLS, see Configuring the client systems.

Procedure

Perform the following steps to customize the FTP client for TLS:

Decide what level of RFC 4217, On Securing FTP with TLS, that you want the client to support.
- To have the client support On Securing FTP with TLS at the Internet draft level, code the following statement in the client's FTP.DATA configuration file:
```
TLSRFCLEVEL DRAFT
```
  This is the default. The z/OS® FTP client has supported TLS security at this level since V1R2. Code this statement in FTP.DATA to maintain this level of support.
- To have the client support On Securing FTP with TLS at the RFC 4217 level, code the following statement in the client's FTP.DATA configuration file:
```
TLSRFCLEVEL RFC4217
```
  The RFC On Securing FTP with TLS was published as RFC 4217 in October, 2005. The RFC differs from the Internet draft in its description of the AUTH, CCC, and REIN commands. This has implications for client subcommands such as AUTH and CCC. Generally, RFC 4217 is less restrictive than the Internet draft. For more information, see RFC 4217. For more information on RFC 4217 and using security mechanisms, see z/OS Communications Server: IP User's Guide and Commands.
Code the following statement in the client's FTP.DATA configuration file to enable the client for TLS:
```
SECURE_MECHANISM TLS
```
Decide what level of authentication you will use for TLS sessions:
- Server authentication only
- Client authentication level 1
- Client authentication level 2
- Client authentication level 3
For more information about server authentication and client authentication, see Secure Socket Layer overview.
Use a CERTAUTH virtual key ring, or create a client key ring database and add the certificates that you need to that database. If you are using server authentication only and the FTP server certificate is signed by a certificate authority (CA), the FTP client can use a CERTAUTH virtual key ring and you do not need to create a client key ring database. To use a CERTAUTH virtual key ring, use the key ring name *AUTH*/* .
If you cannot use a virtual key ring, create the client key ring database and add the certificates that you need to that database.

Every TLS session handshake includes server authentication. If a server certificate is self-signed, you must import that certificate to the key ring database of any client that will log in using TLS. If the server certificate is signed by a CA, the CA certificate used to sign the server certificate (rather than the server certificate itself) needs to be in the client key ring database. For more information, see Server authentication.

If you are using client authentication, you must add a certificate for the client to the client key ring database.

If you are using client authentication and self-signed client certificates, you must add a certificate for the client to the server key ring database. If a client certificate is signed by a CA, the CA certificate used to sign the client certificate needs to be in the server key ring database, rather than the client certificate.

For information about the client certificates you must create, see Client authentication.
Decide whether FTP will implement TLS security or AT-TLS will implement TLS security. The default is to have FTP implement TLS security. This setting is customized using the TLSMECHANISM configuration statement.
- To configure the FTP client to use AT-TLS for TLS security, code the following statement in FTP.DATA:
```
TLSMECHANISM ATTLS
```
- To configure the FTP client to implement TLS security by itself, code the following statement in FTP.DATA:
```
TLSMECHANISM FTP
```
  This is the default setting.
If using TLSMECHANISM FTP, you must configure the FTP client with the name of the key ring database. Code the following statement in FTP.DATA:
```
KEYRING client-keyring-database
```
For information about the KEYRING statement, see z/OS Communications Server: IP Configuration Reference.
If you specified TLSMECHANISM ATTLS, configure the AT-TLS policy for the FTP client. To configure AT-TLS, see Configuring the client systems.
Requirements:
- The FTP server and client are controlling applications. For more information about controlling applications, see Advanced application considerations.
  Code a TTLSEnvironmentAdvancedParms statement with the ApplicationControlled and SecondaryMap parameters; both parameters should specify the value On. The ApplicatonControlled parameter allows FTP to start and stop TLS security on a connection. The SecondaryMap parameter enables active or passive data connections to use the AT-TLS policy that is used for the control connection. You do not need to code any additional TTLSRule statements for the data connections.
- The FTP client requires the HandshakeRole parameter with the value Client to be coded on the TTLSEnvironmentAction statement.
- The TTLSRule statement for the FTP client requires the Direction parameter with the value Outbound.
A sample Policy Agent AT-TLS configuration showing the required policy configuration statements for AT-TLS is as follows:
```
   TTLSGroupAction  secure_ftp_client_group
   {
      TTLSEnabled On
   }
   TTLSEnvironmentAction secure_ftp_client_env
   {
      TTLSKeyringParms
      {
         Keyring client-keyring-database
      }
      HandshakeRole Client       
      TTLSEnvironmentAdvancedParms
      {
         ApplicationControlled On
         SecondaryMap  On
      }
      TTLSCipherParmsRef   ftp_client_ciphers   # Used to customize ciphersuites 
   }
TTLSCipherParms ftp_client_ciphers 
{
   # Sample ciphers.  Should be customized!
   V3CipherSuites TLS_RSA_WITH_AES_256_CBC_SHA
   V3CipherSuites TLS_RSA_WITH_3DES_EDE_CBC_SHA
   V3CipherSuites TLS_RSA_WITH_NULL_SHA 
}

   TTLSRule secure_ftp_client_rule
   {
      RemotePortRange 21       # This should be set to the port the FTP server is
                               # listening on
      Direction Outbound
      TTLSGroupActionRef secure_ftp_client_group
      TTLSEnvironmentActionRef secure_ftp_client_env
   }
```
Tip: You can enable additional security settings with AT-TLS, such as LDAP servers and handshake timeout values. The sample configuration is only the minimum required to allow the FTP client to use AT-TLS. You can add additional configuration statements.
Decide which cipher algorithms the client should use to encipher data transfers and control information. FTP and AT-TLS support TLS through the system SSL cryptographic services base element of z/OS. System SSL supports multiple cipher algorithms that provide both encryption and data authentication (that is, data integrity). Encryption scrambles the data so it is transferred confidentially and cannot be interpreted without a special key. Data authentication algorithms ensure that the data was not modified during transfer. Some of the supplied cipher algorithms provide only data authentication, and some provide both encryption and authentication. Be aware that the actual cipher algorithm used for the session is determined by a negotiation between the server and client. For example, if you configure an FTP client to use the Triple DES encryption, SHA authentication algorithm, but the server does not support that cipher algorithm, Triple DES encryption, SHA authentication will not be used for sessions between the client and that server.
If using TLSMECHANISM FTP, select which cipher algorithms you prefer to use by coding a CIPHERSUITE configuration statement in the FTP.DATA file for each cipher algorithm the client can use. For a list of the cipher algorithms you can specify on the CIPHERSUITE statement, see z/OS Communications Server: IP Configuration Reference.

If you specify TLSMECHANISM ATTLS, select which cipher algorithms you want to use by coding a TTLSCipherParms configuration statement to specify the cipher algorithms the client can use. For a list of the cipher algorithms you can specify with the TTLSCipherParms statement, see z/OS Communications Server: IP Configuration Reference. List the ciphers in the order of preference, your most preferred cipher algorithm first. The cipher algorithm is negotiated with the server on behalf of the client using the same order of preference as is indicated by the order of the TTLSCipherParms statement.
Restrictions:
- Only RSA key exchange is supported.
- The following algorithms are subject to export regulations and might not be available to your system:
  - Triple DES encryption, SHA authentication
  - RC4 (128-bit) encryption, SHA authentication
  - RC4 (128-bit) encryption, MD5 authentication
  - AES (128-bit and 256-bit) encryption, SHA authentication
Guideline: The default ciphers used by System SSL support a null cipher, which has no encryption or authentication. A TTLSCipherParms statement or CIPHERSUITE statement should be coded to remove the null cipher from the list of acceptable ciphers.
Decide whether the client should be required to use the TLS protocol. If the FTP server does not support TLS, you can choose to allow the client to log in without using the TLS security, or require the client to use a secure session, thus failing the login. The default is to not require the client to use TLS. This setting is customized using the SECURE_FTP configuration statement.
To have the client log in using the TLS protocol when the server supports TLS, and log in without TLS when the server does not support TLS, code the following statement in the client's FTP.DATA configuration file:
```
SECURE_FTP ALLOWED
```
This is the default.
To have the client log in using the TLS protocol, but close the server connection and prevent logging in when the server does not support TLS, code the following statement in the client's FTP.DATA configuration file:
```
SECURE_FTP REQUIRED
```
Decide the level of security for the data connection. You can choose to require enciphered data transfers, or to allow the FTP user to decide the level of security for data transfers. The default is to not encipher the data, but allow the data to be enciphered at the server's request or at the FTP user's request during the FTP session.
Note that the level of security for data connections is determined by both the SECURE_DATACONN statement in FTP.DATA and by subcommands an FTP user might issue during an FTP session.

The following subcommands can be issued by the user:

clear

Resets the security level so that data is transferred raw.

private

Resets the security level so that data is transferred enciphered. The cipher algorithm is negotiated between the server and the client using the TLS protocol negotiation.

If you want the client to transfer data raw with no cipher algorithm applied to the data, code the following statement in the client's FTP.DATA configuration file:
```
SECURE_DATACONN NEVER
```
To indicate the data can be transferred raw or enciphered, code the following statement in the client's FTP.DATA configuration file:
```
SECURE_DATACONN CLEAR
```
This is the default.
By default, data is transferred raw. However, the user can issue the private subcommand during the FTP session to change the data connection security level, so that data is transferred enciphered. The user can also issue the clear subcommand to reset the data connection security level back, so that data is transferred raw again. For TLS, if the private subcommand is issued, the cipher algorithm is negotiated between the server and the client using TLS protocols.

If you want to require that data is transferred enciphered, code the following statement in the client's FTP.DATA configuration file:
```
SECURE_DATACONN PRIVATE
```
For TLS, the cipher algorithm is negotiated between the server and the client using TLS protocols.