1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
|
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author"
content="Matt Newman <matt@novadigm.com>">
<meta name="Copyright" content="1999 Matt Newman.">
<meta name="GENERATOR" content="Microsoft FrontPage Express 2.0">
|
>
>
<
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
|
<!doctype html public "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author"
content="Matt Newman <matt@novadigm.com>">
<meta name="Copyright" content="1999 Matt Newman.">
<title>TLS (SSL) Tcl Commands</title>
</head>
<body bgcolor="#FFFFFF">
<dl>
<dd><a href="#NAME">NAME</a> <dl>
|
| ︙ | | | ︙ | |
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
|
<dd><b>tls::socket </b><em>?options? host port</em></dd>
<dd><b>tls::socket</b><em> ?-server command?
?options? port</em></dd>
<dd><b>tls::handshake</b><em> channel</em></dd>
<dd><b>tls::status </b><em>?-local? channel</em></dd>
<dd><b>tls::import</b><em> channel ?options?</em></dd>
<dd><b>tls::ciphers </b><em>protocol ?verbose?</em></dd>
</dl>
</dd>
<dd><a href="#COMMANDS">COMMANDS</a></dd>
<dd><a href="#CONFIGURATION OPTIONS">CONFIGURATION OPTIONS</a></dd>
<dd><a href="#HTTPS EXAMPLE">HTTPS EXAMPLE</a></dd>
<dd><a href="#SEE ALSO">SPECIAL CONSIDERATIONS</a></dd>
<dd><a href="#SEE ALSO">SEE ALSO</a></dd>
</dl>
<hr>
|
>
|
|
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
|
<dd><b>tls::socket </b><em>?options? host port</em></dd>
<dd><b>tls::socket</b><em> ?-server command?
?options? port</em></dd>
<dd><b>tls::handshake</b><em> channel</em></dd>
<dd><b>tls::status </b><em>?-local? channel</em></dd>
<dd><b>tls::import</b><em> channel ?options?</em></dd>
<dd><b>tls::ciphers </b><em>protocol ?verbose?</em></dd>
<dd><b>tls::version</b></dd>
</dl>
</dd>
<dd><a href="#COMMANDS">COMMANDS</a></dd>
<dd><a href="#CALLBACK OPTIONS">CALLBACK OPTIONS</a></dd>
<dd><a href="#HTTPS EXAMPLE">HTTPS EXAMPLE</a></dd>
<dd><a href="#SEE ALSO">SPECIAL CONSIDERATIONS</a></dd>
<dd><a href="#SEE ALSO">SEE ALSO</a></dd>
</dl>
<hr>
|
| ︙ | | | ︙ | |
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
|
port</em><br>
<b>tls::socket</b><em> ?-server command? ?options? port</em><br>
</a><a href="#tls::status"><b>tls::status </b><em>?-local? channel</em><br>
</a><a href="#tls::handshake"><b>tls::handshake</b><em> channel</em></a><br>
<br>
<a href="#tls::import"><b>tls::import </b><i>channel ?options?</i></a><br>
<a href="#tls::ciphers protocol ?verbose?"><strong>tls::ciphers</strong>
<em>protocol ?verbose?</em></a></p>
<h3><a name="DESCRIPTION">DESCRIPTION</a></h3>
<p>This extension provides a generic binding to <a
href="http://www.openssl.org/">OpenSSL</a>, utilizing the
<strong>Tcl_StackChannel</strong>
API for Tcl 8.2 and higher. The sockets behave exactly the same
|
|
>
>
|
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
|
port</em><br>
<b>tls::socket</b><em> ?-server command? ?options? port</em><br>
</a><a href="#tls::status"><b>tls::status </b><em>?-local? channel</em><br>
</a><a href="#tls::handshake"><b>tls::handshake</b><em> channel</em></a><br>
<br>
<a href="#tls::import"><b>tls::import </b><i>channel ?options?</i></a><br>
<a href="#tls::ciphers protocol ?verbose?"><strong>tls::ciphers</strong>
<em>protocol ?verbose?</em></a><br>
<a href="#tls::version"><b>tls::version</b></a>
</p>
<h3><a name="DESCRIPTION">DESCRIPTION</a></h3>
<p>This extension provides a generic binding to <a
href="http://www.openssl.org/">OpenSSL</a>, utilizing the
<strong>Tcl_StackChannel</strong>
API for Tcl 8.2 and higher. The sockets behave exactly the same
|
| ︙ | | | ︙ | |
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
<dd>SSL-enable a regular Tcl channel - it need not be a
socket, but must provide bi-directional flow. Also
setting session parameters for SSL handshake.</dd>
</dl>
<blockquote>
<dl>
<dt><strong>-cafile </strong><em>filename</em></dt>
<dd>Provide the CA file.</dd>
<dd>This callback is invoked to pass errors, tracing
information and to allow Tcl scripts to perform
additional verification of the certificate, which can
override the default validation in OpenSSL.</dd>
<dt><strong>-keyfile</strong> <em>filename</em></dt>
<dd>Provide the private key file. (<strong>default</strong>:
value of -certfile)</dd>
<dt><strong>-model</strong> <em>channel</em></dt>
<dd>This will force this channel to share the same <em><strong>SSL_CTX</strong></em>
structure as the specified <em>channel</em>, and
therefore share callbacks etc.</dd>
<dt><strong>-request </strong><em>bool</em></dt>
<dd>Request a certificate from peer during SSL handshake.
(<strong>default</strong>: <em>true</em>)</dd>
<dt><strong>-require</strong> <em>bool</em></dt>
<dd>Require a valid certificate from peer during SSL
handshake. If this is set to true then <strong>-request</strong>
must also be set to true. (<strong>default</strong>: <em>false</em>)</dd>
<dt><strong>-server</strong> <em>bool</em></dt>
<dd>Handshake as server if true, else handshake as
client.(<strong>default</strong>: <em>false</em>) <em>[Not
available to tls::socket]</em></dd>
<dt><strong>-ssl2</strong> <em>bool</em></dt>
<dd>Enable use of SSL v2. (<strong>default</strong>: <em>true</em>
unless -DNO_PATENTS was specified in build)</dd>
<dt><strong>-ssl3 </strong><em>bool</em></dt>
<dd>Enable use of SSL v3. (<strong>default</strong>: <em>true</em>)</dd>
<dt>-<strong>tls1</strong> <em>bool</em></dt>
<dd>Enable use of TLS v1. (<strong>default</strong>: <em>false</em>)</dd>
|
<
<
>
>
|
>
|
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
|
<
|
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
<dd>SSL-enable a regular Tcl channel - it need not be a
socket, but must provide bi-directional flow. Also
setting session parameters for SSL handshake.</dd>
</dl>
<blockquote>
<dl>
<dt>-<strong>cadir</strong> <em>dir</em></dt>
<dd>Provide the directory containing the CA certificates.</dd>
<dt><strong>-cafile </strong><em>filename</em></dt>
<dd>Provide the CA file.</dd>
<dt><strong>-certfile</strong> <em>filename</em></dt>
<dd>Provide the certificate to use.</dd>
<dt><strong>-cipher </strong><em>string</em></dt>
<dd>Provide the cipher suites to use. Syntax is as per
OpenSSL.</dd>
<dt><strong>-command</strong><em> callback</em></dt>
<dd>If specified, this callback will be invoked at several points
during the OpenSSL handshake. It can pass errors and tracing
information, and it can allow Tcl scripts to perform
their own validation of the certificate in place of the
default validation provided by OpenSSL.
The callback should return an integer whose interpretation
depends on context.
<br>
See <a href="#CALLBACK OPTIONS">CALLBACK OPTIONS</a> for
further discussion.</dd>
<dt><strong>-keyfile</strong> <em>filename</em></dt>
<dd>Provide the private key file. (<strong>default</strong>:
value of -certfile)</dd>
<dt><strong>-model</strong> <em>channel</em></dt>
<dd>This will force this channel to share the same <em><strong>SSL_CTX</strong></em>
structure as the specified <em>channel</em>, and
therefore share callbacks etc.</dd>
<dt><strong>-password</strong><em> callback</em></dt>
<dd>If supplied, this callback will be invoked when OpenSSL needs
to obtain a password, typically for a certificate.
The callback should return a string which represents the
password to be used.
<br>
See <a href="#CALLBACK OPTIONS">CALLBACK OPTIONS</a> for
further discussion.</dd>
<dt><strong>-request </strong><em>bool</em></dt>
<dd>Request a certificate from peer during SSL handshake.
(<strong>default</strong>: <em>true</em>)</dd>
<dt><strong>-require</strong> <em>bool</em></dt>
<dd>Require a valid certificate from peer during SSL
handshake. If this is set to true then <strong>-request</strong>
must also be set to true. (<strong>default</strong>: <em>false</em>)</dd>
<dt><strong>-server</strong> <em>bool</em></dt>
<dd>Handshake as server if true, else handshake as
client.(<strong>default</strong>: <em>false</em>)</dd>
<dt><strong>-ssl2</strong> <em>bool</em></dt>
<dd>Enable use of SSL v2. (<strong>default</strong>: <em>true</em>
unless -DNO_PATENTS was specified in build)</dd>
<dt><strong>-ssl3 </strong><em>bool</em></dt>
<dd>Enable use of SSL v3. (<strong>default</strong>: <em>true</em>)</dd>
<dt>-<strong>tls1</strong> <em>bool</em></dt>
<dd>Enable use of TLS v1. (<strong>default</strong>: <em>false</em>)</dd>
|
| ︙ | | | ︙ | |
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
you supply, which must be one of <em>ssl2, ssl3, or tls1</em>.
If <em>verbose</em> is specified as true then a verbose,
semi-human readable list is returned providing additional
information on the nature of the cipher support. In each
case the result is a Tcl list.</dd>
</dl>
<h3><a name="CONFIGURATION OPTIONS">CONFIGURATION OPTIONS</a></h3>
<p>In addition to the options listed above you can set the <strong>tls::debug</strong>
flag to a non-zero value to see the output from the default
command callback (<strong>tls::callback</strong>) which shows the
progression of the SSL handshake. Setting this value to greated
than 1 will cause the default verify method in <strong>tls::callback</strong>
to always accept the certificate, even if it is invalid.</p>
<p>In a real-world deployment you should substitute your own
callback in place of <strong>tls::callback</strong>, via the <em>-command
</em>option to <strong>tls::socket</strong> or <strong>tls::import</strong>.</p>
<p>When the TLS layer needs to obtain a password, typically for a
certificate, the software will invoke a Tcl command called <strong>tls::password</strong>,
which should return a string which represents the password to be
used. A default implementation is provided, which simply returns<em>
"secret"</em> - you should redefine this procedure
after issuing the <em>package require tls</em>.</p>
|
>
|
>
>
>
|
<
>
>
>
|
<
|
|
|
>
|
>
>
>
>
|
>
>
>
|
>
|
>
>
>
>
|
>
>
>
>
|
<
>
|
|
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
|
you supply, which must be one of <em>ssl2, ssl3, or tls1</em>.
If <em>verbose</em> is specified as true then a verbose,
semi-human readable list is returned providing additional
information on the nature of the cipher support. In each
case the result is a Tcl list.</dd>
</dl>
<dl>
<dt><a name="tls::version"><strong>tls::version</strong></a></dt>
<dd>Returns the version string defined by OpenSSL.</dd>
</dl>
<h3><a name="CALLBACK OPTIONS">CALLBACK OPTIONS</a></h3>
<p>
As indicated above, individual channels can be given their own callbacks
to handle intermediate processing by the OpenSSL library, using the
<em>-command</em> and <em>-password</em> options passed to either of
<strong>tls::socket</strong> or <strong>tls::import</strong>.
</p>
<p>
Reference implementations of these callbacks are provided in the distribution
as <strong>tls::callback</strong> and <strong>tls::password</strong>.
Note that these are <em>sample</em> implementations only. In a more realistic
deployment you would substitute your own callbacks, typically by configuring
the <em>-command</em> and <em>-password</em> options on each channel with
scripts to be executed when the callbacks are invoked.
</p>
<p>
The default behavior when the <em>-command</em> option is not specified is for
TLS to process the associated library callbacks internally.
The default behavior when the <em>-password</em> option is not specified is for
TLS to process the associated library callbacks by attempting to call
<strong>tls::password</strong>.
The difference between these two behaviors is a consequence of maintaining
compatibility with earlier implementations. The use of implied callbacks
is not recommended.
</p>
<p>
The <strong>tls::debug</strong> variable provides some additional control
over the default commands. Its value is zero by default. Higher values
produce more diagnostic output. Setting this value greater than zero
will also force the default verify method in <strong>tls::callback</strong>
to accept the certificate, even if it is invalid.
</p>
<h3><a name="HTTPS EXAMPLE">HTTPS EXAMPLE</a></h3>
<p>This example requires a patch to the <strong>http</strong>
module that ships with Tcl - this patch has been submitted for
inclusion in Tcl 8.2.1, but is also provided in the tls directory
if needed. A sample server.pem is provided with the TLS release,
|
| ︙ | | | ︙ | |
260
261
262
263
264
265
266
267
268
269
|
<p><strong>socket</strong>, <strong>fileevent, </strong><a
href="http://www.openssl.org/"><strong>OpenSSL</strong></a></p>
<hr>
<pre>
Copyright © 1999 Matt Newman.</pre>
</body>
</html>
|
|
>
|
299
300
301
302
303
304
305
306
307
308
309
|
<p><strong>socket</strong>, <strong>fileevent, </strong><a
href="http://www.openssl.org/"><strong>OpenSSL</strong></a></p>
<hr>
<pre>
Copyright © 1999 Matt Newman.
</pre>
</body>
</html>
|