x3270 and TLS

x3270 supports secure communication via the Transport Layer Security protocol (TLS), formerly called the Secure Sockets Layer (SSL). (The text below refers to x3270, but the descriptions apply to all of the members of the suite.)

A secure connection can be negotiated immediately by specifying the L: prefix on the hostname (e.g., L:foo.whatever.net), or can be negotiated later via the TELNET STARTTLS option, which is initiated by the host after the connection has been established.

TLS on Unix (except MacOS)

On Unix (except for MacOS), x3270 TLS support uses the OpenSSL library. Much of the information below is common to many OpenSSL clients and more extensive documentation is available on the Web.

A Note on PEM Format

PEM (Privacy Enhanced Mail) is a text file format used for TLS certificates and private keys. It is easily recognized by headers like the following:

  -----BEGIN CERTIFICATE-----

A certificate is the text between (and including) the BEGIN CERTIFICATE and END CERTIFICATE headers. A private key is the text between (and including) the BEGIN RSA PRIVATE KEY and END RSA PRIVATE KEY headers. A PEM-format file can contain multiple certificates and keys.

Options and Resources

TLS is controlled by a number of different command-line options and resources.

Specifying the Server's Root Certificate

If your host's certificate was not signed by a well-known certificate authority (CA), you can configure x3270 to accept it by specifying an alternate set of root certificate(s).

The -cafile option (or the caFile resource) can be used to specify a file containing one or more server root certificates. This file must be in PEM format.

If there are a large number of certificates, the -cadir option (or the caDir resource) can be used to specify a directory containing root certificates. This directory contains files that use the naming convention of hash.seq, where hash is the hash of the certificate value and seq is a sequence number (since multiple certificates could have the same hash) starting with 0.

If your host uses a self-signed certificate, x3270 will not normally allow TLS authentication with it. To allow authentication with self-signed certificates, set the selfSignedOk resource to true.

Updating the Root Certificate Database

To avoid having to specify a root certificate for each invocation of x3270, one or more certificates can be added to the OpenSSL root certificate database. On Unix, this procedure is (unfortunately) an operating-system- and release- specific procedure. However, the OpenSSL root certificate database is common to all OpenSSL applications on your workstation, so instructions on updating it should be easily found on the web.

Specifying a Certificate for the Client (the Emulator)

If you have been issued a certificate and a private key to allow your client (the emulator) to be authenticated by your host, there are several options that allow this to be specified to x3270.

The -certfile option (or the certFile resource) defines a file containing the client certificate. By default, this file is in PEM format, but it can also be in ASN1 format, which is specified by setting the -certfiletype option (or the certFileType resource) to the value asn1.

The -chainfile option (or the chainFile resource) defines a PEM-format file containing both the client certificate and any intermediate certificates that were used to sign it. If a chain file is specified, it is used instead of the certificate file.

Specifying the Private Key for the Client Certificate

The file containing the private key for the client certificate can be specified by the -keyfile option or the keyFile resource. This file is in PEM format by default, but can be in ASN1 format, by specifying the -keyfiletype option or the keyFileType resource with the value asn1.

If no explicit key file is specified, the default is to find the private key in the chain file or the client certificate file (whichever was specified).

If the private key is encrypted, then a password must be specified. x3270 and c3270 will prompt for a password interactively. For the other emulators, the password is given with the -keypasswd option or the keyPasswd resource. (These also work with x3270 and c3270.) The password can have one of two formats. The format file:filename specifies a file containing the password. The format string:string specifies the password as a string in the option or resource directly.

Controlling Host Certificate Verification

By default, host certificates are always verified. To disable host certificate verification, set the verifyHostCert resource to false or specify the -noverifycert option.

When host certificates are verified, self-signed certificates are not allowed. To allow self-signed host certificates, set the selfSignedOk resource to true or specify the -selfsignedok option.

Also, when host certificates are verified, the name in the host's certificate is checked. This check can be controlled by the acceptHostname resource or the -accepthostname option. The value can be any, which disables hostname checking, or a specific hostname to use for comparison. (The form DNS:hostname is also available for backwards-compatibility.)

TLS on MacOS

On MacOS, x3270 uses Secure Transport for TLS.

Options and Resources

TLS is controlled by a number of different command-line options and resources.

Specifying a Certificate for the Client (the Emulator)

The -clientcert option (or the clientCert resource) gives the name of a client certificate to be used. This certificate must be installed in the keychain.

The -certfile option (or the certFile resource) defines a file containing the client certificate. The file must be in PKCS12 format.

Specifying a Password for the Client Certificate File

If the private key is encrypted, then a password must be specified. x3270 and c3270 will prompt for a password interactively. For the other emulators, the password is given with the -keypasswd option or the keyPasswd resource. (These also work with x3270 and c3270.) The password can have one of two formats. The format file:filename specifies a file containing the password. The format string:string specifies the password as a string in the option or resource directly.

Controlling Host Certificate Verification

By default, host certificates are always verified. To disable host certificate verification, set the verifyHostCert resource to false or specify the -noverifycert option.

When host certificates are verified, the name in the host's certificate is compared to the name used to establish the connection. The acceptHostname resource or the -accepthostname option can be used to specify a different name to compare.

TLS on Windows

wc3270, ws3270 and wpr3287 use the native Windows Schannel APIs for TLS. This means that the emulators' TLS support is limited by the functionality supported by the underlying OS, but it benefits from OS fixes and updates over time without any need to update the app.

Options and Resources

TLS is controlled by a number of different command-line options and resources.

Specifying a Certificate for the Client (the Emulator)

The -clientcert option (or the clientCert resource) gives the name of a client certificate to be used. This certificate must be installed in the Personal certificate store.

Controlling Host Certificate Verification

By default, host certificates are always verified. To disable host certificate verification, set the verifyHostCert resource to false or specify the -noverifycert option.

When host certificates are verified, the name in the host's certificate is compared to the name used to establish the connection. The acceptHostname resource or the -accepthostname option can be used to specify a different name to compare.