TclTLS
Diff
Login
HomeTimelineDownloadBrowse SourceBranchesTagsTicketsWiki
Annotate Patch Side-by-side Diff

Differences From Artifact [dd76fd83fe]:

To Artifact [a3ee30595b]:



1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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 &lt;[email protected]&gt;">
<meta name="Copyright" content="1999 Matt Newman.">
<meta name="GENERATOR" content="Microsoft FrontPage Express 2.0">
<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

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="#CONFIGURATION OPTIONS">CONFIGURATION OPTIONS</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

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></p>
<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

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>-cafile </strong><em>filename</em></dt>
        <dd>Provide the CA file.</dd>
        <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>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>
        <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>) <em>[Not
            client.(<strong>default</strong>: <em>false</em>)</dd>
            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>




︙


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

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>
<h3><a name="CONFIGURATION OPTIONS">CONFIGURATION OPTIONS</a></h3>
    <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>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
<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
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>
<strong>tls::socket</strong> or <strong>tls::import</strong>.
</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>
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.
<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>
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>
&quot;secret&quot;</em> - you should redefine this procedure
after issuing the <em>package require tls</em>.</p>
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

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>
Copyright &copy; 1999 Matt Newman.
</pre>
</body>
</html>













Powered by Fossil · RSS