1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
<h1>x3270 and TLS</h1>
x3270 supports secure communication via the Transport Layer Security protocol
(TLS), formerly called the Secure Sockets Layer (SSL). (The text
below refers to <i>x3270</i>, but the descriptions apply to all of the
members of the suite.)
<p>
A secure connection can be negotiated immediately by specifying the
<b>L:</b> prefix on the hostname (e.g., <b>L:foo.whatever.net</b>), or can
be negotiated later via the TELNET STARTTLS option, which is initiated by
the host after the connection has been established.</p>
<h2>TLS on Unix (except MacOS)</h2>
<p>On Unix (except for MacOS), x3270 TLS support uses the
<a href="http://www.openssl.org">OpenSSL</a> library.
Much of the information below is common to many OpenSSL clients and more
extensive documentation is available on the Web.
<h3>A Note on PEM Format</h3>
<i>PEM</i> (Privacy Enhanced Mail) is a text file format used for TLS
certificates and private keys.
It is easily recognized by headers like the following:
<p> <tt>-----BEGIN CERTIFICATE-----</tt>
<p>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.
<h3>Options and Resources</h3>
TLS is controlled by a number of different command-line options and resources.
<h3>Specifying the Server's Root Certificate</h3>
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).
</p>The <b>-cafile</b> option (or the <b>caFile</b> resource) can be used to
specify a file containing one or more server root certificates.
This file must be in PEM format.</p>
<p>If there are a large number of certificates, the <b>-cadir</b> option (or
the <b>caDir</b> resource) can be used to specify a directory containing root
certificates.
This directory contains files that use the naming convention of
<i>hash</i>.<i>seq</i>, where <i>hash</i> is the hash of the certificate
value and <i>seq</i> is a sequence number (since multiple certificates could
have the same hash) starting with 0.
<p>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 <b>selfSignedOk</b> resource to <b>true</b>.
<h3>Updating the Root Certificate Database</h3>
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.
<h3>Specifying a Certificate for the Client (the Emulator)</h3>
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.
<p>The <b>-certfile</b> option (or the <b>certFile</b> 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 <b>-certfiletype</b> option (or the
<b>certFileType</b> resource) to the value <b>asn1</b>.</p>
<p>The <b>-chainfile</b> option (or the <b>chainFile</b> 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.</p>
<h3>Specifying the Private Key for the Client Certificate</h3>
The file containing the private key for the client certificate can be specified
by the <b>-keyfile</b> option or the <b>keyFile</b> resource.
This file is in PEM format by default, but can be in ASN1 format, by
specifying the <b>-keyfiletype</b> option or the <b>keyFileType</b> resource
with the value <b>asn1</b>.
<p>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).</p>
<p>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 <b>-keypasswd</b>
option or the <b>keyPasswd</b> resource. (These also work with x3270 and c3270.)
The password can have one of two formats.
The format <b>file:</b><i>filename</i> specifies a file containing the password.
The format <b>string:</b><i>string</i> specifies the password as a string in
the option or resource directly.</p>
<h3>Controlling Host Certificate Verification</h3>
By default, host certificates are always verified.
To disable host certificate verification, set the <b>verifyHostCert</b>
resource to <b>false</b> or specify the <b>-noverifycert</b> option.
<p> When host certificates are verified, self-signed certificates are not
allowed.
To allow self-signed host certificates, set the <b>selfSignedOk</b> resource
to <b>true</b> or specify the <b>-selfsignedok</b> option.
<p>
Also, when host certificates are verified, the name in the host's
certificate is checked.
This check can be controlled by the <b>acceptHostname</b> resource or the
<b>-accepthostname</b> option.
The value can be <b>any</b>, which disables hostname checking, or
a specific hostname to use for comparison. (The form <b>DNS:hostname</b> is
also available for
backwards-compatibility.)
<a name="MacOS"></a>
<h2>TLS on MacOS</h2>
<p>On MacOS, x3270 uses Secure Transport for TLS.</p>
<h3>Options and Resources</h3>
TLS is controlled by a number of different command-line options and resources.
<h3>Specifying a Certificate for the Client (the Emulator)</h3>
<p>The <b>-clientcert</b> option (or the <b>clientCert</b> resource) gives the
name of a client certificate to be used. This certificate must be installed in
the keychain.
<p>The <b>-certfile</b> option (or the <b>certFile</b> resource) defines a
file containing the client certificate.
The file must be in PKCS12 format.
<h3>Specifying a Password for the Client Certificate File</h3>
<p>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 <b>-keypasswd</b>
option or the <b>keyPasswd</b> resource. (These also work with x3270 and c3270.)
The password can have one of two formats.
The format <b>file:</b><i>filename</i> specifies a file containing the password.
The format <b>string:</b><i>string</i> specifies the password as a string in
the option or resource directly.</p>
<h3>Controlling Host Certificate Verification</h3>
By default, host certificates are always verified.
To disable host certificate verification, set the <b>verifyHostCert</b>
resource to <b>false</b> or specify the <b>-noverifycert</b> option.
<p>
When host certificates are verified, the name in the host's
certificate is compared to the name used to establish the connection.
The <b>acceptHostname</b> resource or the <b>-accepthostname</b> option can be
used to specify a different name to compare.
<a name="Windows"></a>
<h2>TLS on Windows</h2>
<p>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.</p>
<h3>Options and Resources</h3>
TLS is controlled by a number of different command-line options and resources.
<h3>Specifying a Certificate for the Client (the Emulator)</h3>
<p>The <b>-clientcert</b> option (or the <b>clientCert</b> resource) gives the
name of a client certificate to be used. This certificate must be installed in
the Personal certificate store.
<h3>Controlling Host Certificate Verification</h3>
By default, host certificates are always verified.
To disable host certificate verification, set the <b>verifyHostCert</b>
resource to <b>false</b> or specify the <b>-noverifycert</b> option.
<p>
When host certificates are verified, the name in the host's
certificate is compared to the name used to establish the connection.
The <b>acceptHostname</b> resource or the <b>-accepthostname</b> option can be
used to specify a different name to compare.
|
