Ticket Change Details
Overview

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

  1. foundin changed 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 changed to: "c47142f6219c164377efd7f92c5d3dfe2a13b4cf"
  6. severity changed to: "Important"
  7. status changed to: "Open"
  8. title changed to: ""https example" section is confusing"
  9. type changed to: "Documentation"