Artifacts Associated With Ticket 56d19eb033715cd05fbb7a09261e8a0f29a7f1c3

1. Ticket change [a5df46dc0c] (rid 1523) by anonymous on 2020-08-20 22:25:53:

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

      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. login: "anonymous"
   4. mimetype: "text/x-fossil-plain"
   5. private_contact initialized to: "c47142f6219c164377efd7f92c5d3dfe2a13b4cf"
   6. severity initialized to: "Important"
   7. status initialized to: "Open"
   8. title initialized to: ""https example" section is confusing"
   9. type initialized to: "Documentation"