Secure X3270 to z/OS on ADCD

I was asked if it was possible to connect to an ADCD system using X3270 and certificates, after quite a bit of work, the answer is yes – but it may not be easy.

The process is documented in the September version of IBM ISV zPDT Guide and Reference – which works, but the SecurePort is being removed in z/OS 2.5!

How to connect using x3270.

Using a “dialed in” local terminal into an ADCD system.

You can connect to z/OS using 3270 like terminals via a 3274 type controller and use applications like TSO. This is not a TCPIP connection, so you cannot use TLS to protect the session. These terminals are created using a Linux command like

x3270 -model 5 colin@localhost:3270 &

Where the :3270 matches the zPDT configuration statement 3270port 3270.

The colin@, known as the LUName, is put in the title of the window (so I could hot key to it, by setting key Ctrl+3 to wmctrl -a colin@).

Using X3270 and TCPIP over an insecure connection

You can connect over TCPIP into the TN3270 server using a command like

x3270 -model 5 10.1.1.2:23

This uses port 23, the standard telnet port.

You can specify an LU name – but you need to look at your TN3270 configuration to see what values have been configured. If you do not know what you are doing … it is safer to omit it.

SECUREPORT will be removed in z/OS 2.5

This was the “secure” way of providing a secure connection, before AT-TLS was developed. It is documented in Appendix E of IBM ISV zPDT Guide and Reference

The z/OS documentation says SECUREPORT will be removed

Keyword no longer supported for the TN3270E Telnet server: Removal of native
TLS/SSL support from TN3270E Telnet Server
, FTP Server, and DCAS.

How to configure and use TN3270

Ive written about it here.

My TN3270 configuration is member TNPO2023 is

TelnetParms         ; ATTLS defined secure port 
 TTLSPort 2023      ; 
 DEBUG CONN DETAIL CTRACE 
 DEBUG CONN trace  CTRACE 
 ConnType Secure    ; Client chooses secure or nonsecure connection. 
EndTelnetParms 
                                                                           
BeginVTAM 
 Port 2023 
 DEFAULTLUS 
   TLS00001..TLS00030 
 ENDDEFAULTLUS 
 ALLOWAPPL TSO* DISCONNECTABLE ; Allow all users access to TSO 
             ; applications. 
             ; TSO is multiple applications all beginning with TSO, 
             ; so use the * to get them all.  
 ALLOWAPPL *      ; Allow all applications that have not been 
                  ; previously specified to be accessed.             
 USSTCP USSN 
EndVTAM 

Using AT-TLS

I eventually got a secure connection using AT-TLS. Many parameters need to be correct for the TLS Handshake to work. Some combinations should work – but did not.

I’ve blogged about setting up and using AT-TLS.

The short list of requirements:

  • The z/OS certificate needs CN(‘10.1.1.2’) where 10.1.1.2 is what is used by the X3270 client. It checks the value in the certificate with the value used in the connection. ALTNAME(IP(10.1.1.2)) did not work for me. If there is a mismatch you get x3270 message “hostname mismatch(62). When I used a host name of zos as in “x3270…. zos” – and the z/OS certificate has CN(‘zos’)…. it also worked.
  • You can use RSA, and NISTECC, certificates on z/OS.
    • TLS 1.2 or TLS 1.3 , RSA size 2048 or larger
    • TLS 1.2 or TLS 1.3, NISTECC size 521
    • BPECC not supported.
  • The CA was exported, sent down to Linux and used in the x3270 command (and also the openssl s_client command). For example -cafile ./doczosca.pem .
  • x3270 does not use a certificate on Linux – the doc implies it does, but nothing gets sent to the server.
  • In the AT-TLS configuration below,
    • the three cipher spec represent TLS 1.3, NISTECC and RSA.
    • ApplicationControlled On is required
    • HandshakeRole Server is required

Below is the AT-TLS configuration for my telnet (TN…) configuration. It should work with the keyring created in Appendix E. Secure x3270 connection in IBM ISV zPDT Guide and Reference September 2022 (SG24-8205-06). See JCL. The file below is on GIT.

TTLSRule                      TN 
{ 
  LocalPortRange              2023 
  Jobname                     TN3270 
  Direction                   INBOUND 
  TTLSConnectionActionRef     TNCA   
  TTLSGroupActionRef          TNGA 
  TTLSEnvironmentActionRef    TNEA 

} 
TTLSConnectionAction              TNCA 
{ 
  TTLSCipherParmsRef              TLS13TLS12 
  TTLSSignatureParmsRef           TNESigParms 
  TTLSConnectionAdvancedParmsRef  TNCOonAdvParms 
  CtraceClearText                 Off 
  Trace                           50 
} 
TTLSConnectionAdvancedParms       TNCOonAdvParms 
{ 
 #ServerCertificateLabel  NISTECC521 
 #ServerCertificateLabel  RSA2048 
 #ccp this was added 
  ApplicationControlled         On 
  SSLv3          OFF 
  TLSv1          OFF 
  TLSv1.1        OFF 
  TLSv1.2        ON 
  TLSv1.3        OFF 
  SecondaryMap   OFF 
  HandshakeTimeout 3 
} 

TTLSGroupAction      TNGA 
{ 
  TTLSEnabled        ON 
  trace              50 
} 
TTLSKeyringParms    TNKEYRING 
{ 
  Keyring           START1/TN3270 
} 

TTLSEnvironmentAction      TNEA 
{ 
  HandshakeRole            Server 
  TTLSKeyringParms 
  { 
#    Keyring                START1/TN3270 
# Use the keyring from the ZPDT documentation chapter E
     Keyring                START1/TN3270TLSring 
  } 
  TTLSSignatureParmsRef    TNESigParms 
} 
TTLSSignatureParms         TNESigParms 
{ 
   CLientECurves Any 
} 
TTLSCipherParms             TLS13TLS12 
{ 
#TLS 1.3 
 V3CipherSuites      TLS_CHACHA20_POLY1305_SHA256 
#V3CipherSuites      TLS_AES_256_GCM_SHA384 
#V3CipherSuites      TLS_AES_128_GCM_SHA256 
#TLS 1.2 
# NSTECC 
 V3CipherSuites      TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 
#RSA 
 V3CipherSuites      TLS_RSA_WITH_AES_256_CBC_SHA256 
} 

I did many system SSL traces to get it working.

Some lessons learned

  • Although you can specify a certificate and private key on the Linux x3270 command, it does not use them. If you specify them, the certificate is not passed up to to z/OS.
  • The AT-TLS configuration needs TTLSEnvironmentAction -> HandshakeRole SERVER. (Despite what the documentation says). If you specify HandshakeRole ServerWithClientAuth, then z/OS expects the client to send a certificate as part of the handshake – and as x3270 does not sent a certificate – the handshake fails.
  • x3270 checks the host name. In the z/OS certificate the DN needs a CN matching the connection name. I connected to 10.1.1.2 – I needed SUBJECTSDN(CN(‘10.1.1.2‘) … . Without this you get hostname mismatch (62).
    • You should be able to specify RACDCERT …. ALTNAME(IP(10.1.1.2)), as an alternate name, but x3270 does not recognise it.
  • x3270 supports TLS 1.3 – if you have TLS 1.3 cipher specs configured in AT-TLS, and specify TLSv1.3 ON
  • X3270 supports TLS 1.2 – if you have TLS 1.2 cipher specs configured in AT-TLS, and specify TLSv1.2 ON and TLSv1.3 OFF.
  • x3270 sends up a list of cipher suites it will accept. The first three are TLS 1.3 (TLS_AES_256_GCM_SHA384 (0x1302) ,TLS_CHACHA20_POLY1305_SHA256 (0x1303),TLS_AES_128_GCM_SHA256 (0x1301).
  • When configuring TN3270 use V3CipherSuites not V3CipherSuites4char. V3CipherSuites takes 2 character strings and long TLS_… strings. V3CipherSuites4char only take 4 character strings, and not TLS_… strings.
  • If you change the PAGENT configuration you need F PAGNET,UPDATE to pick up the changes.
  • If you make a change to the PAGENT configuration, it does not always report problems. You should use Unix command commands like pagent -t -f TN 1>a … oedit a to display the TTLS configuration for rule TN, and edit the file to check.
  • If you change a keyring, you need F CPAGENT,REFRESH to pick up the change.
  • When you start PAGENT use the -l /var/log/pagent.log -d1 options (or similar). Review the /var/log/pagent.log file and check for “WARNING” and “ERR”
  • The PAGENT configuration can have the same parameter specified at the environment level and at the connection level. The pasearch -t -f TN command displays both sets of data … you have to be careful you are checking the right set of data.

Is the port active?

Check the port is being listened to

tso netstat conn ( port 2023

gave

EZZ2585I User Id  Conn     Local Socket           Foreign Socket         State
EZZ2586I -------  ----     ------------           --------------         -----
EZZ2587I TN3270   0000000B 0.0.0.0..2023          0.0.0.0..0             Listen

Showing the port is in Listen state from jobname TN3270 (which has userid TCPIP!)

Update to show it not working!

I was asked a question about AT-TLS, and it not working. I thought it would be useful to include some Wireshark output to help people to see what is happening.

I used x3270 10.1.1.2@3023 and it reported “SSL: Host certificate verification failed: self signed certificate in certificate chain”.

In the examples below there are three records of interest

  • Client Hello – this is the first step in the handshake. If you do not have this – your client is not sending a request
  • Server Hello – the back-end has processed the Client-Hello – and, in the example below, sends down a certificate
  • Alert (from the client). The client cannot validate the certificate because it does not have the CA for the certificate.

The Wireshark trace was

The important line is the “Client Hello” in blue. This is the start of the TLS handshake. In my case the length is 512 bytes. I would expect any TLS handshake to be a couple of hundred bytes long. If you do not get a “Client Hello”, your client is not set up for TLS/SSL.

The “Server Hello” line is where the server is responding (with a certificate).

There is an error “Alert (Level: Fatal Description: Unknown CA”

Using AT-TLS and PAGENT on z/OS (with ADCD)

I wrote this post based on getting X3270 to work with TLS to z/OS. It covers some of the lessons I learned in doing so.

Policy Server

The Communications Server’s policy server allows you to define policies for: (the list below is mainly taken from the IBM documentation)

  • QoS: The overall Quality of Service provided to applications or users, in terms of elements such as throughput and delay. It might be critical to provide Business Application traffic better service during peak hours than that of FTP or web traffic.
  • IDS: Intrusion Detection Services provides the following support: scan detection and reporting, attack detection, reporting, and prevention, traffic regulation for TCP connections and UDP receive queues. You can use IDS policies to specify event conditions and the actions to take for particular events
  • IPSec: IP Security policy can be used for the following protection:
    • Protect a secure host on an internal network from unwanted network traffic
    • Provide protection for traffic between partner companies over connected networks
    • Allow secure sending of data over the Internet by providing IPSec virtual private network (VPN) support
  • Routing: Policy conditions consist of a variety of selection criteria that act as filters for policy-based routing (Routing) rules. Traffic can be filtered based on source addresses, destination addresses, source port range, destination port range, protocol, job name, security zone, and security label.
  • AT-TLS: (Application Transparent-Transport Layer Security) Provides TLS support at the TCPIP level (below the application). Using AT-TLS means applications do not need to be changed to support TLS.

The PAGENT (Policy Agent) started task runs the policy server. It can use local configuration files, or data in LDAP.

Using AT-TLS

It was a struggle to get a secure connection using AT-TLS and x3270. Many parameters need to be correct for the TLS Handshake to work. Some combinations should work – but did not, the documentation is not 100% correct. When I knew what the correct parameters were, the configuration was pretty easy! The configuration technique looks as if it was designed for a baby system. It is not easy to follow good housekeeping, and change management practices, which made the overall experience harder than I expected.

X3270 requirements

x3270 is a 3270 emulator. It can use TLS to provide a secure connection to z/OS. Although you can specify a certificate for X3270 to use – x3270 does not used the client certificate.

At a high level, the TLS flow between x3270 and AT-TLS is:

  • X3270 client sends a “client-hello” request to the server. This includes what levels of TLS are supported (TLS 1.2, TLS 1.3), and the cipher specs it supports (what encryption type,what checksum algorithm etc)
  • The server (Pagent) matches the information sent in the “Client-hello” with its configuration. For example, select a certificate which matches the encryption type, and finds a common cipher spec.
  • If there is an acceptable certificate, and cipher spec, the selected certificate and selected cipher spec are sent down to the client (“server hello”).
  • The x3270 client checks that the certificate is acceptable – the CN in the certificate matches the address of the server. (CN(10.1.1.2) matches the IP address 10.1.1.2).
  • If client authentication is requested, then the client sends its certificate to the server. This is not supported by X3270, and the server has to be configured with HandshakeRole Server.

X3270 initially sends that it can support TLS 1.2 and TLS 1.3, and a variety of cipher specs.

TN3270 requirements

Not all certificates worked. I could only get certificates to work with

  • RSA key size >= 2048
  • NISTECC leysize >= 521

To AT-TLS, this is just a certificate name in a keyring.

In the AT-TLS configuration

  • ApplicationControlled On is required. This allows TN3270 to interact with AT-TLS, for example display the cipher spec being used.
  • HandshakeRole Server is required.
  • It needs a keyring, and access to the private part of the certificate. For example CONTROL access to the RACF profile userid.ring.LST int the RDATALIB class.
  • Certificates
    • If you do not specify a certificate – it takes the keyring default.
    • You can specify a(one) certificatelabel.
    • You can specify multiple ServerCertificateLabel statements. With this you can support different certificate types, and support migration to newer certificates.

AT-TLS configuration – in general

The Communications Server as a group of products, do not have a consistent way of configuring the individual components. For example some use # as a comment delimiter, other products use ; . Configuring the Policy Server is not difficult – just different, and does not behave as other z/OS components do, or as I expected.

In my PAGENT JCL is

//STDENV -> USER.Z24C.TCPPARMS(PAGENTEN).

This file has

PAGENT_CONFIG_FILE=//'USER.Z24C.TCPPARMS(PAGENTCF)' 
LIBPATH=/usr/lib 

The PAGENTCF member is like

CommonTTLSConfig //'USER.Z24C.TCPPARMS(PAGENTCO)' 
tcpImage TCPIP   //'USER.Z24C.TCPPARMS(PAGENTT)' 
tcpImage TCPIP1  //'USER.Z24C.TCPPARMS(PAGENT1)' 

File USER.Z24C.TCPPARMS(PAGENTT) has the configuration for one TCPIP image.

TTLSConfig //'USER.Z24C.TCPPARMS(PAGENTTN)' FLUSH PURGE 
TTLSRULE ... #and other inline definitions 

QOSConfig  //'USER.Z24C.TCPPARMS(PAGENTQ1)' FLUSH PURGE 
policyAction  ...  # and other inline QOS definitions 

# and similarly for IDS, IPSec,Routing etc

You are allowed one TTLSConfig statement per TCPIP file. If you have multiple, only the last one will be used. You can have multiple TTLSRULE statements.

How the configuration works

Within a file, if you have a set of definitions with the same name, the last one will be used. For example

TTLSEnvironmentAction                 TNEA 
{ 
  TTLSKeyringParms 
  { 
    Keyring                   START1/TN3270 
  } 
  Trace 17
} 
TTLSEnvironmentAction                 TNEA 
{ 
  TTLSKeyringParms 
  { 
    Keyring                   START2/TN3270 
  }   
} 

The keyring will be START2/TN3270 and Trace is not specified.

If you use Unix command pasearch -t , it will show keyring:START2/TN3270 and no trace statement in that section. Definitions with the same name are replaced, not merged.

Having just one TTLSCONFIG file makes it harder to manage. I would like to be able to have a configuration file for each port, or have all of the TLSRULEs in one file, and TTLSCipherParms in another file, and so on. It would make it easier to manager, and perform change management on the files.

The configurations from tcpImage TCPIP2 and tcpImage TCPIP2 are isolated from each other. If you want to use common definitions between tcpImages, put them in CommonTTLSConfig file.

The commonTTLSConfig statements are processed before the tcpImage statements, so a definition set in the tcpImage file will take precedence over a common definition.

The commonTTLSConfig file seems to need to be self consistent. I added

TTLSEnvironmentAction                 TNEA 
{ 
  TTLSSignatureParmsRef       TNESigParms 
} 

Without the TNESigParms definition. I got strange configuration error messages until I included the TNESigParms {..} in the file.

Using smaller units.

I remember some advice I was given… try to get all of your changes visible on one screen. Use subroutines or other ways of dividing up the code.

You can have

TTLSCipherParms 
{
   TTLSCipherParms 
   { 
      V3CipherSuites      TLS_CHACHA20_POLY1305_SHA256 
   } 
}

But the list of cipher suites could be long.

You can have a …REFerence o a set of definitions.

TTLSConnectionAction   TNCA 
{ 
  TTLSCipherParmsRef   TLS13TLS12 
} 
TTLSCipherParms        TLS13TLS12 
{ 
  #TLS 1.3 
   V3CipherSuites      TLS_CHACHA20_POLY1305_SHA256 
   #V3CipherSuites      TLS_AES_256_GCM_SHA384 
   #V3CipherSuites      TLS_AES_128_GCM_SHA256 
 #TLS 1.2 
   # NSTECC 
   V3CipherSuites   TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
   #RSA 
   V3CipherSuites      TLS_RSA_WITH_AES_256_CBC_SHA256 
} 

The allows you to create a “subroutine” out of the cipherspecs. It also allows you to use the same definitions in multiple places.

Within a TCPIPIMAGE configuration

The same parameter can be specified in more than one configuration statement. The documentation says:

For parameters that can be specified in multiple action types, the value used by a connection is
determined by the following hierarchical rule set, they first found is used
.

  1. If the parameter is specified in the TTLSConnectionAction statement that is the value used.
  2. If the parameter is specified in the TTLSEnvironmentAction statement that is the value used.
  3. If the parameter is specified in the TTLSGroupAction statement that is the value used.
  4. If a default value is defined, that is the value used.
  5. No value is used by AT-TLS and no parameter is explicitly passed to System SSL.

So if you have

TTLSEnvironmentAction  TNEA 
{ 
  TTLSCipherParmsRef     TLS13 
} 
TTLSConnectionAction   TNCA 
{ 
  TTLSCipherParmsRef    TLS13TLS12 
} 

The the CipherParms TLS13TLS12 will be used, because Connection is used before Environment.

If you use pasearch -t … it will display the configuration with sections like

TTLS Action:                  TNGA 
    Scope:                      Group 

TTLS Action:                  TNEA 
  Scope:                      Environment 

  TTLSCipherParms: 
    v3CipherSuites: 
      1303  TLS_CHACHA20_POLY1305_SHA256 
 ... 
TTLS Action:                  TNCA 
    Scope:                      Connection 
    TTLSCipherParms: 
     v3CipherSuites: 
      1303  TLS_CHACHA20_POLY1305_SHA256 
      C02C  TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 
      003D  TLS_RSA_WITH_AES_256_CBC_SHA256 

Because of the order, Scope:Connection takes precedence over Scope:Environment, the three cipher specs will be used.

When configuring AT-TLS I found it easiest if I used the Unix commands pasearch -t -f TN 1>a; oedit a and specify the rule name I was interested in (TN), then search for the last instance of the attribute of interest

PDSE or Unix file?

If you configuration is in Unix files, then you can get AT-TLS to reread this on regular basis – typically half an hour. This is useful of you want changes to be picked up automatically, but not if you want strict change control management.

AT-TLS configuration for TN3270

Below is the AT-TLS configuration for my telnet (PAGENTTN…) configuration.

TTLSRule                      TN 
{ 
  LocalPortRange              2023 
  Jobname                     TN3270 
  Direction                   INBOUND 
  TTLSConnectionActionRef     TNCA   
  TTLSGroupActionRef          TNGA 
  TTLSEnvironmentActionRef    TNEA 

} 
TTLSConnectionAction              TNCA 
{ 
  TTLSCipherParmsRef              TLS13TLS12 
  TTLSSignatureParmsRef           TNESigParms 
  TTLSConnectionAdvancedParmsRef  TNCOonAdvParms 
  CtraceClearText                 Off 
  Trace                           50 
} 
TTLSConnectionAdvancedParms       TNCOonAdvParms 
{ 
 ServerCertificateLabel  NISTECC521 
 ServerCertificateLabel  RSA2048 
#ccp this was added 
  ApplicationControlled         On 
  SSLv3          OFF 
  TLSv1          OFF 
  TLSv1.1        OFF 
  TLSv1.2        ON 
  TLSv1.3        OFF 
  SecondaryMap   OFF 
  HandshakeTimeout 3 
} 

TTLSGroupAction      TNGA 
{ 
  TTLSEnabled        ON 
  trace              50 
} 
TTLSKeyringParms    TNKEYRING 
{ 
  Keyring           START1/TN3270 
} 

TTLSEnvironmentAction      TNEA 
{ 
  HandshakeRole            Server 
  TTLSKeyringParms 
  { 
    Keyring                START1/TN3270 
  } 
  TTLSSignatureParmsRef    TNESigParms 
} 
TTLSSignatureParms         TNESigParms 
{ 
   CLientECurves Any 
} 
TTLSCipherParms             TLS13TLS12 
{ 
#TLS 1.3 
 V3CipherSuites      TLS_CHACHA20_POLY1305_SHA256 
#V3CipherSuites      TLS_AES_256_GCM_SHA384 
#V3CipherSuites      TLS_AES_128_GCM_SHA256 
#TLS 1.2 
# NSTECC 
 V3CipherSuites      TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 
#RSA 
 V3CipherSuites      TLS_RSA_WITH_AES_256_CBC_SHA256 
} 

I did many system SSL traces to get it working.

Using certificates

  • If you do not specify a certificate label in the configuration, AT-TLS takes the default from the keyring.
  • You can specify a certificate label using CertificateLabel…
  • If you want to specify more than one Certificate label – for example you are migrating from one certificate to another, or you want to support an RSA certificate and an Elliptic Curve certificate then specify one or more ServerCertificateLabel … statements.

Some lessons learned

  • When configuring TN3270 use V3CipherSuites not V3CipherSuites4char. V3CipherSuites takes 2 character identifiers and long TLS_… strings. V3CipherSuites4char only take 4 character identifiers , and not TLS_… strings.
  • If you change the PAGENT configuration you need F PAGNET,UPDATE to pick up the changes.
  • If you make a change to the PAGENT configuration, it does not always report problems. You should use Unix command commands like pagent -t -f TN 1>a ;oedit a to display the TTLS configuration for rule TN, and edit the file to check.
  • If you change a keyring, you need F CPAGENT,REFRESH to pick up the change.
  • When you start PAGENT use the -l /var/log/pagent.log -d1 options. Review the /var/log/pagent.log file and check for “WARNING” and “ERR”
  • The PAGENT configuration can have the same parameter specified at the environment level and at the connection level. The pasearch -t -f TN command displays both sets of data … you have to be careful you are checking the right set of data.
  • PAGENT does not report if a section was skipped. I had two TTLSConfig statements in a TCPIP image file, and only the last one was used.
  • You need the syslogd daemon running to capture error messages in a file.

General PAGENT commands

See here for starting PAGENT (and the trace levels you can use).

Updating PAGENT

If you change the PAGENT configuration (my job is CPAGENT) you can use

F CPAGENT,UPDATE

To refresh the configuration,

F CPAGENT,REFRESH

to refresh the configuration and restart processing. Existing sessions will continue unchanged.

When configuring TN3270 you can use the Unix command pasearch -t -f TN 1>a to display just the TLS policy you are interested in (TN) .

Displaying information

You display configuration information using the Unix command pasearch…

What does a rule configuration look like?

I frequently use

pasearch -t -f TN

This shows me the TLS configuration for rule TN

What does the high level TLS object look like?

pasearch -c -t

gave me

TTLS Policy Object:                                                     
  ConfigLocation:       Local             LDAPServer:        False      
  CommonFileName:                                                       
  ImageFileName:        //'USER.Z24C.TCPPARMS(PAGENTTN)'                
  ApplyFlush:           True              PolicyFlush:       True       
  ApplyPurge:           True              PurgePolicies:     True       
  AtomicParse:          True              DeleteOnNoflush:   False      
  DummyOnEmptyPolicy:   True              ModifyOnIDChange:  False      
  Configured:           True              UpdateInterval:    1800       
  TTLS Enabled:         True                                            
  InstanceId:           1666079380                                      
  LastPolicyChanged:    Tue Oct 18 08:49:40 2022                        

The CommonFileName: value was blank, which was a surprise as I had specified a file.

How to display a summary of a rule?

pasearch -t -n

gave

policyRule:             TN         
  TTLS Action:          TNGA       
  TTLS Action:          TNEA       
  TTLS Action:          TNCA       

How do I display which policy or rule has been used?

I could not find a way of displaying which rules were used, and which options were used.

Using Telnet (TN3270) on z/OS

This article gives some of the lessons I learned from using TN3270. My mission had been to connect x3270 to TN3270 (telnet) using TLS. Some things are obvious once you know, but frustrating all the same.

Creating the configuration

You start TN3270 with the name of the configuration file it should use. For me this was USER.Z24C.TCPPARMS(TN3270).

My file looks like

TelnetGlobals 
....
EndTelnetGlobals 

 include adcd.z24c.tcpparms(port0023)  ; General Applications 
 include user.z24c.tcpparms(tnpt2023)  ; TLS Support AT-TLS 
 include user.z24c.tcpparms(tnpt3023)  ; TLS Support AT-TLS 
                                                                

Where the include files contain self contained information about each port. My member name tnpo2023 is for TelNet, POrt 2023.

Restricting access

You can restrict which IP addresses can use which profile (port). See Transport Layer Security-Telnet profile example. The example below has a few minor tweaks from me.

TelnetParms         ; ATTLS defined secure port 
 TTLSPort 3023      ; 
 DEBUG CONN DETAIL JOBLOG 
 DEBUG CONN trace  CTRACE 
 ConnType None      ; Default is no access
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
 
 PARMSMAP BasicPG localIP  ; hosts defined in IPGROUP localIP 
 PARMSGROUP BasicPG     ; override default ConnType
   CONNTYPE NONE        ; support basic connections if mapped to this group
 ENDPARMSGROUP
; this defines who has access 
 PARMSMAP AdminPG 10.1.0.2 ; this ip address can use secure connections
 PARMSGROUP AdminPG     ; override default ConnType
   CONNTYPE SECURE      ; allow any type of connections if mapped to this group
 ENDPARMSGROUP
 
ENDVTAM

This says

  • The default connection type is NONE (from TelnetParms)
  • IP addresses 10.1.1.0, and 10.1.2.0 have PARMSMAP BASICPG which have CONNTYPE NONE.
  • IP address 10.1.0.2 has PARMSMAP AdminPG which has CONNTYPE SECURE.

Changing the configuration

You can update the TN3270 configuration while it is active. You use a command like

v tcpip,tn3270,obeyfile,USER.Z24C.TCPPARMS(TN3270)

Where USER.Z24C.TCPPARMS(TN3270) is the configuration file used at start up. If you have the configuration spread across several files, you cannot use OBEYFILE on one file – you need to use a complete configuration file. It appears to replace the current configuration with the specified one.

Displaying information.

You can use TSO netstat telnet to display the ports in use by Telnet. For proper display, you need to use the d tcpip,tn3270,…. command.

This is a bit restrictive as it only displays the information on the syslog. You can use Extended consoles, and so REXX can capture the output – but it still writes many records to SYSLOG and the operator console.

Display connection information

You can use the d tcpip,tn3270,conn,detail command, for example

EZZ6064I TN3270 CONN DISPLAY         FRAME LAST   F      E   SYS=S0W1
         ENCR                                           TSP          
CONN     TYPE IPADDR..PORT           LUNAME   APPLID    PTR LOGMODE  
-------- ---- ---------------------- -------- --------  --- --------       
00000048      10.1.0.2..51928        TCP00001 A06TSO02  TAE SNX32703       
----- PORT:    23  ACTIVE           PROF: CURR CONNS:      1               
------------------------------------------------------------               
00000043 C02F 10.1.0.2..48126        TLS00001           TPE                
00000046 C02F 10.1.0.2..40978        TLS00002 A06TSO03  TAE SNX32703       
----- PORT:  2023  ACTIVE           PROF: CURR CONNS:      2               
------------------------------------------------------------                     

Shows message EZZ6064I

  • there are two sessions with PORT 2023. Both using cipher suite C02F. The cipher spec value is described here.
  • The LUNAME of TCP… this comes from the BEGINVTAM .. part of the TN320 definitions.
  • Two terminals are connected to TSO (A06TS002), with the given logmode. The A in TSP means Active

EZZ… messages are here.

I could not see a way of displaying which z/OS certificate is being used.

Display profile information

d tcpip,tn3270,profile

gives

  PERSIS   FUNCTION        DIA  SECURITY    TIMERS   MISC        
 (LMTGCAK)(OPATSKTQSSHRTL)(DRF)(PCKLECXN23)(IPKPSTS)(SMLT)       
  -------  --------------  ---  ----------  -------  ----        
  L******  ***TSBTQ***RT*  TT*  BB********  IP**ST*  SMD*        
----- PORT:    23  ACTIVE           PROF: CURR CONNS:      0     
------------------------------------------------------------     
  L******  ***TSBTQ***RT*  TJ*  TSTTTT**TT  IP**STT  SMD*        
----- PORT:  2023  ACTIVE           PROF: CURR CONNS:      0     
------------------------------------------------------------     
  L******  ***TSBTQ***RT*  TJ*  TSTTTT**TT  IP**STT  SMD*        
----- PORT:  3023  ACTIVE           PROF: CURR CONNS:      1     
------------------------------------------------------------     
   FORMAT            LONG                                        
   NOSMFPROFILE                                                  
   TCPIPJOBNAME      TCPIP                                       
   TNSACONFIG        DISABLED                                    
   DEBUG TASK        EXCEPTION  CONSOLE                          
   DEBUG CONFIG      EXCEPTION  CONSOLE                          
   DEBUG CONFIG      TRACEOFF                                    
21 OF 21 RECORDS DISPLAYED                                       

If you issue d tcpip,tn3270,profile,detail you get a lot of output – it will display only the first nnn lines. You can change this value by d tcpip,tn3270,profile,detail,MAX=200.

You may find it easier to specify a port tcpip,tn3270,profile,port=23,detail to get less output.

To display the TN3270 configuration options you can specify profile=…

d tcpip,tn3270,profile,port=3023,profile=xxxx,detail

Where profile=xxxx can be PROFile =CURRent|prfid|ACTive|ALL|Basic|Pending|Secure

Current, Active, ALL and basic seem to display the same information. I do not know the difference between them.

Displaying “VTAM” information

You can display some of the configuration, but not all of it. For example

D TCPIP,TN3270,object,PORT=3023,type=parmsgrp

gives

OBJECT      CONNS  CLIENT ID CLIENT ID        ITEM                    
NAME        USING  TYPE      NAME             SPECIFIC   OPTIONS      
----------  ------ --------- ---------------- ---------- --------     
PARMSGRP                                                              
 BASICPG         0 IPGRP     LOCALIP   
 ADMINPG         1 IPADDR    10.1.0.2                                 

But you cannot display what LOCALIP is.

Where does the parameter come from?

d tcpip,tn3270,profile,port=3023,detail

This command gives

EZZ6080I TN3270 PROFILE DISPLAY 771                                          
  PERSIS   FUNCTION        DIA  SECURITY    TIMERS   MISC                    
 (LMTGCAK)(OPATSKTQSSHRTL)(DRF)(PCKLECXN23)(IPKPSTS)(SMLT)                   
  -------  --------------  ---  ----------  -------  ----                    
  *******  ***TSBTQ***RT*  EC*  BB********  *P**STS  *DD* *DEFAULT           
  L------  ------------T   TT-  ----------  I---ST-  SM-- *TGLOBAL           
  -------  -------------   TJ-  TSTTTT--TT  ------T  ---- *TPARMS            
  L******  ***TSBTQ***RT*  TJ*  TSTTTT**TT  IP**STT  SMD* CURR               

The field column headings are described here.

  • * means the option was turned off
  • – the option was not set.

In the first column (LMTGCAK)

  • The default is *
  • From the T(elnet)GLOBAL the value is L
  • From T(elnet)PARMS nothing is specified
  • So the Current definition is L

Quiescing and resuming ports

Quiescing a port stops new connections from using it. Resume allows it to be used.

v tcpip,tn3270,quiesce,port=3023
v tcpip,tn3270,resume,port=3023

Stopping a port may be bad for you

You can use a command

v tcpip,tn3270,stop,port=3023

Which cancels existing sessions using the port, and stops new connections from using it.

I cannot find how to start the port.

If you use

v tcpip,tn3270,obeyfile,USER.Z24C.TCPPARMS(TN3270)

to refresh the whole configuration all ports are restarted, so you can start all – but not just one port.