{"id":40736394,"url":"https://github.com/chpock/tclmtls","last_synced_at":"2026-01-21T15:01:20.150Z","repository":{"id":235852450,"uuid":"783343764","full_name":"chpock/tclmtls","owner":"chpock","description":"tclmtls package to provide SSL/TLS support in Tcl","archived":false,"fork":false,"pushed_at":"2025-02-23T11:03:43.000Z","size":925,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-23T12:18:42.146Z","etag":null,"topics":["mbedtls","tcl","tcl-extension","tls"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chpock.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog","contributing":null,"funding":null,"license":"license.terms","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-07T16:23:15.000Z","updated_at":"2025-02-23T11:03:47.000Z","dependencies_parsed_at":"2024-05-11T23:24:35.337Z","dependency_job_id":"42150775-0517-4518-bba0-fd27fb69bf0c","html_url":"https://github.com/chpock/tclmtls","commit_stats":null,"previous_names":["chpock/tclmtls"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/chpock/tclmtls","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chpock%2Ftclmtls","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chpock%2Ftclmtls/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chpock%2Ftclmtls/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chpock%2Ftclmtls/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chpock","download_url":"https://codeload.github.com/chpock/tclmtls/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chpock%2Ftclmtls/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28635122,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T14:50:40.221Z","status":"ssl_error","status_checked_at":"2026-01-21T14:48:59.225Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mbedtls","tcl","tcl-extension","tls"],"created_at":"2026-01-21T15:01:10.876Z","updated_at":"2026-01-21T15:01:20.130Z","avatar_url":"https://github.com/chpock.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# \u003ca name='Introduction'\u003e\u003c/a\u003eIntroduction\n\nThis Tcl package provides an extension which implements Transport\nLayer Security (TLS) over Transmission Control Protocol (TCP)\nnetwork communication channels.\n\n## \u003ca name='::Introduction-Why_'\u003e\u003c/a\u003eWhy?\n\nUsual Tcl package for SSL/TLS communication channels is\n[tcltls](https://core.tcl-lang.org/tcltls). But this package has\na number of disadvantages:\n\n- it uses OpenSSL/LibreSSL libraries. These libraries are huge (see [issue#11308](https://github.com/openssl/openssl/issues/11308)), contain a lot of obsolete and practically useless code/functions\n- no support for CA certificates provided by the operating system\n- unsafe default parameters\n\n\nThere are also alternatives, but they have their disadvantages:\n\n- Package [twapi](https://www.magicsplat.com/tcl-docs/twapi/tls.html): Windows platform only; comes as part of the entire twapi package (which is very cool, but also critically huge)\n- Package [TclCurl](https://github.com/flightaware/tclcurl-fa): depends on the even larger cURL library and therefore has both greater build complexity and size; support for client connections only\n\n\n[::mtls](README\\.html\\#::mtls) solves these disadvantages. It has the following features:\n\n- uses the [mbedTLS](https://github.com/Mbed-TLS/mbedtls) library with minimal size\n- interface is compatible with tcltls, most of the existing code will work as is, without modifications\n- uses CA certificates from the operating system on Linux/Windows/MacOS platforms\n- uses only modern TLS1.2/TLS1.3 protocols, which are more than sufficient for successful connections to most services\n- certificate and hostname verification, SNI are enabled by default\n- multi-platform, Linux/Windows/MacOS supported\n- possibility to exclude the client or server part to minimize the size even more\n- easy to build, no 3rd-party libraries, everything you need to build is in this repository\n- was created as a base for the use of SSL/TLS alternative backends\n\n\n## \u003ca name='::Introduction-Compatibility'\u003e\u003c/a\u003eCompatibility\n\nThis package requires Tcl 8.6 or later. However it has been tested\nwith Tcl 8.6.14 and 9.0b3.\n\n## \u003ca name='::Introduction-How_to_build'\u003e\u003c/a\u003eHow to build\n\nThis package uses the Tcl Extension Architecture (TEA) to build and\ninstall on Linux, Mac, or Windows platforms. For Windows platform only\nbuilding with Mingw-w64 toolchain is supported.\n\nThe standard TEA config, make and install process is supported.\n\n```\n$ git clone https://github.com/chpock/tclmtls.git\n$ cd tclmtls\n$ git submodule update --init --recursive\n$ mkdir build \u0026\u0026 cd build\n$ ../configure\n$ make\n$ make test\n$ make install\n```\n\nThe supported configure options include all of the standard TEA\nconfigure script options, plus:\n\n|||\n|----|----|\n|`--disable-client`|disable SSL client part|\n|`--disable-server`|disable SSL server part|\n\n\nBy default, mbedTLS will be built and used. It is possible to use\nan already built library, for this it is possible to specify\nthe following options:\n\n|||\n|----|----|\n|`--with-mbedtls=\u003cdir\u003e`|path to root directory of Mbed-TLS installation|\n|`--with-mbedtls-include=\u003cdir\u003e`|path to include directory of Mbed-TLS installation|\n|`--with-mbedtls-lib=\u003cdir\u003e`|path to lib directory of Mbed-TLS installation|\n\n\nOptions that can be used for development:\n\n|||\n|----|----|\n|`--enable-debug=\u003clevel\u003e`|enable debug messages. Possible levels are: `none`, `error`, `warning`, `info` or `on`|\n\n\n## \u003ca name='::Introduction-Usage'\u003e\u003c/a\u003eUsage\n\nSince this package intends to be compatible with the original\n[tcltls](https://core.tcl-lang.org/tcltls) package, the usual\n**tcltls** examples should be correct. You can see these examples on\nthe Tcl wiki: [https://wiki.tcl-lang.org/page/tls](https://wiki.tcl-lang.org/page/tls)\n\nMinimal examples are available below under [HTTPS examples](README\\.html\\#::mtls\\-HTTPS\\_examples).\n\n## \u003ca name='::Introduction-Built_packages_and_sources'\u003e\u003c/a\u003eBuilt packages and sources\n\nThe source code is available on [Github](https://github.com/chpock/tclmtls).\n\nBuilt packages are available on the above Github page, under\n[Releases](https://github.com/chpock/tclmtls/releases).\n\nThere are packages for the following platforms:\n\n- **Windows x86** and **x86\\_64**: Windows XP or higher is required. However, they are only tested on Windows 10.\n- **Linux x86** and **x86\\_64**: built and tested on Cenos6.10. Require glibc v2.12 or higher.\n- **MacOS x86** and **x86\\_64**: built and tested on MacOS 10.12. However, these packages should be compatible with MacOS as of version 10.6.\n\n\nRPM spec file for openSUSE is available on\n[https://build.opensuse.org/package/show/home:jkandz/tclmtls](https://build.opensuse.org/package/show/home:jkandz/tclmtls).\nBinary packages for openSUSE for various platforms are available on\n[openSUSE build service](https://software.opensuse.org//download.html?project=home%3Ajkandz\u0026package=tclmtls)\n\n## \u003ca name='::Introduction-Copyrights'\u003e\u003c/a\u003eCopyrights\n\nCopyright (C) 2024 Konstantin Kushnir \u003cchpock@gmail.com\u003e\n\n## \u003ca name='::Introduction-License'\u003e\u003c/a\u003eLicense\n\nThis code is licensed under the same terms as the Tcl Core.\n\nThis package contains [mbedTLS](https://github.com/Mbed-TLS/mbedtls)\nsources which are distributed under a dual [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)\nOR [GPL-2.0-or-later](https://spdx.org/licenses/GPL-2.0-or-later.html)\nlicense.\n\n# \u003ca name='::mtls'\u003e\u003c/a\u003e::mtls\n\n## \u003ca name='::mtls-Description'\u003e\u003c/a\u003eDescription\n\nThis Tcl package provides an extension which implements Transport\nLayer Security (TLS) over Transmission Control Protocol (TCP)\nnetwork communication channels.\n\nTypically one would use the [socket](README\\.html\\#::mtls::socket) command which provides\ncompatibility with the native Tcl [socket](https://www.tcl.tk/man/tcl8.6/TclCmd/socket.htm)\ncommand. In such cases [import](README\\.html\\#::mtls::import) should not be used directly.\n\nPlease note, to ensure seamless use of both the classic tcltls package\nand this package, command aliases are created in the `::tls` namespace\nwhen loading mtls. This allows the same code base to be used when using\ndifferent packages to support SSL/TLS connections. However, aliases\nwill not be created if the `::tls` namespace already exists at the time\nthe mtls package is loaded. This in turn allows both the tcltls and\nmtls packages to be loaded at the same time. But the tcltls package\nmust be loaded first.\n\n## \u003ca name='::mtls-HTTPS_examples'\u003e\u003c/a\u003eHTTPS examples\n\n### \u003ca name='::mtls-client_example'\u003e\u003c/a\u003eclient example\n\n```\npackage require http\npackage require mtls\n\nhttp::register https 443 ::mtls::socket\n\nset tok [http::geturl https://www.tcl.tk/]\n\n```\n\n### \u003ca name='::mtls-server_example'\u003e\u003c/a\u003eserver example\n\n```\npackage require mtls\n\nproc readable { sock } {\n    # do something\n}\n\nproc accept { sock addr port } {\n    fileevent $sock readable [list readable $sock]\n}\n\nmtls::socket -certfile $serverCert -keyfile $serverKey -server accept 8080\n\n```\n\n## \u003ca name='::mtls-Commands'\u003e\u003c/a\u003eCommands\n\n#### \u003ca name='::mtls::ciphers'\u003e\u003c/a\u003eciphers [[::mtls](README\\.html\\#::mtls)]\n\nGets a list of supported ciphers.\n\n\n\u003e `ciphers` *`protocol`*\u003cbr\u003e\n\n##### Parameters\n\n|||\n|----|----|\n|`protocol`|protocol for which a list of ciphers will be returned. Must be one of `tls1.2` or `tls1.3`.|\n\n\n##### Description\n\nFor compatibility with **tcltls**, this procedure can also accept\n`verbose` and `supported` arguments. However, they do not affect\nthe result and will be ignored.\n\n##### Return value\n\n A Tcl list of supported ciphers based on the specified\nprotocol.\n\n#### \u003ca name='::mtls::debug'\u003e\u003c/a\u003edebug [[::mtls](README\\.html\\#::mtls)]\n\nSets the level for debug messages\n\n\n\u003e `debug` *`?integer?`*\u003cbr\u003e\n\u003e `debug` *`?level? ?backend_level?`*\u003cbr\u003e\n\n##### Parameters\n\n|||\n|----|----|\n|`backend_level`|sets the desired level for TLS backend debug messages. The format is the same as for the `level` argument.|\n|`integer`|integer in this form will represent the debugging level for the packet and TLS backend messages. The first 3 bits refer to the packet layer and the next 3 bits refer to the TLS backend layer. The minimum level is `0`, which means no messages, and the maximum level is `5`, which corresponds to the `trace` level.|\n|`level`|sets the desired level for package debug messages, which must be one of `none`, `error`, `warning`, `info`, `debug`, `trace` or a number from `0` to `5`.|\n\n\n##### Description\n\nIf no arguments are specified, this command simply returns the current\nlevel.\n\nDebug messages will only work if the package was built with debugging\nsupport. Otherwise, this level will be ignored.\n\n##### Return value\n\n An unsigned integer corresponding to the current level\nfor both package and TLS backend debug messages.\n\n#### \u003ca name='::mtls::handshake'\u003e\u003c/a\u003ehandshake [[::mtls](README\\.html\\#::mtls)]\n\nForces handshake to take place\n\n\n\u003e `handshake` *`channel`*\u003cbr\u003e\n\n##### Parameters\n\n|||\n|----|----|\n|`channel`|TLS channel on which the handshake process should be started.|\n\n\n##### Return value\n\n `0` if handshake is still in progress (non-blocking), or `1` if\nthe handshake was successful. If the handshake failed this procedure\nwill throw an error.\n\n#### \u003ca name='::mtls::import'\u003e\u003c/a\u003eimport [[::mtls](README\\.html\\#::mtls)]\n\nAdds TLS layer for existing socket channel.\n\n\n\u003e `import` *`channel ?options?`*\u003cbr\u003e\n\n##### Parameters\n\n|||\n|----|----|\n|`channel`|A regular Tcl channel created wich Tcl [socket](https://www.tcl.tk/man/tcl8.6/TclCmd/socket.htm) command.|\n|`-cadir dir`|Provide the directory containing the CA certificates.|\n|`-cafile filename`|Provide the CA file.|\n|`-cert data`|Provide the contents of a certificate to use, as a PEM encoded or a binary DER encoded value (X.509 DER).|\n|`-certfile filename`|Provide the name of a file containing certificate to use.|\n|`-cipher list`|Provide the list of cipher suites to use.|\n|`-dhparams filename`|Provide a Diffie-Hellman parameters file.|\n|`-key data`|Provide the private key to use as a PEM encoded or a binary DER encoded value (X.509 DER).|\n|`-keyfile filename`|Provide the private key file. (default: value of `-certfile`)|\n|`-model channel`|This will force this channel to share the same parameters as the specified channel.|\n|`-password callback`|If supplied, this callback will be invoked to unlock the private key of a certificate. The callback should return a string which represents the password to be used.|\n|`-require bool`|Require a valid certificate from peer during TLS handshake. (default: `true` for client connections and `false` for server connections)|\n|`-server bool`|Handshake as server if true, else handshake as client. (default: `false`)|\n|`-servername host`|Use to name the logical host we are talking to and expecting a certificate for.|\n|`-tls1.2 bool`|Enable use of TLS v1.2 protocol (default: `true`)|\n|`-tls1.3 bool`|Enable use of TLS v1.3 protocol (default: `true`)|\n\n\n##### Description\n\nTLS-enables a regular Tcl channel and sets session parameters for\nTLS handshake.\n\nFor compatibility with **tcltls**, this procedure can also accept\n`-command callback`, `-request bool`, `-ssl2 bool`, `-ssl3 bool`,\n`-tls1 bool` and `-tls1.1 bool` arguments. However, they will be ignored.\n\n##### Return value\n\n The name of a TLS-enabled Tcl channel that can be used to send\nand receive data.\n\n#### \u003ca name='::mtls::init'\u003e\u003c/a\u003einit [[::mtls](README\\.html\\#::mtls)]\n\nSets the default settings for newly created TLS channels.\n\n\n\u003e `init` *`?options?`*\u003cbr\u003e\n\n##### Parameters\n\n|||\n|----|----|\n|`?options?`|options supported by the [import](README\\.html\\#::mtls::import) and [socket](README\\.html\\#::mtls::socket) commands.|\n\n\n##### Description\n\nSets the default settings for newly created TLS channels. The `-model`,\n`-server`, `-servername` options will be accepted but silently ignored.\n\n##### Return value\n\n The dict value with the currently defined default options.\n\n#### \u003ca name='::mtls::protocols'\u003e\u003c/a\u003eprotocols [[::mtls](README\\.html\\#::mtls)]\n\nGet a list of supported TLS protocols.\n\n\n\u003e `protocols` *``*\u003cbr\u003e\n\n##### Return value\n\n A Tcl list of supported TLS protocols.\n\n#### \u003ca name='::mtls::socket'\u003e\u003c/a\u003esocket [[::mtls](README\\.html\\#::mtls)]\n\nCreate a TLS socket channel.\n\n\n\u003e `socket` *`?options? host port`*\u003cbr\u003e\n\u003e `socket` *`?-server command? ?options? port`*\u003cbr\u003e\n\n##### Parameters\n\n|||\n|----|----|\n|`-autoservername bool`|Automatically set the `-servername` as the host argument (default: `true`)|\n|`options`|options accepted by the normal Tcl command [socket](https://www.tcl.tk/man/tcl8.6/TclCmd/socket.htm) and the [import](README\\.html\\#::mtls::import) command.|\n\n\n##### Description\n\nThis is a helper function for creating TLS-enabled channels. It behaves\nexactly the same as the native Tcl [socket](https://www.tcl.tk/man/tcl8.6/TclCmd/socket.htm)\ncommand, and accepts all of its options. In addition, it takes all\nparameters from the [import](README\\.html\\#::mtls::import) command to configure the newly created\nchannel.\n\nIt also accepts the option `-autoservername`. If set to `true`,\nthe value of the `-servername` option will be automatically detected\nfrom the specified connection parameters.\n\n##### Return value\n\n The name of a TLS-enabled Tcl channel that can be used to send\nand receive data.\n\n#### \u003ca name='::mtls::status'\u003e\u003c/a\u003estatus [[::mtls](README\\.html\\#::mtls)]\n\nGets the current security status of an TLS channel.\n\n\n\u003e `status` *`channel`*\u003cbr\u003e\n\n##### Parameters\n\n|||\n|----|----|\n|`channel`|TLS channel from which to obtain status|\n\n\n##### Description\n\nThe returned value will be a Tcl dictionary with the following keys:\n\n|||\n|----|----|\n|version|The protocol version used for the connection: `TLSv1.1`, `TLSv1.2`, `unknown`.|\n|cipher|The current cipher in use between the client and server.|\n|sbits|The number of bits used for the session key.|\n\n\nFor compatibility with **tcltls**, this procedure can also accept\n`-local` optional argument. However, it will be ignored.\n\n##### Return value\n\n The Tcl dict value with the current security status of\nthe TLS channel.\n\n#### \u003ca name='::mtls::unimport'\u003e\u003c/a\u003eunimport [[::mtls](README\\.html\\#::mtls)]\n\nUnstacks the TLS-enabling of a regular Tcl channel.\n\n\n\u003e `unimport` *`channel`*\u003cbr\u003e\n\n##### Parameters\n\n|||\n|----|----|\n|`channel`|TLS channel from which TLS layer is to be removed.|\n\n\n##### Description\n\nProvided for symmetry to [import](README\\.html\\#::mtls::import) command. This unstacks\nthe TLS-enabling of a regular Tcl channel.\n\n##### Return value\n\n nothing.\n\n#### \u003ca name='::mtls::version'\u003e\u003c/a\u003eversion [[::mtls](README\\.html\\#::mtls)]\n\nGet the type and version of the TLS backend in use.\n\n\n\u003e `version` *``*\u003cbr\u003e\n\n##### Return value\n\n A string with the type and version number of\nthe TLS backend used.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchpock%2Ftclmtls","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchpock%2Ftclmtls","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchpock%2Ftclmtls/lists"}