|
| 1 | +# HTTP Server |
| 2 | + |
| 3 | +Trustchain includes a built-in HTTP server that can be used to issue and verify digital credentials via an HTTP API. The server can also respond to requests made by the Trustchain Mobile app. |
| 4 | + |
| 5 | +!!! info "Prerequisites" |
| 6 | + |
| 7 | + To use the Trustchain HTTP server, first make sure that you have followed the installation and configuration instructions on the [Getting Started](getting-started.md) page. |
| 8 | + |
| 9 | + Your ION node will also need to be up and running, either locally or on a remote machine to which you are connected via SSH and with port forwarding. Instructions for restarting ION, and setting up port forwarding, can be found [here](ion.md#running-ion). |
| 10 | + |
| 11 | +## Installation |
| 12 | + |
| 13 | +To install the Trustchain HTTP server, run: |
| 14 | +```console |
| 15 | +$ cargo install --path "$TRUSTCHAIN_REPO"/crates/trustchain-http |
| 16 | +``` |
| 17 | + |
| 18 | +## Configuration |
| 19 | + |
| 20 | +Before starting the HTTP server some configuation parameters will need to be set. Execute the following command to open the Trustchain configuration file `trustchain_config.toml` for editing: |
| 21 | +```console |
| 22 | +$ nano $TRUSTCHAIN_CONFIG |
| 23 | +``` |
| 24 | + |
| 25 | +Under the section headed `[http]`, add or edit the following configuration parameters: |
| 26 | + |
| 27 | +- Set the `root_event_time` parameter to the integer root DID timestamp for your network (in Unix Time). |
| 28 | +- Set the `host_display` parameter to the fully qualified domain name of your Trustchain HTTP server. |
| 29 | +- Set the `port` parameter to the port number on which your server will listen for HTTP requests. |
| 30 | +- Set the `https` parameter to either `true` or `false`, depending on whether your server will use TLS for encrypted communications. |
| 31 | +- If `https` is set to `true`, set the `https_path` parameter to the directory containing the certificate and key necessary for accepting HTTPS connections. See the section on [HTTPS configuration](#https-configuration) for more details. |
| 32 | +- Set the `ion_host` parameter to the host name of your ION instance. If ION is running on the local machine, set this to the loopback address `"127.0.0.1"`. |
| 33 | +- Set the `ion_port` parameter to the port number of your ION instance. By default, ION listens on port `3000`. |
| 34 | +- If you intend to act as an issuer of digital credentials and you already have you own DID for this purpose, set it as the `server_did` parameter. |
| 35 | + |
| 36 | +!!! example "Example HTTP server configuration" |
| 37 | + |
| 38 | + After completing the above steps, the `[http]` section of `trustchain_config.toml` should look similar the following example: |
| 39 | + ```bash |
| 40 | + [http] |
| 41 | + root_event_time = 1697213008 |
| 42 | + host_display = "https://trustchain.example.com" |
| 43 | + port = 443 |
| 44 | + https = true |
| 45 | + https_path = "~/.trustchain/http/self_signed_certs" |
| 46 | + ion_host = "127.0.0.1" |
| 47 | + ion_port = 3000 |
| 48 | + server_did = "did:ion:test:EiB4S2znMhXFMxLLuI6dSrcfn4uF1MLFGvMYTwRPRH_-eQ" |
| 49 | + ``` |
| 50 | + |
| 51 | +### HTTPS configuration |
| 52 | + |
| 53 | +It is strongly advisable to configure your Trustchain HTTP server to use TLS (Transport Layer Security) for encrypted communictions via HTTPS. This is done by setting the `https` config parameter to `true` and the `port` parameter to `443`, which is the default HTTPS port number. |
| 54 | + |
| 55 | +In this case, you will need a TLS certificate and associated cryptographic keys. |
| 56 | + |
| 57 | +If you do not already have a TLS certificate, you can obtain one by using a free and open source service called [Certbot](https://certbot.eff.org/). Certbot is a software tool for automatically generating [Let's Encrypt](https://letsencrypt.org/) certificates for web servers to enable HTTPS, which is precisely what is needed here. |
| 58 | + |
| 59 | +Follow the steps in the [Certbot setup instructions](https://certbot.eff.org/instructions?ws=other&os=ubuntubionic) to generate a TLS certificate. |
| 60 | + |
| 61 | +At the end of Step 6, you should see output similar to the following: |
| 62 | +``` |
| 63 | +Successfully received certificate. |
| 64 | +Certificate is saved at: /etc/letsencrypt/live/trustchain.example.com/fullchain.pem |
| 65 | +Key is saved at: /etc/letsencrypt/live/trustchain.example.com/privkey.pem |
| 66 | +This certificate expires on 2024-02-25. |
| 67 | +These files will be updated when the certificate renews. |
| 68 | +Certbot has set up a scheduled task to automatically renew this certificate in the background. |
| 69 | +``` |
| 70 | + |
| 71 | +Step 7 of the Certbot instructions requires you to install your new TLS certificate. To do this: |
| 72 | + |
| 73 | +- make a new directory to store the certificate: |
| 74 | +```console |
| 75 | +$ mkdir "$TRUSTCHAIN_CONFIG"/http/self_signed_certs |
| 76 | +``` |
| 77 | +- copy the certificate file `fullchain.pem` and the key file `privkey.pem` from the locations given in the output from Step 6 (above), to the new directory, e.g.: |
| 78 | +```console |
| 79 | +$ sudo cp /etc/letsencrypt/live/trustchain.example.com/fullchain.pem "$TRUSTCHAIN_CONFIG"/http/self_signed_certs |
| 80 | +$ sudo cp /etc/letsencrypt/live/trustchain.example.com/privkey.pem "$TRUSTCHAIN_CONFIG"/http/self_signed_certs |
| 81 | +``` |
| 82 | +- change the ownership of those files so they are owned by the user and group that will run the Trustchain server (replace `<USER>` and `<GROUP>` in the following commands): |
| 83 | +```console |
| 84 | +$ sudo chown <USER>:<GROUP> "$TRUSTCHAIN_CONFIG"/http/self_signed_certs/fullchain.pem |
| 85 | +$ sudo chown <USER>:<GROUP> "$TRUSTCHAIN_CONFIG"/http/self_signed_certs/privkey.pem |
| 86 | +``` |
| 87 | +- create symbolic links to the certificate and key files: |
| 88 | +```console |
| 89 | +$ ln -s "$TRUSTCHAIN_CONFIG"/http/self_signed_certs/fullchain.pem "$TRUSTCHAIN_CONFIG"/http/self_signed_certs/cert.pem |
| 90 | +$ ln -s "$TRUSTCHAIN_CONFIG"/http/self_signed_certs/privkey.pem "$TRUSTCHAIN_CONFIG"/http/self_signed_certs/key.pem |
| 91 | +``` |
| 92 | + |
| 93 | +!!! warning "Running the Trustchain HTTP server on port 443" |
| 94 | + |
| 95 | + By default, elevated privileges are required when binding a process to port 443. Therefore, if you have configured the HTTP server to listen on port 443, you will need to run the following command (once) to allow a non-root user to start the server: |
| 96 | + ```console |
| 97 | + $ sudo setcap CAP_NET_BIND_SERVICE=+eip $HOME/.cargo/bin/trustchain-http |
| 98 | + ``` |
| 99 | + |
| 100 | +### Network configuration |
| 101 | + |
| 102 | +To make your Trustchain HTTP server reachable from the public Internet you will need to configure your local network to allow connections to the port given in the `trustchain_config.toml` file, and to route them to your Trustchain node. |
| 103 | + |
| 104 | +If your Trustchain node is running on a virtual machine (VM) in the cloud, navigate to your cloud provider's web portal and open the network settings page for the VM. Then create an "inbound port rule" to allow incoming traffic to the relevant port. |
| 105 | + |
| 106 | +If your node is running on a computer in your local network, the network configuration steps are as follows: |
| 107 | + |
| 108 | +- On your router, configure the firewall to allow connections to the port configured for the Trustchain server, |
| 109 | +- On your router, configure port forwarding (for the same port) to the IP address of your Trustchain node on the local network. To enable this, you may want to assign a static local IP address to your Trustchain node. |
| 110 | +- If there is a firewall running on your Trustchain node, ensure it is configured to allow connections to the relevant port. |
| 111 | + |
| 112 | +## Running the HTTP server |
| 113 | + |
| 114 | +Open a new Terminal window and invoke the Trustchain HTTP server with the following command: |
| 115 | +```console |
| 116 | +$ trustchain-http |
| 117 | +``` |
| 118 | + |
| 119 | +The server will listen on the port specified in the `trustchain_config.toml` file. Server log messages will be printed to this terminal window, so you will see a new message whenever the server responds to a request. |
| 120 | + |
| 121 | + |
0 commit comments