<dt><strong>num_extensions</strong> <em>n</em></dt>
	<dd>Number of certificate extensions.</dd>
	<dt><strong>extensions</strong> <em>list</em></dt>
	<dd>List of certificate extension names.</dd>
	<dt><strong>authorityKeyIdentifier</strong> <em>string</em></dt>
	<dd>(AKI) Key identifier of the Issuing CA certificate that signed
	    the SSL certificate. This value matches the SKI value of the
	    Intermediate CA certificate.</dd>
	<dt><strong>subjectKeyIdentifier</strong> <em>string</em></dt>
	<dd>(SKI) Hash of the public key inside the certificate. Used to
	   identify certificates that contain a particular public key.</dd>

	<dt><strong>subjectAltName</strong> <em>list</em></dt>
	<dd>List of all of the alternative domain names, sub domains,
	    and IP addresses that are secured by the certificate.</dd>
	<dt><strong>ocsp</strong> <em>list</em></dt>
	<dd>List of all OCSP URLs.</dd>

	<dt><strong>certificate</strong> <em>cert</em></dt>
	<dd>The PEM encoded certificate.</dd>

	<dt><strong>signatureAlgorithm</strong> <em>algorithm</em></dt>
	<dd>Cipher algorithm used for certificate signature.</dd>
	<dt><strong>signatureValue</strong> <em>string</em></dt>

	<dt><strong>state</strong> <em>state</em></dt>
	<dd>State of the connection.</dd>
	<dt><strong>servername</strong> <em>name</em></dt>
	<dd>The name of the connected to server.</dd>
	<dt><strong>protocol</strong> <em>version</em></dt>
	<dd>The protocol version used for the connection:
	    SSL2, SSL3, TLS1, TLS1.1, TLS1.2, TLS1.3, or unknown.</dd>
	<dt><strong>renegotiation</strong> <em>state</em></dt>
	<dd>Whether protocol renegotiation is supported or not.</dd>
	<dt><strong>securitylevel</strong> <em>level</em></dt>
	<dd>The security level used for selection of ciphers, key size, etc.</dd>
	<dt><strong>session_reused</strong> <em>boolean</em></dt>
	<dd>Whether the session has been reused or not.</dd>
	<dt><strong>is_server</strong> <em>boolean</em></dt>
	<dd>Whether the connection configured as a server or client (false).</dd>
	<dt><strong>compression</strong> <em>mode</em></dt>
	<dd>Compression method.</dd>
	<dt><strong>expansion</strong> <em>mode</em></dt>
	<dd>Expansion method.</dd>
    </dl>
</blockquote>
<blockquote>

	<dd>Can the session be resumed or not.</dd>
	<dt><strong>start_time</strong> <em>seconds</em></dt>
	<dd>Time since session started in seconds since epoch.</dd>
	<dt><strong>timeout</strong> <em>seconds</em></dt>
	<dd>Max duration of session in seconds before time-out.</dd>
	<dt><strong>lifetime</strong> <em>seconds</em></dt>
	<dd>Session ticket lifetime hint in seconds.</dd>
	<dt><strong>session_id</strong> <em>string</em></dt>
	<dd>Unique session id for use in resuming the session.</dd>
	<dt><strong>session_ticket</strong> <em>string</em></dt>
	<dd>Unique session ticket for use in resuming the session.</dd>
	<dt><strong>ticket_app_data</strong> <em>string</em></dt>
	<dd>Unique session ticket application data.</dd>
	<dt><strong>master_key</strong> <em>binary_string</em></dt>
	<dd>Unique session master key.</dd>
	<dt><strong>session_cache_mode</strong> <em>mode</em></dt>
	<dd>Server cache mode (client, server, or both).</dd>
    </dl>
</blockquote>

</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>
	  This form of callback is invoked by the OpenSSL function
	  <code>SSL_CTX_sess_set_new_cb()</code>.
	  Where <em>session_id</em> is the current session identifier,
	  <em>ticket</em> is the session ticket info, and <em>lifetime</em>
	  is the the ticket lifetime in seconds.
	</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 the password as a string.
	No arguments are appended to the script upon callback.
    </dd>

    <br>


    <dt><strong>-validatecommand</strong> <em>callback</em></dt>
    <dd>
	Invokes the specified <em>callback</em> script during handshake in
	order to verify/validate the provided value. 
	To reject the value and abort connection, the callback should return 0.
	To accept the value, it should return 1.  To reject the value, but
	continue the connection, it should return 2.

	<br>
	<br>

	<dl>

	<dt>
	  <strong>alpn</strong> <em>protocol</em>
	</dt>
	<dd>
	  For servers, this form of callback is invoked when the client ALPN
	  header is received and the first <b>-alpn</b> specified protocol common
	  to the both the client and server is selected. If none, the first
	  client specified protocol is used.
	</dd>

	<br>

	<dt>
	  <strong>hello</strong> <em>servername</em>
	</dt>
	<dd>
	  For servers, this form of callback is invoked during client hello
	  message processing. Used to select an appropriate certificate to
	  present, and make other configuration adjustments relevant to that
	  server name and its configuration. Called before SNI and ALPN callbacks.
	</dd>

	<br>

	<dt>
	  <strong>sni</strong> <em>servername</em>
	</dt>
	<dd>
	  For servers, this form of callback is invoked when the SNI header
	  from the client is received. Where <i>servername</i> is the client
	  specified servername. This is used when a server supports multiple
	  names, so the right certificate can be used. Called after hello
	  callback but before ALPN callback.
	</dd>

	<br>

	<dt>

	  <li>The <em>status</em> argument is an boolean representing the
	  validity of the current 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.</li>
	  <li>The <em>error</em> argument supplies the message, if any, generated
	  by <code>X509_STORE_CTX_get_error()</code>.</li>
	  </ul>
	  <br>
	  <br>
	  The callback may override normal validation processing by explicitly
	  returning one of the above <em>status</em> values.
	</dd>
	<br>
	</dl>
    </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="DEBUG">DEBUG</a></h3>

TLS key logging can be enabled by setting the environment variable
<b>SSLKEYLOGFILE</b> to the name of the file to log to. Then whenever TLS
key material is generated or received it will be logged to the file.



<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 -autoservername true -require true -cadir /etc/ssl/certs]

set tok [http::geturl https://www.tcl.tk/]
</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 &quot;no patents&quot; 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>