Merge pull request #249 from alan-turing-institute/248-server-did

Remove out-of-date `issuer_did` config parameter

Author: thobson88

crates/trustchain-http/src/config.rs

@@ -16,27 +16,26 @@ const DEFAULT_PORT: u16 = 8081;
 /// HTTP configuration.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 pub struct HTTPConfig {
+    /// Hostname displayed in generated QR codes, e.g. for credential offers.
+    /// If using a local server with an Android emulator for Trustchain Mobile development, the
+    /// hostname `10.0.2.2` refers to `127.0.0.1` (localhost) of the machine running the emulator.
+    pub host_display: String,
     /// Host address for server.
-    /// machine running emulator.
     pub host: IpAddr,
-    /// Hostname display in QR codes. For example, if using local server with an Android emulator
-    /// `10.0.2.2` refers to `127.0.0.1` of machine
-    /// running emulator.
-    pub host_display: String,
-    /// Port for server
+    /// Port for server.
     pub port: u16,
-    /// ION host
+    /// ION host.
     pub ion_host: IpAddr,
-    /// ION port
+    /// ION port.
     pub ion_port: u16,
-    /// Optional server DID if issuing or verifying
+    /// Optional server DID if attesting dDIDs or verifying credentials/presentations.
     pub server_did: Option<String>,
-    /// Flag indicating whether server uses https
+    /// Flag indicating whether server uses https.
     pub https: bool,
-    /// Path containing certificate and key necessary for https
+    /// Path containing certificate and key necessary for https.
     pub https_path: Option<String>,
     /// Display downstream DIDs (instead of URLs) in QR codes for verifiable endpoint retrieval
-    /// (`None` by default and unwrapped as `true`)
+    /// (`None` by default and unwrapped as `true`).
     pub verifiable_endpoints: Option<bool>,
     /// Root event time for verifier.
     pub root_event_time: Option<Timestamp>,

docs/getting-started.md

@@ -144,27 +144,87 @@ Then open your copy of `trustchain_config.toml` for editing:
 ```console
 nano $TRUSTCHAIN_CONFIG
 ```
-and edit the following configuration parameters:
+This file is organised into different sections, separated by headings inside square brackets. At this point, we only need to consider the `[ion]` and `[cli]` sections.
 
-- In the `[ion]` section, add the `bitcoin_rpc_username` and `bitcoin_rpc_password` that were chosen when you configured the [Bitcoin CLI](ion.md#bitcoin-cli).
-- If you intend to act as an issuer of digital credentials, and you already have you own DID for this purpose, add it in the `[http]` section to the `issuer_did` parameter value. Otherwise, the `[http]` section can be ignored.
-- If you know the root event time for your DID network, add it in the `[cli]` section to the `root_event_time` parameter value. This must be an integer in Unix time format, e.g.:
-```{ .text .no-copy }
-root_event_time = 1697213008
+Edit the following configuration parameters:
+
+- In the `[ion]` section, set the `mongo_database_ion_core` parameter to either `"ion-mainnet-core"` or `"ion-testnet-core"`, depending on the Bitcoin network in use (see the example below). This parameter must match the `databaseName` parameter in the ION Core config file which can be viewed by running the following command:
+```console
+cat $ION_CORE_CONFIG_FILE_PATH
 ```
+- Also in the `[ion]` section, set the address of your Bitcoin node in the `bitcoin_connection_string` parameter. If Bitcoin is running locally, set this to localhost and choose the correct port number for the particular Bitcoin network in use (see the example below).
+- Also in the `[ion]` section, set the `bitcoin_rpc_username` and `bitcoin_rpc_password` parameters that were chosen when you configured the [Bitcoin CLI](ion.md#bitcoin-cli).
+- If you know the root event time for your DID network, add it in the `[cli]` section to the `root_event_time` parameter value. This must be an integer in Unix time format.
+
+After completing the above steps, the `trustchain_config.toml` file should look similar to the following example (choose the correct tab for your [Bitcoin network configuration](ion.md#bitcoin-mainnet-vs-testnet)):
+
+=== "Mainnet"
+
+    ```bash
+    [ion]
+    mongo_connection_string = "mongodb://localhost:27017/"
+    mongo_database_ion_core = "ion-mainnet-core"
+
+    bitcoin_connection_string = "http://localhost:8332"
+    bitcoin_rpc_username = "admin"
+    bitcoin_rpc_password = "<YOUR_BITCOIN_RPC_PASSWORD>"
+
+    [cli]
+    root_event_time = 1697213008
+    ion_endpoint.host = "127.0.0.1"
+    ion_endpoint.port = 3000
+    ```
+
+=== "Testnet4"
+
+    ```bash
+    [ion]
+    mongo_connection_string = "mongodb://localhost:27017/"
+    mongo_database_ion_core = "ion-testnet-core"
+
+    bitcoin_connection_string = "http://localhost:48332"
+    bitcoin_rpc_username = "admin"
+    bitcoin_rpc_password = "<YOUR_BITCOIN_RPC_PASSWORD>"
+
+    [cli]
+    root_event_time = 1769521645
+    ion_endpoint.host = "127.0.0.1"
+    ion_endpoint.port = 3000
+    ```
+
+=== "Testnet3 (Deprecated)"
+
+    ```bash
+    [ion]
+    mongo_connection_string = "mongodb://localhost:27017/"
+    mongo_database_ion_core = "ion-testnet-core"
+
+    bitcoin_connection_string = "http://localhost:18332"
+    bitcoin_rpc_username = "admin"
+    bitcoin_rpc_password = "<YOUR_BITCOIN_RPC_PASSWORD>"
+
+    [cli]
+    root_event_time = 1697213008
+    ion_endpoint.host = "127.0.0.1"
+    ion_endpoint.port = 3000
+    ```
 
 !!! warning "Root event time"
 
     The "root event time" refers to the exact time at which the root DID was published. It is imperative that this configuration parameter is entered correctly, because it identifies the root public key certificate.
 
+    The value given in the above example is for illustration only.
+
     If you are not sure about the correct root event time for your network, or you are intending to create your own root DID, leave this parameter unset for now.
 
-    In future versions of Trustchain, this Unix time parameter will be replaced by a calendar date (the "root event date") plus a short confirmation code.
+    In future versions of Trustchain, this Unix time parameter will be replaced by a calendar date, the "root event date", plus a short confirmation code (which is the format used in the Trustchain Mobile app).
 
 ## Using Trustchain
 
-Trustchain is controlled via its command line interface (CLI). Supported operations include DID resolution, issuance, attestation and verification. It can also be used to issue and verify digital credentials.
+Trustchain is controlled via its command line interface (CLI). Supported operations include DID resolution, creation, attestation and verification. It can also be used to sign and verify digital credentials.
 
 Instructions on how to use the Trustchain CLI are provided on the [Usage page](usage.md).
 
+If you also want to be able to issue verifiable credentials to users of the Trustchain Mobile credential wallet app, check out [this page](http-server.md) for instructions on how to configure and run the built-in Trustchain HTTP server.
+
 &nbsp;

docs/http-server.md

@@ -26,33 +26,53 @@ Under the section headed `[http]`, add or edit the following configuration param
 
 - Set the `root_event_time` parameter to the integer root DID timestamp for your network (in Unix Time).
 - Set the `host_display` parameter to the fully qualified domain name of your Trustchain HTTP server.
+- Set the `host` parameter to the host address for the server. If you want the server to be accessible only on a local network, set this to `"127.0.0.1"` (localhost). If you want the server to be accessible from the Internet, set it to `"0.0.0.0"`. In this case, ensure both your router and server are protected by a properly configured firewall.
 - Set the `port` parameter to the port number on which your server will listen for HTTP requests.
 - Set the `https` parameter to either `true` or `false`, depending on whether your server will use TLS for encrypted communications.
 - 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.
 - 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"`.
 - Set the `ion_port` parameter to the port number of your ION instance. By default, ION listens on port `3000`.
-- 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.
+- If you intend to use your server for credential verification and/or for dDID attestation (via the Trustchain challenge-response protocol), and you already have your own DID for this purpose, set it as the `server_did` parameter. If the server is only intended to respond to requests from the Trustchain Mobile app, e.g. for issuing verifiable credentials, this parameter is not required and can be omitted.
 
 !!! example "Example HTTP server configuration"
 
     After completing the above steps, the `[http]` section of `trustchain_config.toml` should look similar to the following example:
+
     ```bash
     [http]
-    root_event_time = 1697213008
-    host_display = "https://trustchain.example.com"
+    root_event_time = 1769521645
+    host_display = "<YOUR_SERVER_HOSTNAME>"
     port = 443
     https = true
     https_path = "~/.trustchain/http/self_signed_certs"
+    host = "0.0.0.0"
     ion_host = "127.0.0.1"
     ion_port = 3000
-    server_did = "did:ion:test:EiB4S2znMhXFMxLLuI6dSrcfn4uF1MLFGvMYTwRPRH_-eQ"
+    server_did = "<YOUR_SERVER_DID>"
     ```
 
+### Network configuration
+
+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.
+
+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.
+
+If your node is running on a computer in your local network, the network configuration steps are as follows:
+
+- On your router, configure the firewall to allow connections to the port configured for the Trustchain server, and 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.
+- If there is a firewall running on your Trustchain node, ensure it is configured to allow inbound connections to the relevant port.
+
 ### HTTPS configuration
 
 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.
 
-In this case, you will need a TLS certificate and associated cryptographic keys.
+!!! info "HTTPS is required to support Trustchain Mobile"
+
+    The Trustchain HTTP server is designed to handle requests from the Trustchain Mobile app, for operations such as the issuance and verification of [Verifiable Credentials](https://www.w3.org/TR/vc-data-model-2.0/).
+
+    If you intend to use the HTTP server for this purpose, it is essential that you configure it with HTTPS support. The Trustchain Mobile app will refuse to connect to a server that does not have a valid TLS certificate.
+
+To support HTTPS, you will need a TLS certificate and associated cryptographic keys.
 
 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.
 
@@ -72,22 +92,22 @@ Step 7 of the Certbot instructions requires you to install your new TLS certific
 
 - make a new directory to store the certificate:
 ```console
-mkdir -p "$TRUSTCHAIN_CONFIG"/http/self_signed_certs
+mkdir -p "$TRUSTCHAIN_DATA"/http/self_signed_certs
 ```
 - 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.:
 ```console
-sudo cp /etc/letsencrypt/live/trustchain.example.com/fullchain.pem "$TRUSTCHAIN_CONFIG"/http/self_signed_certs
-sudo cp /etc/letsencrypt/live/trustchain.example.com/privkey.pem "$TRUSTCHAIN_CONFIG"/http/self_signed_certs
+sudo cp /etc/letsencrypt/live/trustchain.example.com/fullchain.pem "$TRUSTCHAIN_DATA"/http/self_signed_certs
+sudo cp /etc/letsencrypt/live/trustchain.example.com/privkey.pem "$TRUSTCHAIN_DATA"/http/self_signed_certs
 ```
 - 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):
 ```console
-sudo chown <USER>:<GROUP> "$TRUSTCHAIN_CONFIG"/http/self_signed_certs/fullchain.pem
-sudo chown <USER>:<GROUP> "$TRUSTCHAIN_CONFIG"/http/self_signed_certs/privkey.pem
+sudo chown <USER>:<GROUP> "$TRUSTCHAIN_DATA"/http/self_signed_certs/fullchain.pem
+sudo chown <USER>:<GROUP> "$TRUSTCHAIN_DATA"/http/self_signed_certs/privkey.pem
 ```
 - create symbolic links to the certificate and key files:
 ```console
-ln -s "$TRUSTCHAIN_CONFIG"/http/self_signed_certs/fullchain.pem "$TRUSTCHAIN_CONFIG"/http/self_signed_certs/cert.pem
-ln -s "$TRUSTCHAIN_CONFIG"/http/self_signed_certs/privkey.pem "$TRUSTCHAIN_CONFIG"/http/self_signed_certs/key.pem
+ln -s "$TRUSTCHAIN_DATA"/http/self_signed_certs/fullchain.pem "$TRUSTCHAIN_DATA"/http/self_signed_certs/cert.pem
+ln -s "$TRUSTCHAIN_DATA"/http/self_signed_certs/privkey.pem "$TRUSTCHAIN_DATA"/http/self_signed_certs/key.pem
 ```
 
 !!! warning "Running the Trustchain HTTP server on port 443"
@@ -97,18 +117,6 @@ ln -s "$TRUSTCHAIN_CONFIG"/http/self_signed_certs/privkey.pem "$TRUSTCHAIN_CONFI
     sudo setcap CAP_NET_BIND_SERVICE=+eip $HOME/.cargo/bin/trustchain-http
     ```
 
-### Network configuration
-
-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.
-
-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.
-
-If your node is running on a computer in your local network, the network configuration steps are as follows:
-
-- On your router, configure the firewall to allow connections to the port configured for the Trustchain server,
-- 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.
-- If there is a firewall running on your Trustchain node, ensure it is configured to allow connections to the relevant port.
-
 ## Running the HTTP server
 
 Open a new Terminal window and invoke the Trustchain HTTP server with the following command:

trustchain_config.toml

@@ -2,17 +2,22 @@
 mongo_connection_string = "mongodb://localhost:27017/"
 mongo_database_ion_core = "ion-testnet-core"
 
-bitcoin_connection_string = "http://localhost:18332"
+bitcoin_connection_string = "http://localhost:48332"
 bitcoin_rpc_username = "<YOUR_BITCOIN_RPC_USERNAME>"
 bitcoin_rpc_password = "<YOUR_BITCOIN_RPC_PASSWORD>"
 
-[http]
-host = "127.0.0.1"
-host_reference = "127.0.0.1"
-port = 8081
-issuer_did = "<YOUR_ISSUER_DID>"
-
 [cli]
 root_event_time = 0 # SET YOUR ROOT EVENT TIME HERE
 ion_endpoint.host = "127.0.0.1"
 ion_endpoint.port = 3000
+
+[http]
+root_event_time = 0 # SET YOUR ROOT EVENT TIME HERE
+host_display = "<YOUR_SERVER_HOSTNAME>"
+host = "127.0.0.1"
+port = 80
+https = false
+https_path = "~/.trustchain/http/self_signed_certs"
+ion_host = "127.0.0.1"
+ion_port = 3000
+server_did = "<YOUR_SERVER_DID>"