View Ticket
Ticket Hash: 56d19eb033715cd05fbb7a09261e8a0f29a7f1c3
Title: "https example" section is confusing
Status: Open Type: Documentation
Severity: Important Priority:
Subsystem: Resolution:
Last Modified: 2020-08-20 22:25:53
Version Found In: 1.7.21
User Comments:
anonymous added on 2020-08-20 22:25:53: (text/x-fossil-plain)
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.