diff options
| author | William Joye <wjoye@cfa.harvard.edu> | 2019-01-02 21:11:07 (GMT) |
|---|---|---|
| committer | William Joye <wjoye@cfa.harvard.edu> | 2019-01-02 21:11:07 (GMT) |
| commit | a2f632142c20caf1b58cf26cbcc10e8ab598fc92 (patch) | |
| tree | 345caa9e72dec72fdca32aecbe8df5f51348d4b1 /tls/tls.htm | |
| parent | 38372df5fe93ad7eda2915ca1f5335d03a04af5d (diff) | |
| download | blt-a2f632142c20caf1b58cf26cbcc10e8ab598fc92.zip blt-a2f632142c20caf1b58cf26cbcc10e8ab598fc92.tar.gz blt-a2f632142c20caf1b58cf26cbcc10e8ab598fc92.tar.bz2 | |
update TEA 3.13
Diffstat (limited to 'tls/tls.htm')
| -rw-r--r-- | tls/tls.htm | 432 |
1 files changed, 0 insertions, 432 deletions
diff --git a/tls/tls.htm b/tls/tls.htm deleted file mode 100644 index ab47d4d..0000000 --- a/tls/tls.htm +++ /dev/null @@ -1,432 +0,0 @@ -<!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="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> - <dd><strong>tls</strong> - binding to <strong>OpenSSL</strong> - toolkit.</dd> - </dl> - </dd> - <dd><a href="#SYNOPSIS">SYNOPSIS</a> </dd> - <dd><dl> - <dd><b>package require Tcl </b><em>?8.4?</em></dd> - <dd><b>package require tls </b><em>?1.6?</em></dd> - <dt> </dt> - <dd><b>tls::init </b><i>?options?</i> </dd> - <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::unimport</b><em> channel</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> - -<h3><a name="NAME">NAME</a></h3> - -<p><strong>tls</strong> - binding to <strong>OpenSSL</strong> -toolkit.</p> - -<h3><a name="SYNOPSIS">SYNOPSIS</a></h3> - -<p><b>package require Tcl 8.4</b><br> -<b>package require tls 1.6</b><br> -<br> -<a href="#tls::init"><b>tls::init </b><i>?options?</i><br> -</a><a href="#tls::socket"><b>tls::socket </b><em>?options? host -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::unimport"><b>tls::unimport </b><i>channel</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 -as channels created using Tcl's built-in <strong>socket</strong> -command with additional options for controlling the SSL session. -To use TLS with an earlier version of Tcl than 8.4, please obtain -TLS 1.3. -</p> - -<h3><a name="COMMANDS">COMMANDS</a></h3> - -<p>Typically one would use the <strong>tls::socket </strong>command -which provides compatibility with the native Tcl <strong>socket</strong> -command. In such cases <strong>tls::import</strong> should not be -used directly.</p> - -<dl> - <dt><a name="tls::init"><b>tls::init </b><i>?options?</i></a></dt> - <dd>This routine sets the default options used by <strong>tls::socket</strong> - and is <em>optional</em>. If you call <strong>tls::import</strong> - directly this routine has no effect. Any of the options - that <strong>tls::socket</strong> accepts can be set - using this command, though you should limit your options - to only TLS related ones.</dd> - <dt> </dt> - <dt><a name="tls::socket"><b>tls::socket </b><em>?options? - host port</em></a></dt> - <dt><b>tls::socket</b><em> ?-server command? ?options? port</em></dt> - <dd>This is a helper function that utilizes the underlying - commands (<strong>tls::import</strong>). It behaves - exactly the same as the native Tcl <strong>socket</strong> - command except that the options can include any of the - applicable <a href="#tls::import"><strong>tls:import</strong></a> - options.</dd> - <dt> </dt> - <dt><a name="tls::handshake"><strong>tls::handshake</strong> <em>channel</em></a></dt> - <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> </dt> - <dt><a name="tls::status"><strong>tls::status</strong> - <em>?-local? channel</em></a></dt> - <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> - <dl> - <dt><strong>issuer</strong> <em>dn</em></dt> - <dd>The distinguished name (DN) of the certificate - issuer.</dd> - <dt><strong>subject</strong> <em>dn</em></dt> - <dd>The distinguished name (DN) of the certificate - subject.</dd> - <dt><strong>notBefore</strong> <em>date</em></dt> - <dd>The begin date for the validity of the certificate.</dd> - <dt><strong>notAfter</strong> <em>date</em></dt> - <dd>The expiry date for the certificate.</dd> - <dt><strong>serial</strong> <em>n</em></dt> - <dd>The serial number of the certificate.</dd> - <dt><strong>cipher</strong> <em>cipher</em></dt> - <dd>The current cipher in use between the client and - server channels.</dd> - <dt><strong>sbits</strong> <em>n</em></dt> - <dd>The number of bits used for the session key.</dd> - </dl> -</blockquote> - -<dl> - <dt><a name="tls::import"><b>tls::import </b><i>channel - ?options?</i></a></dt> - <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. - <br> - See <a href="#CALLBACK OPTIONS">CALLBACK OPTIONS</a> for - further discussion.</dd> - <dt><strong>-dhparams </strong><em>filename</em></dt> - <dd>Provide a Diffie-Hellman parameters file.</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 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. - (<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>-servername</strong> <em>host</em></dt> - <dd>Only available if the OpenSSL library the package is linked - against supports the TLS hostname extension for 'Server Name - Indication' (SNI). Use to name the logical host we are talking - to and expecting a certificate for</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> - </dl> -</blockquote> - -<dl> - <dt><a name="tls::unimport"><b>tls::unimport </b><i>channel</i></a></dt> - <dd>Provided for symmetry to <strong>tls::import</strong>, this - unstacks the SSL-enabling of a regular Tcl channel. An error - is thrown if TLS is not the top stacked channel type.</dd> -</dl> - -<dl> - <dt><a name="tls::ciphers protocol ?verbose?"><strong>tls::ciphers</strong> - <em>protocol ?verbose?</em></a></dt> - <dd>Returns list of supported ciphers based on the <em>protocol</em> - 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> - -<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> 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. -</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. -</p> - -<p> -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 uses a sample server.pem provided with the TLS release, -courtesy of the <strong>OpenSSL</strong> project.</p> - -<pre><code> -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> - -<h3><a name="SPECIAL CONSIDERATIONS">SPECIAL CONSIDERATIONS</a></h3> - -<p>The capabilities of this package can vary enormously based -upon how your OpenSSL library was configured and built. At the -most macro-level OpenSSL supports a "no patents" build, -which disables RSA, IDEA, RC(2,4,5) and SSL2 - if your OpenSSL is -configured this way then you will need to build TLS with the --DNO_PATENTS option - and the resultant module will function -correctly and also support ADH certificate-less encryption, -however you will be unable to utilize this to speak to normal Web -Servers, which typically require RSA support. Please see <a -href="http://www.openssl.org/">http://www.openssl.org/</a> for -more information on the whole issue of patents and US export -restrictions. </p> - -<h3><a name="SEE ALSO">SEE ALSO</a></h3> - -<p><strong>socket</strong>, <strong>fileevent, </strong><a -href="http://www.openssl.org/"><strong>OpenSSL</strong></a></p> - -<hr> - -<pre> -Copyright © 1999 Matt Newman. -Copyright © 2004 Starfish Systems. -</pre> -</body> -</html> |