README.md

   1 ### Simple HTTPS server
   2
   3 To use this server, first run `./n.sh` in the `ssl` subdirectory if you need
   4 to, this will generate a certificate for your SSL server. It has just been run
   5 and the results checked in at the time of writing, but the certificate will
   6 expire periodically, so you may need to regenerate it before use.
   7
   8 The certificate which has been generated is in `ssl/localhost_cert_bundle.pem`.
   9 It goes with the private key in `ssl/localhost.key`. Usually the private key
  10 is not regenerated when you run `./n.sh` but it can be if you uncomment a line.
  11
  12 You can make your browser accept this certificate by adding the CA to your
  13 browser. Browsers are quite fussy about this and so some experimentation has
  14 gone in to creating the `./n.sh` script in such a way as to first create a CA
  15 and then create a certificate signed by that CA. To add the CA to your browser
  16 you need the file `ssl/ca_cert.pem`, which can be added via the settings menu.
  17
  18 Having done all this, you should be able to run the HTTPS server by running
  19 `./simple_https_server.py` in the root of the repository. It will serve the
  20 current directory. We have placed an `index.html` file in the root for testing.
  21 You probably want to serve other files, so you can of course add them in also.
  22
  23 When serving, navigate to `https://localhost:8443` in your browser and you
  24 should see the "Hello, world" message from the testing `index.html` file.
  25
  26 We created this server so that we could easily serve configuration files or
  27 firmwares to IOT devices on our local network, which for security insist upon
  28 connecting via HTTPS. We compiled the CA certificate in to the device to make
  29 it work (IOT devices typically use only a single CA or a smaller set of CAs).
  30
  31 When serving to the local network rather than `localhost`, you will probably
  32 want to use dotted-decimal notation such as `https://192.168.1.1:8443`. Then
  33 you must edit the `ssl/localhost.conf` and `ssl/localhost_ext.conf` to put in
  34 additional IP addresses, using the existing `IP.1 = 127.0.0.1` as an example.
  35 Once you have done this you will obviously need to regenerate the certificate.
  36
  37 Note that `ssl/localhost_ext.conf` is a cut-down `ssl/localhost.conf` and must
  38 match. This was confusing when trying to add extra DNS or IP addresses and
  39 finding the certificate stubbornly included the old set. The reason we did it
  40 this way is because OpenSSL likes to strip extensions from the certificate in
  41 the signing process, so we use `ssl/localhost_ext.conf` to add them back in.