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 Start of changeTelnet connections with Transport Layer Security (TLS) or the Secure Sockets Layer(SSL) protocol using Application TransparentEnd of change Transport Layer Security (AT-TLS) in TCP/IP. A port using AT-TLS security configuration is referred to as a TTLSPORT 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.

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 Start of changeClientAuthType parameter of the TTLSEnvironmentAdvancedParms statement in AT-TLS policy.End of change 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.

Telnet Transport Layer Security setup

The TTLSPORT statement in the TELNETPARMS block is required to define a port as a secure port that is using AT-TLS to Start of changesecure the connectionsEnd of change.

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 Start of changeTN3270E/End of changeTNsafkeyring   
      }                         
      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.

Telnet profile example

This example defines three ports with the following characteristics:

  • Port 23 allows only basic connections.
  • Start of changePorts 992 and 1023 are enabled for secure connections defined by AT-TLS policy.End of change
  • 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 Start of changeidentifiable subnetworks (10.1.1.0/24 and 10.1.2.0/24, respectively)End of change. The installation wants these clients to use basic connections to avoid the encryption overhead.
    • Start of changeTLS security with client authentication is required for all other connections.End of change
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:

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

TELNETPARMS             ; port that allows only secure connections
 TTLSPORT 992           ; no client authentication requested
ENDTELNETPARMS

TELNETPARMS             ; port that allows secure and BASIC connections.
 TTLSPORT 1023          ; note: BEGINVTAM block has PARMSGROUP that may override
 CONNTYPE SECURE        ; this CONNTYPE setting. If not, SECURE will be default.
ENDTELNETPARMS

BEGINVTAM
 Port 1023
 ...                    ; Mapping statements
 IPGROUP LocalIP        ; Subnets for buildings A and B
   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 if mapped to this group
 ENDPARMSGROUP
 PARMSGROUP AdminPG     ; override default ConnType
   CONNTYPE ANY         ; allow any type of connections if mapped to this group
 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
End of change

AT-TLS policy statements:

Start of change
TTLSRule tn992_serv
{
  LocalPortRange 992
  Direction Inbound
  Jobname TN3270A
  TTLSGroupActionRef tn_grp_act
  TTLSEnvironmentActionRef tn992_env_act
}

TTLSRule tn1023_serv
{
  LocalPortRange 1023
  Direction Inbound
  Jobname TN3270A
  TTLSGroupActionRef tn_grp_act
  TTLSEnvironmentActionRef tn1023_env_act
}

TTLSGroupAction tn_grp_act
{
  TTLSEnabled On
  Trace 7
  GroupUserInstance 1
}

TTLSEnvironmentAction tn992_env_act
{
  Start of changeHandshakeRole ServerEnd of change
  TTLSKeyringParmsRef tn_keyring
  TTLSEnvironmentAdvancedParms
  {
    ApplicationControlled On
  }
  EnvironmentUserInstance 1
}

TTLSEnvironmentAction tn1023_env_act
{
  Start of changeHandshakeRole ServerWithClientAuthEnd of change
  TTLSKeyringParmsRef tn_keyring
  TTLSEnvironmentAdvancedParms
  {
    ClientAuthType Required
    ApplicationControlled On
  }
  EnvironmentUserInstance 1
}

TTLSKeyringParms tn_keyring
{
  Keyring TN3270E/TNsafkeyring
}
End of change