Lab 5: HTTPS and WebAuthn

This lab will introduce you to HTTPS and WebAuthn. In part 1, you will learn about the ACME protocol for obtaining TLS certificates, and in part 2, you will add WebAuthn support to Zoobar.

Network setup

For this lab, you will need access to a few more network ports: port 5000 for the certificate authority in part 1, and port 8443 for the HTTPS version of the Zoobar web site in part 2. Add these ports to your SSH port forwarding setup as needed.

Setting up the web server

Before you begin working on these exercises, please use Git to commit your Lab 4 solutions, fetch the latest version of the course repository, and then create a local branch called lab5 based on our lab5 branch, origin/lab5. Do not merge your previous solutions into lab 5. Here are the shell commands:

student@65660-v23:~$ cd lab
student@65660-v23:~/lab$ git commit -am 'my solution to lab4'
[lab4 c54dd4d] my solution to lab4
 1 files changed, 1 insertions(+), 0 deletions(-)
student@65660-v23:~/lab$ git pull
Already up-to-date.
student@65660-v23:~/lab$ git checkout -b lab5 origin/lab5
Branch lab5 set up to track remote branch lab5 from origin.
Switched to a new branch 'lab5'
student@65660-v23:~/lab$ make
...

Like lab 4, the source code for lab 5 is based on the initial web server from lab 1. It does not include privilege separation or Python profiles.

You will need to start several components: the zookws web server, the HTTPS proxy (whose job will be to translate HTTPS requests for zookws), and the certificate authority (whose job will be to issue a TLS certificate for your HTTPS proxy). The commands are:

student@65660-v23:~/lab$ ./zookd 8080 &
[1] 808
student@65660-v23:~/lab$ ./https-proxy.py &
[2] 809
[811] 2023/03/30 13:47:17.388163 starting ghostunnel in server mode
[811] 2023/03/30 13:47:17.449362 using cert/key files on disk as certificate source
[811] 2023/03/30 13:47:17.449517 error: unable to load certificates: open tls.cert: no such file or directory
error: open tls.cert: no such file or directory
student@65660-v23:~/lab$ ./ca/run.py &
[3] 818
 * Serving Flask app 'run' (lazy loading)
 * Environment: production
   WARNING: This is a development server. Do not use it in a production deployment.
   Use a production WSGI server instead.
 * Debug mode: on
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
 * Restarting with stat
 * Debugger is active!
 * Debugger PIN: 111-516-085
student@65660-v23:~/lab$ 

The errors you see above from https-proxy.py are because there is no TLS certificate yet; you will fix that in part 1.

Part 1: HTTPS certificates

To get HTTPS working, you need to obtain a TLS certificate for your web server. There is a standard protocol for obtaining a TLS certificate, called the Automatic Certificate Management Environment (ACME). The certificate authority (ca/run.py in our lab) uses this ACME protocol to validate requests from clients and issue certificates.

In this lab, you will need to use your browser to connect to Zoobar via HTTPS, using a certificate issued by the ACME CA server in your VM. By default, your browser does not trust this CA. You can explicitly add the CA's certificate to your browser, by downloading the root CA certificate from http://zoobar-ca.csail.mit.edu:5000/ca.crt, and installing it in your browser. For example, in Chrome, you can add a new CA under the Authorities tab in chrome://settings/certificates (you need to manually copy-paste that URL into your address bar, because Chrome blocks links to chrome:// URLs by default).

There is lots of documentation you can find online on ACME and certificates. Some suggestions that might be helpful:

• Section 7.1 in RFC 8555 describes roughly how the client should interact with the ACME CA.
• You can look at ca/acme.py to see how the ACME CA server handles requests from your client.
• ACME requires signing requests using JSON Web Keys (JWK) and JSON Web Signatures (JWS). The Authlib JOSE Python library, pre-installed in your VM, is convenient for working with JWK and JWS.
• Python provides libraries for managing Elliptic Curve and RSA keys; you will need EC keys for JWK, and RSA keys for the TLS certificate key. Python also has a library for managing x509 certificate and certificate requests, cryptography.x509.

Use make check-lab5 to check if your ACME client correctly obtains a TLS certificate.

Submit your answers to the first part of this lab assignment by running make handin.zip and upload the resulting handin.zip file to the submission web site.

Part 2: WebAuthn

In this part, you will modify Zoobar to support login via WebAuthn. Rather than implementing two-factor authentication, you will make WebAuthn the only authentication factor: a user will register for an account using WebAuthn (no password), and will similarly log in by entering their username and using WebAuthn to authenticate (again, no password).

WebAuthn uses an authenticator to store credentials and sign attestations in response to authentication requests. You can use a physical WebAuthn authenticator for this lab, such as the FIDO2-capable Yubikey 5. You can ask IS&T for a Yubikey token.

Alternatively, you can use the virtual authenticator in Chrome to emulate an authenticator, which might make your development easier instead of using a physical authenticator device.

There are many online resources describing WebAuthn; you are welcome to use any of them. Some suggested ones are:

• WebAuthn guide that gives an overview of how WebAuthn should work from the client perspective.
• The format of an attestation is described here.
• Duo Labs has a Python implementation of WebAuthn, which can be helpful as a reference. The code for parsing the authData, here, might be helpful.

Use make check-lab5 to check if your WebAuthn support works correctly.

Don't forget to remove your VM's ACME CA root certificate from your web browser, if you installed it at the beginning of this lab!

Run make handin.zip and upload handin.zip to the submission web site, and you're done!