TclTLS
Check-in [20fd9291ba]
Login
HomeTimelineDownloadBrowse SourceBranchesTagsTicketsWiki
Overview
Comment:Unify result handling in callback options.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 20fd9291ba51d15f9f1807adde4d3bd2dd915eab
User & Date: razzell on 2004-02-13 02:09:21
Other Links: manifest | tags
Context
2004-02-17
21:27
TLS 1.5.0 RELEASED check-in: ba5a968fc6 user: razzell tags: trunk, tls-1-5-0
2004-02-13
02:09
Unify result handling in callback options. check-in: 20fd9291ba user: razzell tags: trunk
2004-02-11
22:41
Complete private key name changes introduced in tlsIO.c Revision 1.18. check-in: c6821b0cf1 user: razzell tags: trunk
Changes
Side-by-Side Diff Ignore Whitespace Patch
Modified ChangeLog from [ca64c2cd1b] to [06a92d1c72]. 










1
2
3
4
5
6
7

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

+
+
+
+
+
+
+
+
+
+








2004-02-12  Dan Razzell	<research@starfishsystems.ca>

	* tls.c:	Allow verify callback to return empty result.
	* tls.htm:	Document callback behaviors.

2004-02-11  Dan Razzell	<research@starfishsystems.ca>

	* tests/tlsIO.test:
	* remote.tcl:	Complete private key name changes from 2001-06-21.

2004-02-03  Dan Razzell <research@starfishsystems.ca>

	* Makefile.in:	Removed circular dependency.
	* tlsInt.h:	Make function declarations explicit.
	* tls.c:	Fix type match and unused variable warnings.
	* tlsBIO.c:	Fix type match warning.





︙





Modified tls.c
from [ebec730afe]
to [e64436e2e3].





1
2
3
4
5
6

7
8

9
10
11
12
13
14
15

1
2
3
4
5

6
7

8
9
10
11
12
13
14
15






-
+

-
+








/*
 * Copyright (C) 1997-1999 Matt Newman <matt@novadigm.com>
 * some modifications:
 *	Copyright (C) 2000 Ajuba Solutions
 *	Copyright (C) 2002 ActiveState Corporation
 *	Copyright (C) 2003 Starfish Systems 
 *	Copyright (C) 2004 Starfish Systems 
 *
 * $Header: /home/rkeene/tmp/cvs2fossil/../tcltls/tls/tls/tls.c,v 1.19 2004/02/04 04:02:19 razzell Exp $
 * $Header: /home/rkeene/tmp/cvs2fossil/../tcltls/tls/tls/tls.c,v 1.20 2004/02/13 02:09:21 razzell Exp $
 *
 * TLS (aka SSL) Channel - can be layered on any bi-directional
 * Tcl_Channel (Note: Requires Trf Core Patch)
 *
 * This was built (almost) from scratch based upon observation of
 * OpenSSL 0.9.2B
 *




︙


217
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

217
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








-
+

-
+


-
+
+
+
+









-
-
+
+
+








}

/*
 *-------------------------------------------------------------------
 *
 * VerifyCallback --
 *
 *	monitors SSL cerificate validation process
 *	Monitors SSL certificate validation process.
 *	This is called whenever a certificate is inspected
 *	 or decided invalid
 *	or decided invalid.
 *
 * Results:
 *	ok - let SSL handle it
 *	A callback bound to the socket may return one of:
 *	    0			- the certificate is deemed invalid
 *	    1			- the certificate is deemed valid
 *	    empty string	- no change to certificate validation
 *
 * Side effects:
 *	The err field of the currently operative State is set
 *	  to a string describing the SSL negotiation failure reason
 *-------------------------------------------------------------------
 */
static int
VerifyCallback(int ok, X509_STORE_CTX *ctx)
{
    Tcl_Obj *cmdPtr;
    char *errStr;
    Tcl_Obj *cmdPtr, *result;
    char *errStr, *string;
    int length;
    SSL   *ssl		= (SSL*)X509_STORE_CTX_get_app_data(ctx);
    X509  *cert		= X509_STORE_CTX_get_current_cert(ctx);
    State *statePtr	= (State*)SSL_get_app_data(ssl);
    int depth		= X509_STORE_CTX_get_error_depth(ctx);
    int err		= X509_STORE_CTX_get_error(ctx);

    dprintf(stderr, "Verify: %d\n", ok);




︙


280
281
282
283
284
285
286
287

288
289
290




291

292
293
294



295
296
297
298
299
300
301
302

303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322

284
285
286
287
288
289
290

291
292
293
294
295
296
297
298

299



300
301
302
303
304
305
306
307
308
309

310
311
312
313
314
315
316
317
318
319
320



321
322
323
324
325
326
327








-
+



+
+
+
+
-
+
-
-
-
+
+
+







-
+










-
-
-








	    Tcl_NewStringObj( errStr ? errStr : "", -1) );

    Tcl_Preserve( (ClientData) statePtr->interp);
    Tcl_Preserve( (ClientData) statePtr);

    Tcl_IncrRefCount( cmdPtr);
    if (Tcl_GlobalEvalObj(statePtr->interp, cmdPtr) != TCL_OK) {
	/* it got an error - reject the certificate */
	/* It got an error - reject the certificate.		*/
	Tcl_BackgroundError( statePtr->interp);
	ok = 0;
    } else {
	result = Tcl_GetObjResult(statePtr->interp);
	string = Tcl_GetStringFromObj(result, &length);
	/* An empty result leaves verification unchanged.	*/
	if (length > 0) {
	if (Tcl_GetIntFromObj( statePtr->interp,
	    if (Tcl_GetIntFromObj(statePtr->interp, result, &ok) != TCL_OK) {
		    Tcl_GetObjResult( statePtr->interp), &ok) != TCL_OK) {
	    Tcl_BackgroundError( statePtr->interp);
	    ok = 0;
		Tcl_BackgroundError(statePtr->interp);
		ok = 0;
	    }
	}
    }
    Tcl_DecrRefCount( cmdPtr);

    Tcl_Release( (ClientData) statePtr);
    Tcl_Release( (ClientData) statePtr->interp);

    return(ok);	/* leave the disposition as SSL set it */
    return(ok);	/* By default, leave verification unchanged.	*/
}

/*
 *-------------------------------------------------------------------
 *
 * Tls_Error --
 *
 *	Calls callback with $fd and $msg - so the callback can decide
 *	what to do with errors.
 *
 * Results:
 *	ok - let SSL handle it
 *
 * Side effects:
 *	The err field of the currently operative State is set
 *	  to a string describing the SSL negotiation failure reason
 *-------------------------------------------------------------------
 */
void
Tls_Error(State *statePtr, char *msg)




︙





Modified tls.htm
from [59c4d46cd7]
to [c4760bdd91].





1
2
3
4
5
6
7
8
9
10

11
12
13
14
15
16
17

1
2
3
4
5
6
7



8
9
10
11
12
13
14
15








-
-
-
+








<!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;matt@novadigm.com&gt;">
<meta name="Copyright" content="1999 Matt Newman.">
<meta name="Copyright" content="1999 Matt Newman / 2004 Starfish Systems">
<title>TLS (SSL) Tcl Commands</title>
</head>

<body bgcolor="#FFFFFF">

<dl>
    <dd><a href="#NAME">NAME</a> <dl>




︙


112
113
114
115
116
117
118
119
120


121
122
123
124
125
126
127

110
111
112
113
114
115
116


117
118
119
120
121
122
123
124
125








-
-
+
+








    <dd>Forces handshake to take place, and returns 0 if
        handshake is still in progress (non-blocking), or 1 if
        the handshake was successful. If the handshake failed
        this routine will throw an error.</dd>
    <dt>&nbsp;</dt>
    <dt><a name="tls::status"><strong>tls::status</strong>
    <em>?-local? channel</em></a></dt>
    <dd>Returns the current security status of a SSL channel. The
        result is a list of key value pairs describing the
    <dd>Returns the current security status of an SSL channel. The
        result is a list of key-value pairs describing the
        connected peer. If the result is an empty list then the
        SSL handshake has not yet completed.
        If <em>-local</em> is given, then the certificate information
        is the one used locally.</dd>
</dl>

<blockquote>




︙


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

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








-
+








-
+





-
-










-
+

-
+
+








    <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>
        <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>
        <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>
        <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.
            to obtain a password, typically to unlock the private key of
	    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.




︙


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
273
274

275

276
277
278
279
280
281
282

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
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336





337
338
339
340
341
342

343
344
345
346
347
348
349
350
351

352

353
354
355





356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386

387
388
389
390
391
392
393
394








+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

-
-
-
-
-
+
+
+
+
+
+
-









-
+
-



-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+










+
-
+








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

<blockquote>
<dl>

    <dt><strong>-command</strong> <em>callback</em></dt>
    <dd>
	Invokes the specified <em>callback</em> script at
	several points during the OpenSSL handshake.
	Except as indicated below, values returned from the
	callback are ignored.
	Arguments appended to the script upon callback take one of the
	following forms:

	<br>
	<br>

	<dl>

<!--	This form of callback is disabled.

	<dt>
	  <strong>error</strong> <em>channel message</em>
	</dt>
	<dd>
	  The <em>message</em> argument contains an error message generated
	  by the OpenSSL function
	  <code>ERR_reason_error_string()</code>.
	</dd>

	<br>
-->

	<dt>
	  <strong>info</strong> <em>channel major minor message</em>
	</dt>
	<dd>
	  This form of callback is invoked by the OpenSSL function
	  <code>SSL_CTX_set_info_callback()</code>.
	  <br>
	  The <em>major</em> and <em>minor</em> arguments are used to
	  represent the state information bitmask.
	  <dl>
	  <dt>Possible values for <em>major</em> are:</dt>
	  <dd><code>handshake, alert, connect, accept</code>.</dd>
	  <dt>Possible values for <em>minor</em> are:</dt>
	  <dd><code>start, done, read, write, loop, exit</code>.</dd>
	  </dl>
	  The <em>message</em> argument is a descriptive string which may
	  be generated either by
	  <code>SSL_state_string_long()</code> or by
	  <code>SSL_alert_desc_string_long()</code>,
	  depending on context.
	</dd>

	<br>

	<dt>
	  <strong>verify</strong> <em>channel depth cert status error</em>
	</dt>
	<dd>
	  This form of callback is invoked by the OpenSSL function
	  <code>SSL_set_verify()</code>.
	  <br>
	  The <em>depth</em> argument is an integer representing the
	  current depth on the certificate chain, with
	  <code>0</code> as the subject certificate and higher values
	  denoting progressively more indirect issuer certificates.
	  <br>
	  The <em>cert</em> argument is a list of key-value pairs similar
	  to those returned by
	  <a href="#tls::status"><strong>tls::status</strong></a>.
	  <br>
	  The <em>status</em> argument is an integer representing the
	  current validity of the certificate.
	  A value of <code>0</code> means the certificate is deemed invalid.
	  A value of <code>1</code> means the certificate is deemed valid.
	  <br>
	  The <em>error</em> argument supplies the message, if any, generated
	  by
	  <code>X509_STORE_CTX_get_error()</code>.
	  <br>
	  <br>
	  The callback may override normal validation processing by explicitly
	  returning one of the above <em>status</em> values.
	</dd>

	</dl>
    </dd>

    <br>

    <dt><strong>-password</strong> <em>callback</em></dt>
    <dd>
	Invokes the specified <em>callback</em> script when OpenSSL needs to
	obtain a password.  The callback should return a string which
	represents the password to be used.
	No arguments are appended to the script upon callback.
    </dd>
</dl>
</blockquote>

<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
Reference implementations of these callbacks are provided in the
distribution as <strong>tls::callback</strong> and
<strong>tls::password</strong> respectively.  Note that these are
<em>sample</em> implementations only.  In a more realistic deployment
you would specify your own callback scripts on each TLS channel
using the <em>-command</em> and <em>-password</em> options.
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
compatibility with earlier implementations.
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.
The <strong>tls::debug</strong> variable provides some additional
control over these reference callbacks.  Its value is zero by default.
Higher values produce more diagnostic output, and will also force the
verify method in <strong>tls::callback</strong> to accept the
certificate, even when it is invalid.
</p>

<p>
<em>
The use of the reference callbacks <strong>tls::callback</strong> and
<strong>tls::password</strong> is not recommended.  They may be removed
from future releases.
</em>
</p>

<p>
<em>
The use of the variable <strong>tls::debug</strong> is not recommended.
It may be removed from future releases.
</em>
</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,
courtesy of the <strong>OpenSSL</strong> project.</p>

<pre><code>
<pre><code>package require http
package require http
package require tls

http::register https 443 [list ::tls::socket -require 1 -cafile ./server.pem]

set tok [http::geturl https://developer.netscape.com/]
</code></pre>





︙


300
301
302
303
304
305
306

307
308
309

412
413
414
415
416
417
418
419
420
421
422








+




<p><strong>socket</strong>, <strong>fileevent, </strong><a
href="http://www.openssl.org/"><strong>OpenSSL</strong></a></p>

<hr>

<pre>
Copyright &copy; 1999 Matt Newman.
Copyright &copy; 2004 Starfish Systems.
</pre>
</body>
</html>















Powered by Fossil · RSS