Transport Layer Security

Telnet Transport Layer Security setup

The TTLSPORT statement or the SECUREPORT statement in the TELNETPARMS block is required to define a port as a secure port that is using AT-TLS or Telnet profile statements to configure the secure connections.

The CONNTYPE statement is an optional statement on secure ports that provides more control over how connections initiate the TLS handshake, whether or not the connection is secure, and whether the connection is available for use. Valid CONNTYPE statement options are as follows:

• SECURE

  Indicates that the TLS handshake is used to start the connection. If the client does not start the handshake within the time specified by the handshake timeout time, an attempt is made to perform a negotiated TLS handshake (as defined by the expired IETF TLS-based Telnet security draft). If the client rejects TLS, the connection is closed.

• NEGTSECURE

  Indicates that the client supports the expired IETF TLS-based Telnet security draft. A Telnet negotiation with the client determines whether the client is willing to enter into a secure connection. If the client agrees, a TLS handshake is started and secure protocols are used for all subsequent communication. If the client rejects TLS, the connection is closed. You should consider using this option only if you know that the Telnet secure clients connecting into the port are all using the protocol defined by the expired TLS-based Telnet security draft. With this option, the TLS handshake is not attempted until a positive response to the Telnet DO_StartTLS IAC is received. This avoids the timeout delay that can occur when a TLS handshake is immediately started (as occurs with the CONNTYPE SECURE option), but the client is expecting the protocol used by the expired TLS-based Telnet security draft. Use the SECURE option instead of the NEGTSECURE option in case some clients in your network do not support the expired TLS-based Telnet security draft.

• BASIC

  Indicates that a basic connection is established.

• ANY

  Indicates that the connection can be either secure or basic. Telnet first tries a standard TLS handshake. If the handshake times out, a negotiated TLS connection (see the CONNTYPE NEGTSECURE option description) is attempted:

  • If the client is willing to enter into a secure connection, secure protocols are used for all subsequent communication.
  • If the client is not willing to enter into a secure connection, a basic connection is established.
• NONE

  Indicates that no connection is allowed and the connection will be closed. If this option is specified in the TELNETPARMS block, a PARMSMAP statement must cover every allowable connection, and the related PARMSGROUP statement must specify the connection type on the CONNTYPE statement.

If the CONNTYPE statement is not specified, by default, secure ports are CONNTYPE SECURE and basic ports are CONNTYPE BASIC.

Using one port for both basic and secure connections

You can use the CONNTYPE statement to modify connection types on a single port. Allowing a port to support both basic and secure connections assumes that either of the following statements are true:

• The installation allows the client to determine the connection type.
• A subset of the connections that should use a particular connection security type can be identified by Client Identifier.

In the first case, specify CONNTYPE ANY. If the port was defined as a secure port but the client wants a basic connection, there is a slight delay before connection negotiation begins. This is because when CONNTYPE ANY is coded, Telnet first attempts a TLS handshake to ensure that the client is not requesting TLS support. It is only after the handshake times out and negotiated security is rejected that the basic connection negotiation begins.

In the second case, the TELNETPARMS block should specify the default connection security type (see the CONNTYPE statement). For connections with different connection security requirements:

• Identify the clients by Client Identifier.
• Create a group using the PARMSGROUP statement with the alternate CONNTYPE definitions.
• Map the group created with the PARMSGROUP statement to the clients using the PARMSMAP statement.

Configuring Telnet security using AT-TLS

The TTLSPORT statement in the TELNETPARMS block indicates that the port uses AT-TLS to manage System SSL. All TTLSPORT ports must be defined by specifying a TELNETPARMS block for each port.

Other than the CONNTYPE statement, all security configuration is done in AT-TLS policy. For details about AT-TLS setup, see Application Transparent Transport Layer Security data protection. For Policy Agent setup and AT-TLS policy statements, see z/OS Communications Server: IP Configuration Reference. A sample list of tasks to perform for AT-TLS policy includes:

1. Be sure that the TCP/IP stack profile includes the TCPCONFIG statement with the TTLS parameter.
2. Permit Policy Agent and any other required administrative application to the RACF resource EZB.INITSTACK.sysname.tcpname in the SERVAUTH class.
3. Define the pagent environment file on the STDENV DD statement in Policy Agent JCL. For example:

   //STDENV   DD PATH='/etc/pagent/pagent.env',PATHOPTS=(ORDONLY)

4. In the pagent environment file, point to a configuration file. For example:

   PAGENT_CONFIG_FILE=//'SYS1.TCPPARMS(PAGENT)'

5. In the configuration file, set up policy files for each TCP/IP stack image. For example:

   TcpImage TCP1 /etc/pagent/TCP1.policy FLUSH
   TcpImage TCP2 /etc/pagent/TCP2.policy FLUSH

6. In the TcpImage file, point to the TTLS configuration file. For example:

   TTLSConfig /etc/pagent/pagttls1.ttls

7. In the TTLS configuration file, code the TTLSRule, TTLSGroupAction, TTLSEnvironment, and TTLSConnectionAction statements. Be sure to set the ApplicationControlled parameter to the value On in the TTLSEnvironmentAdvancedParms statement. For example:

   TTLSRule        tn_serv1             
   {                                    
     LocalPortRange 23                  
     Direction      Inbound              
     Jobname TCP1                      
     TTLSGroupActionRef tn_grp_act       
     TTLSEnvironmentActionRef tn_env_act
   }
   
   TTLSGroupAction tn_grp_act  
   {                           
    TTLSEnabled On             
    Trace  7                 
    GroupUserInstance  1
   }     
   
   TTLSEnvironmentAction tn_env_act        
   {                                       
     HandshakeRole Server                  
     TTLSKeyringParms          
     {                         
        Keyring TNsafkeyring   
     }                         
     TTLSEnvironmentAdvancedParms         
     {                                    
      ApplicationControlled On             
     } 
    EnvironmentUserInstance  1   
   }

8. Verify that the policy is correctly entered by using the z/OS® UNIX pasearch command to query information from the z/OS UNIX Policy Agent. Issue the pasearch -t command from the z/OS UNIX System Services shell. If you have multiple TCP/IP stacks that are active, issue the pasearch -t -p procname command to query a specific TCP/IP stack. The pasearch command is a Policy API (PAPI) application. If you have never run a PAPI application, you might receive a message indicating that the papi.dll file was not found. For more information about PAPI and running PAPI applications, see z/OS Communications Server: IP Programmer's Guide and Reference.

Converting Telnet profile statements to equivalent AT-TLS policy statements

If you are currently using the SECUREPORT statement in your Telnet profile, the following table describes how to convert Telnet profile statements to equivalent AT-TLS policy statements.

Configuring Telnet security using Telnet profile statements

System SSL environment initialization based on the Telnet profile configuration occurs when the first SECUREPORT port is activated; initialization does not occur again unless all SECUREPORT ports are stopped (V TCPIP,tnproc,T,STOP,PORT=SECURE). Whether or not hardware encryption is used is based on its availability at the time of Telnet initialization. For ICSF to be used by Telnet, ICSF must be available to System SSL. A crypto assist status message is issued to sysout when the first Telnet secure port is activated. For more information about hardware encryption, see TLS/SSL security.

To implement secure connections, Telnet must have APF-authorized access to the System SSL DLLs. The System SSL DLLs are located in SYS1.SIEALNKE by default. System SSL uses the C runtime library (SCEERUN) and the C/C++ standard library, which must also be accessible to Telnet. To access these libraries, either add them to the linklist or specify them in the Telnet procedure's STEPLIB. If accessed through the linklist, the linklist must be authorized (LNKAUTH=LNKLST specified in the IEASYSxx parmlib member) or the libraries must be explicitly APF authorized. If accessed through a STEPLIB, the libraries must be APF authorized and DISP=SHR must be specified. The Telnet profile must also be updated. An overview of the SSL-related profile parameters follows. For a detailed description of the parameters, see z/OS Communications Server: IP Configuration Reference.

Two statements are required to define a SECUREPORT port:

• SECUREPORT

  The SECUREPORT port designation statement in the TELNETPARMS block indicates that the port uses Telnet profile configuration to manage System SSL. All SECUREPORT ports must be defined by specifying a TELNETPARMS block for each port.

• KEYRING

  A server certificate is required for the server authentication process defined by the SSL protocol. This certificate is stored in a key ring. The key ring type and location is specified in the KEYRING statement. Only one key ring can be used by Telnet.

The key ring can be defined in the TELNETGLOBALS or TELNETPARMS block. Using the TELNETGLOBALS block is the preferred definition method because it ensures that the same key ring has been defined for all SECUREPORT ports. If specified in the TELNETPARMS block, the same key ring type and file must be specified for each SECUREPORT port. The first key ring file name read is considered the correct key ring file name. The TELNETGLOBALS key ring is read first, and then the TELNETPARMS key rings are read in reverse order. Any key ring that does not match the first is rejected and the port update fails. You can verify that your port is secure by issuing a D TCPIP,tnproc,T,PROFILE command. The first column under the security heading indicates the port type. You see an S for a SECUREPORT port, a T for a TTLSPORT port, or a B for a basic port. Near the bottom of the display, you see the key ring name that Telnet is using.

The following steps are required to enable TLS support for Telnet, with server authentication:

1. Generate the Telnet private key and server certificate.
2. Configure Telnet to include one or more SECUREPORT ports; in the TELNETGLOBALS block or the TELNETPARMS block, specify the name of the key ring that you created in the previous step. For example:
   • KEYRING HFS /usr/ssl/server.kdb

     In this example, two files, server.kdb and server.sth, were created using the gskkyman utility. The server's certificate is contained in the server.kdb file and designated as the default certificate.

     The key database and the password stash file must be in the same directory.

   • KEYRING SAF serverkeyring

     In this example, RACF is used to manage keys and certificates. The server certificate is connected to a key ring called SERVERKEYRING and designated as the default certificate.

3. Restart Telnet or issue the VARY TCPIP,tnproc,OBEYFILE command with the updated configuration files.

Optional security statements

You can specify optional security statements only for SECUREPORT ports in the TELNETGLOBALS, TELNETPARMS, or PARMSGROUP blocks. The statements specified in the PARMSGROUP block apply to only the clients mapped to the PARMSGROUP block by the PARMSMAP statement, and override the statements specified in the TELNETPARMS or TELNETGLOBALS block. The statements specified in the TELNETPARMS block apply to any connection for that port, if not overridden by a PARMSGROUP statement. The statements specified in the TELNETGLOBALS block apply to any connection for any port, if not overridden by a TELNETPARMS or PARMSGROUP statement.

The CONNTYPE statement is described in the setup section.

The ENCRYPTION statement is used to limit the encryption algorithms to only those included in the statement. If this statement is not specified, all encryption algorithms that can be specified are used by Telnet. For the encryption ciphers that can be specified and for the default order used by Telnet if the ENCRYPTION statement is not used, see z/OS Communications Server: IP Configuration Reference. Some of the reasons for using the ENCRYPTION statement are:

• The applications supported on this port require a high level of security and the installation wants all data encrypted using a particular encryption cipher.
• Certain connections are local and the installation does not require encryption for local clients. NULL encryption can be specified for this subset of connections.

The SSLV2 statement enables the use of the SSLv2 protocol. The default value is NOSSLV2, which prohibits the use of the SSLv2 protocol. The SSLv2 protocol might be necessary if SSLv3, TLSv1.0, or TLSv1.1 is not supported by the client.

The SSLV3 statement enables the use of the SSLv3 protocol. The default value is NOSSLV3, which prohibits the use of the SSLv3 protocol. The SSLv3 protocol might be necessary if TLSv1.0 or TLSv1.1 is not supported by the client.

The CLIENTAUTH statement indicates that the client must send a client certificate to the server. If this statement is not specified, a client certificate is not requested during the SSL handshake, and no certificate-based client authentication is performed. The level of validation performed depends on the option specified.

Valid CLIENTAUTH options are:

• SSLCERT (Level 1)

  To pass authentication, the Certificate Authority (CA) that signed the client certificate must be considered trusted by the server (that is, a certificate for the CA that issued the client certificate is listed as trusted in the server's key ring).

• SAFCERT (Level 2 and 3)

  The level 1 checking provided by SSLCERT is performed, and level 2 checking is performed to verify that the certificate has been registered with RACF (or another SAF-compliant security product that supports certificate registration). Additionally, if the RACF SERVAUTH class is active and a RACF resource has been defined for the port, level 3 client authentication is in effect and the connection is allowed only if the user ID associated with the client certificate has READ access to the RACF resource.

• NONE

  No client certificate is requested.

The CRLLDAPSERVER statement is specified in the TELNETGLOBALS block, and defines the name or IP address and port of the certificate revocation list (CRL) LDAP server. The CRL LDAP server is used only if client certificates are received (CLIENTAUTH is specified). If CLIENTAUTH and the CRLLDAPSERVER statement have been specified, the certificate revocation list is checked during client authentication. If the client's certificate is found on the certificate revocation list, the connection is closed. Up to five CRL LDAP servers can be defined to Telnet.

You cannot change the key ring (name, type, or contents) or the CRL LDAP server (name or location) using the VARY TCPIP,tnproc,OBEYFILE command while SECUREPORT ports are active. To change the key ring or the CRL LDAP server, first stop all SECUREPORT ports (V TCPIP,tnproc,T,STOP,PORT=S). Then issue the VARY TCPIP,tnproc,OBEYFILE command to restart the SECUREPORT ports with a new key ring or CRL LDAP server. If the CRL LDAP server is stopped or connectivity is lost, System SSL might not recognize a subsequent reconnection. This situation must be handled like the CRL LDAP server change.

Telnet profile example

This example defines three ports with the following characteristics:

• Port 23 allows only basic connections.
• Ports 992 is enabled for secure connections defined by Telnet profile statements.
• Port 1023 is enabled for secure connections defined by AT-TLS policy.
• Port 992 allows only secure connections. No client authentication is requested.
• Port 1023 allows both basic and secure connections. The installation wants the following characteristics for port 1023:
  • The system administrator is at IP address 10.1.3.3 and wants the capability to choose to connect with secure or basic connections.
  • Buildings A and B are local and do not need connection security. The clients in these buildings have identifiable subnetworks. The installation wants these clients to use basic connections to avoid the encryption overhead.
  • Connection security (SSLCERT or Required) is used on all other connections.
  • All secure connections require client authentication and use the DES or triple DES encryption algorithms.

Figure 1. Port 1023 connection characteristics

TCP/IP configuration statements:

⋮
 TCPCONFIG TTLS
⋮

Telnet profile statements:

TELNETPARMS            ; basic port does not support secure connections 
 Port 23
ENDTELNETPARMS

TELNETPARMS                        ; port that allows only secure connections
 SECUREPORT 992                    ; no client authentication requested
 KEYRING hfs /usr/keyring/tcp1.kdb ; keyring used by all SECUREPORTs
ENDTELNETPARMS                     ; any supported encryption algorithm

TELNETPARMS            ; port that allows secure and BASIC connections. 
 TTLSPORT 1023         ; note: BEGINVTAM block has PARMSGROUP that may override CONNTYPE
 CONNTYPE SECURE       ; SECURE is default 
ENDTELNETPARMS         


BEGINVTAM
 Port 1023
 ...                    ; Mapping statements
 IPGROUP LocalIP 
   255.255.255.0:10.1.1.0 
   255.255.255.0:10.1.2.0 
 ENDIPGROUP 

 PARMSGROUP BasicPG     ; override default ConnType
   CONNTYPE BASIC       ; support basic connections mapped to this group
 ENDPARMSGROUP 
 PARMSGROUP AdminPG
   CONNTYPE ANY         ; connections mapped to this group allow any type of connection
 ENDPARMSGROUP

 PARMSMAP AdminPG 10.1.3.3 ; this ip address can use secure or basic connections 
 PARMSMAP BasicPG localIP  ; hosts defined in IPGROUP localIP, 
                           ; will use basic connections as defined in PARMSGROUP BasicPG
ENDVTAM


BEGINVTAM
 Port 992 23
 ...                       ;Mapping statements
                           ;no PARMSGROUP defined for these ports
                           ;TELNETPARMS definitions used for all connections
ENDVTAM

AT-TLS policy statements:

TTLSRule        tn_serv             
{                                    
  LocalPortRange 1023                  
  Direction      Inbound              
  Jobname TCP1                      
  TTLSGroupActionRef tn_grp_act       
  TTLSEnvironmentActionRef tn_env_act
}

TTLSGroupAction tn_grp_act  
{                           
 TTLSEnabled On             
 Trace  7                 
 GroupUserInstance  1
}     

TTLSEnvironmentAction tn_env_act        
{                                       
  HandshakeRole ServerWithClientAuth                  
  TTLSKeyringParms          
  {                         
     Keyring TNsafkeyring   
  }                         
  TTLSEnvironmentAdvancedParms         
  {                                    
   ClientAuthType Required  
   ApplicationControlled On           
  }
  EnvironmentUserInstance  1   
}