It is probably fair to say that the most common reason to start
using TclTLS is that one wants to "fetch a webpage" (or more
generally send HTTP requests to some server, perhaps as part of
some API), which used to be a straightforward application of the
http package, but nowadays web servers increasingly only wants to
do https. This means that section is a very important example!
AFAICT it moreover should just be a matter of giving the right
http::register command, pretty much as shown in that section,
but unfortunately several details seem to be wrong and/or confusing,
and definitely not satisfactory explained.
1. The first (indeed only) sentence in that section reads
"This example uses a sample server.pem provided with the TLS
release, courtesy of the OpenSSL project."
Presumably that refers to the file tests/certs/server.pem in the
TclTLS sources. That file is not used by the code following, and
indeed it would make no sense for it to be so used, since it
seems to be a certificate that would be needed by a server,
whereas this example is about being a HTTPS *client*.
2. The tls::socket command has the option -cadir /etc/ssl/certs
From what little experimentation I've been able to do, it seems
some explicit specification of the certificate authorities is
indeed necessary. That is in itself a bit odd, because from what
I've been able to gather, OpenSSL should be able to find its default
collection of root certificates itself, using SSL_CTX_set_default_verify_paths();
the counterparts of -cadir / -cafile in OpenSLL are more for when you
have your own CA for just this project.
Second, /etc/ssl/certs is not the canonical directory of root
certificates. It is the directory of root certificates in *one*
linux distro (I forget which one), but they pretty much all put that
directory in different locations.
The canonical directory is $OPENSSLDIR/certs, which defaults to
Third, the -cadir is rather awkward to start with, if you find
yourself in the position of actually needing to supply these
(which you will, in case you install openssl from source),
since the collections of root certificates one can download from
the internet (not included with OpenSSL itself) are instead in the
form of a -cafile. Populating the -cadir is not something one
undertakes manually, since the individual certificate files need to
be named according to their hashes for OpenSSL to find them. Finding
out about c_rehash is not all that easy when you're primarily a Tcler.
3. Indeed, there probably should be a section in the TclTLS manpage
giving a quick explanation of certificates and their role in TLS,
because that side of TLS is quite nonobvious to the user who has
primarily encountered TLS in the form of https in a web browser —
knowing that encrypted communication is useful is not so hard,
realising that you also want to be sure about the identity of the
server you're talking to takes a bit more insight.