Ticket Change Details

Artifact ID: a5df46dc0c831e34d8eaa98d692c4e2f3caa232f7192917a2cf3412936f496b1
Ticket: 56d19eb033715cd05fbb7a09261e8a0f29a7f1c3
"https example" section is confusing
User & Date: anonymous 2020-08-20 22:25:53

  1. Change foundin to "1.7.21"
  2. Change icomment to:

    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 /usr/local/ssl/certs.

    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.

  3. Change login to "anonymous"
  4. Change mimetype to "text/x-fossil-plain"
  5. Change private_contact to "c47142f6219c164377efd7f92c5d3dfe2a13b4cf"
  6. Change severity to "Important"
  7. Change status to "Open"
  8. Change title to ""https example" section is confusing"
  9. Change type to "Documentation"