<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::connection </b> <em>channel</em></dd>
            <dd><b>tls::import</b> <em>channel ?options?</em></dd>
            <dd><b>tls::unimport</b> <em>channel</em></dd>
            <dt>&nbsp;</dt>
            <dd><b>tls::ciphers </b> <em>protocol ?verbose?</em></dd>
            <dd><b>tls::ciphers </b> <em>protocol ?verbose? ?supported?</em></dd>
            <dd><b>tls::protocols</b></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>

<a href="#tls::socket"><b>tls::socket</b> <i>?-server command? ?options? port</i></a><br>
<a href="#tls::status"><b>tls::status</b> <i>?-local? channel</i></a><br>
<a href="#tls::connection"><b>tls::connection</b> <i>channel</i></a><br>
<a href="#tls::handshake"><b>tls::handshake</b> <i>channel</i></a><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>
<br>
<a href="#tls::ciphers"><b>tls::ciphers</b> <i>protocol ?verbose?</i></a><br>
<a href="#tls::ciphers"><b>tls::ciphers</b> <i>protocol ?verbose? ?supported?</i></a><br>
<a href="#tls::protocols"><b>tls::protocols</b></a>
<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

        <dd>Specify the filename containing the certificate to use. The
	    default name is <b>cert.pem</b>. This can be overridden via
	    the <b>SSL_CERT_FILE</b> environment variable.</dd>
        <dt><strong>-cert</strong> <em>filename</em></dt>
        <dd>Specify the contents of a certificate to use, as a DER
	    encoded binary value (X.509 DER).</dd>
        <dt><strong>-cipher</strong> <em>string</em></dt>
        <dd>List of ciphers to use. String is a colon (":") separated list
	    of ciphers or cipher suites. Cipher suites can be combined
	    using the <b>+</b> character. Prefixes can be used to permanently
	    remove ("!"), delete ("-"), or move a cypher to the end of
	    the list ("+"). Keywords <b>@STRENGTH</b> (sort by algorithm
	    key length), <b>@SECLEVEL=</b><i>n</i> (set security level to
	    n), and <b>DEFAULT</b> (use default cipher list, at start only)
        <dd>List of ciphers to use. See OpenSSL documentation for the full
	    list of valid values.</dd>
	    can also be specified. See OpenSSL documentation for the full
	    list of valid values. (TLS 1.2 and earlier only)</dd>
        <dt><strong>-command</strong> <em>callback</em></dt>
        <dd>Callback to invoke at several points during the handshake.
	    This is used to pass errors and tracing information, and
	    it can allow Tcl scripts to perform their own certificate
	    validation in place of the default validation provided by
	    OpenSSL. See <a href="#CALLBACK OPTIONS">CALLBACK OPTIONS</a>
	    for further discussion.</dd>

	    Negotiation (ALPN).</dd>
        <dt><strong>session_reused</strong> <em>boolean</em></dt>
        <dd>Whether the session has been reused or not.</dd>
    </dl>
</blockquote>

    <dt><a name="tls::ciphers"><strong>tls::ciphers</strong> 
    <em>protocol ?verbose?</em></a></dt>
    <em>protocol ?verbose? ?supported?</em></a></dt>
    <dd>Returns a list of supported ciphers available for <em>protocol</em>,
        where protocol must be one of <b>ssl2, ssl3, tls1, tls1.1,
	tls1.2,</b> or <b>tls1.3</b>. If <em>verbose</em> is specified as
	true then a verbose, human readable list is returned with
	additional information on the cipher.</dd>
	additional information on the cipher. If <em>supported</em>
	is specified as true, then only the ciphers supported for protocol
	will be listed.</dd>

    <dt><a name="tls::protocols"><strong>tls::protocols</strong></a></dt>
    <dd>Returns a list of supported protocols. Valid values are:
	<b>ssl2</b>, <b>ssl3</b>, <b>tls1</b>, <b>tls1.1</b>, <b>tls1.2</b>,
	and <b>tls1.3</b>.</dd>

    <dt><a name="tls::version"><strong>tls::version</strong></a></dt>

};
enum protocol {
    TLS_SSL2, TLS_SSL3, TLS_TLS1, TLS_TLS1_1, TLS_TLS1_2, TLS_TLS1_3, TLS_NONE
};

static int
CiphersObjCmd(ClientData clientData, Tcl_Interp *interp, int objc, Tcl_Obj *const objv[]) {
    Tcl_Obj *objPtr;
    Tcl_Obj *objPtr = NULL;
    SSL_CTX *ctx = NULL;
    SSL *ssl = NULL;
    STACK_OF(SSL_CIPHER) *sk;
    char *cp, buf[BUFSIZ];
    int index, verbose = 0;
    int index, verbose = 0, use_supported = 0;

    dprintf("Called");

    if ((objc < 2) || (objc > 3)) {
	Tcl_WrongNumArgs(interp, 1, objv, "protocol ?verbose?");
    if ((objc < 2) || (objc > 4)) {
	Tcl_WrongNumArgs(interp, 1, objv, "protocol ?verbose? ?supported?");
	return TCL_ERROR;
    }
    if (Tcl_GetIndexFromObj(interp, objv[1], protocols, "protocol", 0, &index) != TCL_OK) {
	return TCL_ERROR;
    }
    if ((objc > 2) && Tcl_GetBooleanFromObj(interp, objv[2], &verbose) != TCL_OK) {
	return TCL_ERROR;
    }
    if ((objc > 3) && Tcl_GetBooleanFromObj(interp, objv[3], &use_supported) != TCL_OK) {
	return TCL_ERROR;
    }

    switch ((enum protocol)index) {
	case TLS_SSL2:
#if OPENSSL_VERSION_NUMBER >= 0x10101000L || defined(NO_SSL2) || defined(OPENSSL_NO_SSL2)
#if OPENSSL_VERSION_NUMBER >= 0x10100000L || defined(NO_SSL2) || defined(OPENSSL_NO_SSL2)
	    Tcl_AppendResult(interp, protocols[index], ": protocol not supported", NULL);
	    return TCL_ERROR;
#else
	    ctx = SSL_CTX_new(SSLv2_method()); break;
#endif
	case TLS_SSL3:
#if defined(NO_SSL3) || defined(OPENSSL_NO_SSL3)

	default:
	    break;
    }
    if (ctx == NULL) {
	Tcl_AppendResult(interp, REASON(), NULL);
	return TCL_ERROR;
    }

    ssl = SSL_new(ctx);
    if (ssl == NULL) {
	Tcl_AppendResult(interp, REASON(), NULL);
	SSL_CTX_free(ctx);
	return TCL_ERROR;
    }
    objPtr = Tcl_NewListObj(0, NULL);

    if (!verbose) {
	for (index = 0; ; index++) {
	    cp = (char*)SSL_get_cipher_list(ssl, index);
	    if (cp == NULL) break;
	    Tcl_ListObjAppendElement(interp, objPtr, Tcl_NewStringObj(cp, -1));
	}
    } else {
	sk = SSL_get_ciphers(ssl);

    /* Use list and order as would be sent in a ClientHello or all available ciphers */
    if (use_supported) {
	sk = SSL_get1_supported_ciphers(ssl);
    } else {
	sk = SSL_get_ciphers(ssl);
    }

    if (sk != NULL) {
	if (!verbose) {
	    objPtr = Tcl_NewListObj(0, NULL);
	    for (int i = 0; i < sk_SSL_CIPHER_num(sk); i++) {
		const SSL_CIPHER *c = sk_SSL_CIPHER_value(sk, i);
		if (c == NULL) continue;

		/* cipher name or (NONE) */
		cp = SSL_CIPHER_get_name(c);
		if (cp == NULL) break;
		Tcl_ListObjAppendElement(interp, objPtr, Tcl_NewStringObj(cp, -1));
	    }

	} else {
	    objPtr = Tcl_NewStringObj("",0);
	    for (int i = 0; i < sk_SSL_CIPHER_num(sk); i++) {
		const SSL_CIPHER *c = sk_SSL_CIPHER_value(sk, i);
		if (c == NULL) continue;

	for (index = 0; index < sk_SSL_CIPHER_num(sk); index++) {
	    register size_t i;
	    SSL_CIPHER_description(sk_SSL_CIPHER_value(sk, index), buf, sizeof(buf));
	    for (i = strlen(buf) - 1; i ; i--) {
		/* textual description of the cipher */
		if (SSL_CIPHER_description(c, buf, sizeof(buf)) != NULL) {
		    Tcl_AppendToObj(objPtr, buf, strlen(buf));
		if ((buf[i] == ' ') || (buf[i] == '\n') || (buf[i] == '\r') || (buf[i] == '\t')) {
		    buf[i] = '\0';
		} else {
		    break;
		    Tcl_AppendToObj(objPtr, "UNKNOWN\n", 8);
		}
	    }
	    Tcl_ListObjAppendElement(interp, objPtr, Tcl_NewStringObj(buf, -1));
	}
	if (use_supported) {
	    sk_SSL_CIPHER_free(sk);
	}
    }
    SSL_free(ssl);
    SSL_CTX_free(ctx);

    Tcl_SetObjResult(interp, objPtr);
    return TCL_OK;

    if (objc != 1) {
	Tcl_WrongNumArgs(interp, 1, objv, "");
	return TCL_ERROR;
    }

    objPtr = Tcl_NewListObj(0, NULL);

#if OPENSSL_VERSION_NUMBER < 0x10101000L && !defined(NO_SSL2) && !defined(OPENSSL_NO_SSL2)
#if OPENSSL_VERSION_NUMBER < 0x10100000L && !defined(NO_SSL2) && !defined(OPENSSL_NO_SSL2)
    Tcl_ListObjAppendElement(interp, objPtr, Tcl_NewStringObj(protocols[TLS_SSL2], -1));
#endif
#if !defined(NO_SSL3) && !defined(OPENSSL_NO_SSL3)
    Tcl_ListObjAppendElement(interp, objPtr, Tcl_NewStringObj(protocols[TLS_SSL3], -1));
#endif
#if !defined(NO_TLS1) && !defined(OPENSSL_NO_TLS1)
    Tcl_ListObjAppendElement(interp, objPtr, Tcl_NewStringObj(protocols[TLS_TLS1], -1));

            Tls_Free((char *) statePtr);
            return TCL_ERROR;
        }
    }
    if (alpn) {
	/* Convert a Tcl list into a protocol-list in wire-format */
	unsigned char *protos, *p;
	unsigned int protoslen = 0;
	unsigned int protos_len = 0;
	int i, len, cnt;
	Tcl_Obj **list;
	if (Tcl_ListObjGetElements(interp, alpn, &cnt, &list) != TCL_OK) {
	    Tls_Free((char *) statePtr);
	    return TCL_ERROR;
	}
	/* Determine the memory required for the protocol-list */
	for (i = 0; i < cnt; i++) {
	    Tcl_GetStringFromObj(list[i], &len);
	    if (len > 255) {
		Tcl_AppendResult(interp, "alpn protocol name too long", (char *) NULL);
		Tls_Free((char *) statePtr);
		return TCL_ERROR;
	    }
	    protoslen += 1 + len;
	    protos_len += 1 + len;
	}
	/* Build the complete protocol-list */
	protos = ckalloc(protoslen);
	protos = ckalloc(protos_len);
	/* protocol-lists consist of 8-bit length-prefixed, byte strings */
	for (i = 0, p = protos; i < cnt; i++) {
	    char *str = Tcl_GetStringFromObj(list[i], &len);
	    *p++ = len;
	    memcpy(p, str, len);
	    p += len;
	}
	/* Note: This functions reverses the return value convention */
	if (SSL_set_alpn_protos(statePtr->ssl, protos, protoslen)) {
	if (SSL_set_alpn_protos(statePtr->ssl, protos, protos_len)) {
	    Tcl_AppendResult(interp, "failed to set alpn protocols", (char *) NULL);
	    Tls_Free((char *) statePtr);
	    ckfree(protos);
	    return TCL_ERROR;
	}
	/* SSL_set_alpn_protos makes a copy of the protocol-list */
	ckfree(protos);

# Commands covered:  tls::ciphers
#
# This file contains a collection of tests for one or more of the Tcl
# built-in commands.  Sourcing this file into Tcl runs the tests and
# generates output for errors.  No output means no errors were found.
#

# Auto generated test cases for ciphers_and_protocols.csv
# All rights reserved.
#

# See the file "license.terms" for information on usage and redistribution
# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
#

# Load Tcl Test package
if {[lsearch [namespace children] ::tcltest] == -1} {
    package require tcltest
    namespace import ::tcltest::*
	package require tcltest
	namespace import ::tcltest::*
}

set auto_path [concat [list [file dirname [file dirname [info script]]]] $auto_path]
# The build dir is added as the first element of $PATH

package require tls

# One of these should == 1, depending on what type of ssl library
# tls was compiled against. (RSA BSAFE SSL-C or OpenSSL).
#
set ::tcltest::testConstraints(rsabsafe) 0
set ::tcltest::testConstraints(openssl) [string match "OpenSSL*" [tls::version]]
# Make sure path includes location of OpenSSL executable
if {[info exists ::env(OPENSSL)]} {set ::env(path) [string cat [file join $::env(OPENSSL) bin] ";" $::env(path)}

# Constraints
set protocols [list ssl2 ssl3 tls1 tls1.1 tls1.2 tls1.3]
foreach protocol $protocols {::tcltest::testConstraint $protocol 0}
foreach protocol [::tls::protocols] {::tcltest::testConstraint $protocol 1}
::tcltest::testConstraint OpenSSL [string match "OpenSSL*" [::tls::version]]
# Helper functions
proc lcompare {list1 list2} {set m "";set u "";foreach i $list1 {if {$i ni $list2} {lappend m $i}};foreach i $list2 {if {$i ni $list1} {lappend u $i}};return [list "missing" $m "unexpected" $u]}
proc exec_get {delim args} {return [split [exec openssl {*}$args] $delim]}
# Test protocols

set ::EXPECTEDCIPHERS(rsabsafe) {

    EDH-DSS-RC4-SHA
    EDH-RSA-DES-CBC3-SHA
    EDH-DSS-DES-CBC3-SHA
    DES-CBC3-SHA
    RC4-SHA
    RC4-MD5
    EDH-RSA-DES-CBC-SHA
    EDH-DSS-DES-CBC-SHA
test Protocols-1.1 {All} -body {
    DES-CBC-SHA
    EXP-EDH-DSS-DES-56-SHA
    EXP-EDH-DSS-RC4-56-SHA
	lcompare $protocols [::tls::protocols]
    } -result {missing {ssl2 ssl3} unexpected {}}
# Test ciphers

    EXP-DES-56-SHA
    EXP-RC4-56-SHA
    EXP-EDH-RSA-DES-CBC-SHA
    EXP-EDH-DSS-DES-CBC-SHA
    EXP-DES-CBC-SHA
    EXP-RC2-CBC-MD5
    EXP-RC4-MD5
}

test CiphersAll-2.1 {SSL2} -constraints {ssl2} -body {
	lcompare [exec_get ":" ciphers -ssl2] [::tls::ciphers ssl2]
    } -result {missing {} unexpected {}}

set ::EXPECTEDCIPHERS(openssl) {
    AES128-SHA
    AES256-SHA
    DES-CBC-SHA
    DES-CBC3-SHA
    DHE-DSS-AES128-SHA
    DHE-DSS-AES256-SHA
    DHE-DSS-RC4-SHA
    DHE-RSA-AES128-SHA
    DHE-RSA-AES256-SHA
    EDH-DSS-DES-CBC-SHA
    EDH-DSS-DES-CBC3-SHA
    EDH-RSA-DES-CBC-SHA
    EDH-RSA-DES-CBC3-SHA
    EXP-DES-CBC-SHA
    EXP-EDH-DSS-DES-CBC-SHA
    EXP-EDH-RSA-DES-CBC-SHA
    EXP-RC2-CBC-MD5
    EXP-RC4-MD5
    EXP1024-DES-CBC-SHA
    EXP1024-DHE-DSS-DES-CBC-SHA
    EXP1024-DHE-DSS-RC4-SHA
    EXP1024-RC2-CBC-MD5
test CiphersAll-2.2 {SSL3} -constraints {ssl3} -body {
	lcompare [exec_get ":" ciphers -ssl3] [::tls::ciphers ssl3]
    } -result {missing {} unexpected {}}

test CiphersAll-2.3 {TLS1} -constraints {tls1} -body {
	lcompare [exec_get ":" ciphers -tls1] [::tls::ciphers tls1]
    } -result {missing {} unexpected {}}

test CiphersAll-2.4 {TLS1.1} -constraints {tls1.1} -body {
	lcompare [exec_get ":" ciphers -tls1_1] [::tls::ciphers tls1.1]
    } -result {missing {} unexpected {}}

test CiphersAll-2.5 {TLS1.2} -constraints {tls1.2} -body {
	lcompare [exec_get ":" ciphers -tls1_2] [::tls::ciphers tls1.2]
    } -result {missing {} unexpected {}}

test CiphersAll-2.6 {TLS1.3} -constraints {tls1.3} -body {
	lcompare [exec_get ":" ciphers -tls1_3] [::tls::ciphers tls1.3]
    } -result {missing {} unexpected {}}
# Test cipher descriptions

    EXP1024-RC4-MD5
    EXP1024-RC4-SHA
    IDEA-CBC-SHA
    RC4-MD5
    RC4-SHA
}

test CiphersDesc-3.1 {SSL2} -constraints {ssl2} -body {
	lcompare [exec_get "\r\n" ciphers -ssl2 -v] [split [string trim [::tls::ciphers ssl2 1]] \n]
    } -result {missing {} unexpected {}}

test CiphersDesc-3.2 {SSL3} -constraints {ssl3} -body {
set ::EXPECTEDCIPHERS(openssl0.9.8) {
    DHE-RSA-AES256-SHA
	lcompare [exec_get "\r\n" ciphers -ssl3 -v] [split [string trim [::tls::ciphers ssl3 1]] \n]
    } -result {missing {} unexpected {}}
    DHE-DSS-AES256-SHA
    AES256-SHA
    EDH-RSA-DES-CBC3-SHA
    EDH-DSS-DES-CBC3-SHA
    DES-CBC3-SHA
    DHE-RSA-AES128-SHA
    DHE-DSS-AES128-SHA
    AES128-SHA
    IDEA-CBC-SHA
    RC4-SHA
    RC4-MD5
    EDH-RSA-DES-CBC-SHA
    EDH-DSS-DES-CBC-SHA
    DES-CBC-SHA
    EXP-EDH-RSA-DES-CBC-SHA
    EXP-EDH-DSS-DES-CBC-SHA
    EXP-DES-CBC-SHA
    EXP-RC2-CBC-MD5
    EXP-RC4-MD5
}

test CiphersDesc-3.3 {TLS1} -constraints {tls1} -body {
	lcompare [exec_get "\r\n" ciphers -tls1 -v] [split [string trim [::tls::ciphers tls1 1]] \n]
    } -result {missing {} unexpected {}}

set version ""
if {[string match "OpenSSL*" [tls::version]]} {
test CiphersDesc-3.4 {TLS1.1} -constraints {tls1.1} -body {
	lcompare [exec_get "\r\n" ciphers -tls1_1 -v] [split [string trim [::tls::ciphers tls1.1 1]] \n]
   regexp {OpenSSL ([\d\.]+)} [tls::version] -> version
}
    } -result {missing {} unexpected {}}

if {![info exists ::EXPECTEDCIPHERS(openssl$version)]} {
    set version ""
}
test CiphersDesc-3.5 {TLS1.2} -constraints {tls1.2} -body {
	lcompare [exec_get "\r\n" ciphers -tls1_2 -v] [split [string trim [::tls::ciphers tls1.2 1]] \n]
    } -result {missing {} unexpected {}}

test CiphersDesc-3.6 {TLS1.3} -constraints {tls1.3} -body {
	lcompare [exec_get "\r\n" ciphers -tls1_3 -v] [split [string trim [::tls::ciphers tls1.3 1]] \n]
    } -result {missing {} unexpected {}}
# Test protocol specific ciphers

proc listcompare {wants haves} {
    array set want {}
    array set have {}
    foreach item $wants { set want($item) 1 }
    foreach item $haves { set have($item) 1 }
    foreach item [lsort -dictionary [array names have]] {
	if {[info exists want($item)]} {
	    unset want($item) have($item)
	}
    }

test CiphersSpecific-4.1 {SSL2} -constraints {ssl2} -body {
	lcompare [exec_get ":" ciphers -ssl2 -s] [::tls::ciphers ssl2 0 1]
    } -result {missing {} unexpected {}}

    if {[array size want] || [array size have]} {
	return [list MISSING [array names want] UNEXPECTED [array names have]]
    }
}

test CiphersSpecific-4.2 {SSL3} -constraints {ssl3} -body {
	lcompare [exec_get ":" ciphers -ssl3 -s] [::tls::ciphers ssl3 0 1]
    } -result {missing {} unexpected {}}

test CiphersSpecific-4.3 {TLS1} -constraints {tls1} -body {
	lcompare [exec_get ":" ciphers -tls1 -s] [::tls::ciphers tls1 0 1]
    } -result {missing {} unexpected {}}

test CiphersSpecific-4.4 {TLS1.1} -constraints {tls1.1} -body {
test ciphers-1.1 {Tls::ciphers for ssl3} {rsabsafe} {
    # This will fail if you compiled against OpenSSL.
    # Change the constraint setting above.
    listcompare $::EXPECTEDCIPHERS(rsabsafe) [tls::ciphers ssl3]
} {}
	lcompare [exec_get ":" ciphers -tls1_1 -s] [::tls::ciphers tls1.1 0 1]
    } -result {missing {} unexpected {}}

test ciphers-1.2 {Tls::ciphers for tls1} {rsabsafe} {
    # This will fail if you compiled against OpenSSL.
    # Change the constraint setting above.
    listcompare $::EXPECTEDCIPHERS(rsabsafe) [tls::ciphers tls1]
} {}
test CiphersSpecific-4.5 {TLS1.2} -constraints {tls1.2} -body {
	lcompare [exec_get ":" ciphers -tls1_2 -s] [::tls::ciphers tls1.2 0 1]
    } -result {missing {} unexpected {}}

test ciphers-1.3 {Tls::ciphers for ssl3} {openssl} {
    # This will fail if you compiled against RSA bsafe or with a
    # different set of defines than the default.
    # Change the constraint setting above.
    listcompare $::EXPECTEDCIPHERS(openssl$version) [tls::ciphers ssl3]
} {}
test CiphersSpecific-4.6 {TLS1.3} -constraints {tls1.3} -body {
	lcompare [exec_get ":" ciphers -tls1_3 -s] [::tls::ciphers tls1.3 0 1]
    } -result {missing {} unexpected {}}
# Test version

# This version of the test is correct for OpenSSL only.
# An equivalent test for the RSA BSAFE SSL-C is earlier in this file.

test ciphers-1.4 {Tls::ciphers for tls1} {openssl} {
test Version-5.1 {All} -body {
    # This will fail if you compiled against RSA bsafe or with a
    # different set of defines than the default.
    # Change the constraint setting in all.tcl
    listcompare $::EXPECTEDCIPHERS(openssl$version) [tls::ciphers tls1]
} {}
	::tls::version
    } -match {glob} -result {*}

test Version-5.2 {OpenSSL} -constraints {OpenSSL} -body {
	::tls::version
    } -match {glob} -result {OpenSSL*}

# cleanup
# Cleanup
::tcltest::cleanupTests
return