Transport Layer Security

Note: References to RACF®® apply to any SAF-compliant security product that contains the required support.

The TN3270E Telnet server (Telnet) provides the ability to secure Telnet connections with Transport Layer Security (TLS) or the Secure Sockets Layer (SSL) protocol. Telnet can be set up to use Application Transparent Transport Layer Security (AT-TLS) in TCP/IP, or a subset of the functions available in AT-TLS can be configured in the Telnet profile. A port using AT-TLS security configuration is referred to as a TTLSPORT port, and a port using Telnet profile security configuration is referred to as a SECUREPORT port. A secure port is either a TTLSPORT port or a SECUREPORT port. A basic port is one that does not use the TLS protocol. Connections are either secure or basic. The flows between Telnet and VTAM® are unchanged.

Restriction: SECUREPORT only supports the TLSv1.0, SSLv3, and SSLv2 protocols. To use the TLSv1.1 protocol (or above), the TTLSPORT with AT-TLS policies must be configured.

The expired Internet Engineering Task Force (IETF) TLS-based Telnet security draft is supported in Telnet. This draft allows a Telnet negotiation to determine whether the client wants or supports TLS protocol prior to beginning the secure handshake. The default action that Telnet takes for a secure port is to first attempt a TLS handshake. If the client does not start the handshake within the specified handshake timeout time, an attempt is made to negotiate TLS as defined by the expired TLS-based Telnet security draft. If the client responds that it wants a secure connection, the handshake is started; if the client rejects the TLS negotiation request, the connection is closed. In this way, installations can support both types of secure clients without knowing which protocol the client is using. The default action can be changed by specifying the CONNTYPE statement described later in this topic. You can also use the CONNTYPE statement to support secure and basic connections on the same port.

Telnet server authentication and client authentication are described in TLS/SSL security. The Telnet server supports level 1, level 2 and level 3 client authentication. Client authentication is done with the CLIENTAUTH parameter. Level 2 and level 3 client authentication use RACF services to translate the client certificate to an associated user ID. That user ID can also be used as a client identifier.

TTLSPORT uses AT-TLS, which supports many System SSL functions that are not supported by the Telnet profile configuration. For example, the following functions are supported by AT-TLS and not by Telnet profile configuration:

  • Dynamic refresh of a key ring
  • Support new or multiple key rings
  • Specify the label of the certificate to be used for authentication, instead of using the default certificate
  • Support SSL Session Key Refresh
  • Support SSL Session Reuse
  • Support SSL Sysplex Session ID Caching
  • Trace decrypted SSL data for Telnet in a data trace
  • More granular error messages in syslog for easier debugging

When using SECUREPORT ports, the Telnet profile security configuration supports the following subset of System SSL functions:

  • Key ring specification using the KEYRING statement
  • Cipher specification using the ENCRYPTION statement
  • Client authentication level using the CLIENTAUTH statement
  • CRL LDAP server specification using the CRLLDAPSERVER statement
  • Control SSLv2 protocol usage with the SSLV2 or NOSSLV2 statement
  • Control SSLv3 protocol usage with the SSLV3 or NOSSLV3 statement
  • Set the handshake timeout using the SSLTIMEOUT statement

TTLSPORT ports and SECUREPORT ports can coexist in the same Telnet server.

AT-TLS has one limitation when compared to Telnet profile configuration. AT-TLS policy does not support mapping security parameters to connections based on client hostname. You can do this with Telnet profile configuration by coding security parameter statements in a PARMSGROUP statement and using the PARMSMAP statement to map the group to a hostname or a hostname group. If you currently have this configuration, you must continue to use Telnet profile configuration.

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.

Table 1. Converting Telnet profile statements to AT-TLS policy statements
Telnet statement AT-TLS equivalent statement AT-TLS policy statement
CLIENTAUTH NONE HandshakeRole Server TTLSConnectionAction or TTLSEnvironmentAction
CLIENTAUTH SSLCERT HandshakeRole ServerWithClientAuth and ClientAuthType Required TTLSConnectionAction or TTLSEnvironmentAction / TTLSEnvironmentAdvancedParms within TTLSEnvironmentAction
CLIENTAUTH SAFCERT HandshakeRole ServerWithClientAuth and ClientAuthType SAFCHECK TTLSConnectionAction or TTLSEnvironmentAction / TTLSEnvironmentAdvancedParms within TTLSEnvironmentAction
CRLLDAPSERVER GSK_LDAP_Server and GSK_LDAP_Server_Port TTLSGskLdapParms within TTLSEnvironmentAction
ENCRYPTION TTLSCipherParms TTLSConnectionAction or TTLSEnvironmentAction
KEYRING Keyring TTLSKeyRingParms within TTLSEnvironmentAction
SSLV2 SSLv2 TTLSEnvironmentAdvancedParms within TTLSEnvironmentAction or TTLSConnectionAdvancedParms within TTLSConnectionAction
SSLTIMEOUT HandshakeTimeout TTLSEnvironmentAdvancedParms within TTLSEnvironmentAction or TTLSConnectionAdvancedParms within TTLSConnectionAction
Tip: There are many variations possible with the Telnet profile statement CLIENTAUTH. In AT-TLS, whether or not client authentication is done is controlled by the HandshakeRole parameter on either the TTLSEnvironmentAction or TTLSConnectionAction statements. If the connection needs client authentication, the level of authentication is controlled with the ClientAuthType parameter on the TTLSEnvironmentAdvancedParms statement.
  • If you have both CLIENTAUTH SSLCERT and CLIENTAUTH SAFCERT in different ParmsGroup statements in your Telnet configuration, you need two TTLSEnvironmentAction statements; one TTLSEnvironmentAction statement for ClientAuthType Required and one TTLSEnvironmentAction statement for ClientAuthType SAFCheck. Two TTLSRule statements, each referencing a different TTLSEnvironmentAction statement in AT-TLS, replace the two PARMSMAP statements in the Telnet profile.
  • If you have a mixture of CLIENTAUTH NONE and CLIENTAUTH SAFCERT, you need a TTLSEnvironmentAction statement with HandshakeRole ServerWithClientAuth, and a TTLSConnectionAction statement with HandshakeRole Server. Two TTLSRule statements in AT-TLS (one with the TTLSConnectionAction statement and one without) replace the two PARMSMAP statements in the Telnet profile. You could instead create a second TTLSEnvironmentAction statement with HandshakeRole Server, but many more resources are associated with a TTLSEnvironmentAction statement compared to a TTLSConnectionAction statement.

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
Shows connection characteristics of Port 1023, which is one of three ports defined in the Telnet profile example
Note: Definitions that are applicable to TLS connection security are the only definitions shown; additional parameters might be needed. Assume that all connections go through TCP/IP stack with job name TCP1.

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   
}