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”
ColinPaice 