diff --git a/src/SUMMARY.md b/src/SUMMARY.md index c5a19e4..a11eab9 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -2,8 +2,14 @@ [Introduction](./intro.md) [Motivation](./motivation.md) -[Quick Start](./developers/quick_start.md) -[Run a Notary Server](./developers/notary_server.md) + +# Getting Started + +- [Quick Start](./quick_start/README.md) + - [Rust](./quick_start/rust.md) + - [Browser Extension](./quick_start/browser_extension.md) +- [Run a Notary Server](./developers/notary_server.md) + # Protocol diff --git a/src/developers/quick_start.md b/src/developers/quick_start.md deleted file mode 100644 index 117d6c1..0000000 --- a/src/developers/quick_start.md +++ /dev/null @@ -1,75 +0,0 @@ -# Quick Start - -In this guide we will set up a general-purpose TLS verifier ( a.k.a. the `Notary`), so that a `Prover` can notarize some TLS data and generate a proof which he then shows to a `Verifier` for selective disclosure. - -So this guide will take you through the steps of: -- starting a `Notary` server -- running a `Prover` to notarize some web data -- running a `Verifier` to verify the notarized data - -## Preliminaries - -### Install rust - -If you don't have `rust` installed yet, install it with [rustup](https://rustup.rs/): -```shell -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -``` - -## Guide -Clone this repository first - -```shell -git clone https://github.com/tlsnotary/tlsn -``` - -### Start a simple Notary server: - -```shell -cd tlsn/tlsn/examples/simple -cargo run --release --example simple_notary -``` - -The `Notary` server will now be running in the background waiting for connections from a `Prover`. You can switch to another console to run the `Prover`. - -P/S: The notary server used in this example is less functional compared to its [advanced version](https://github.com/tlsnotary/tlsn/tree/dev/notary-server). This simple version is easier to integrate with from prover perspective, whereas the advanced version provides additional features like TLS connection with prover, WebSocket endpoint, API endpoints for further customisation etc. - -### Run a simple Prover: - -```shell -RUST_LOG=DEBUG,yamux=INFO cargo run --release --example simple_prover -``` - -The notarization session usually takes a few moments and the resulting proof will be written to the "proof.json" file. The proof can then be passed on to the `Verifier` for verification. - -The `simple_prover` notarizes and redacts the `USER_AGENT` HTTP header from the proof for the `Verifier`. You can change the code in `tlsn/tlsn/examples/simple/simple_prover.rs` to meet your needs: - -- change which server the `Prover` connects to -- add or remove HTTP request headers -- redact other strings in the request or the response - -⚠️ Please note that by default the `Notary` server expects that the cumulative size of the request and the server response is not more than 16KB. - - -### Run a simple Verifier: - -```shell -cargo run --release --example simple_verifier -``` - -This will verify the proof from the `simple_prover` (`proof.json`) and output the result to the console. - -Note how the parts which the prover chose not to disclose will be shown as "X": -```plaintext -GET / HTTP/1.1 -host: example.com -accept: */* -accept-encoding: identity -connection: close -user-agent: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -``` - - -## ProgCrypto workshop - -On November 17th 2023 we organized a TLSNotary workshop at [ProgCrypto](https://progcrypto.org/). This workshop has more examples for you to explore at diff --git a/src/quick_start/README.md b/src/quick_start/README.md new file mode 100644 index 0000000..7d03fad --- /dev/null +++ b/src/quick_start/README.md @@ -0,0 +1,13 @@ +# Quick Start + +This workshop will help you get started with TLSNotary, both in native [Rust](rust.md) and in the [browser](browser_extension.md). + +1. [Most Basic Example: Proving and Verifying Public Data (Rust)](rust.md#rust-simple) +2. [Proving and Verifying a Private Discord DM (Rust)](rust.md#rust-discord) +3. [Proving and Verifying ownership of a Twitter account (Browser)](browser_extension.md#browser) + +Objectives of this quick start: +* Gain a better understanding of what you can do with TLSNotary +* Learn the basics of how to prove and verify data using TLSNotary + +[Start](rust.md) \ No newline at end of file diff --git a/src/quick_start/browser_extension.md b/src/quick_start/browser_extension.md new file mode 100644 index 0000000..0ea048f --- /dev/null +++ b/src/quick_start/browser_extension.md @@ -0,0 +1,104 @@ +# TLSNotary Browser Extension + +In this Quick Start we will prove ownership of a Twitter account with TLSNotary's browser extension. + +## Run Notary Server + +If the notary server isn't running already, run the notary server (in this repository: ): + +```shell +cd notary-server +cargo run --release +``` + +The notary server will now be running in the background waiting for connections. + +## Install Browser Extension (Chrome/Brave) + +1. Download the browser extension from + +2. Unzip + ⚠️ This is a flat zip file, so be careful if you unzip from the command line, this zip file contains many file at the top level +3. Open **Manage Extensions**: +4. Enable `Developer mode` +5. Click the **Load unpacked** button +6. Select the unzipped folder + +![](images/extension_install.png) + +(Optional:) Pin the extension, so that it is easier to find in the next steps: + +![](images/extension_pin.png) + +## Websocket Proxy + +Since a web browser doesn't have the ability to make TCP connection, we need to use a websocket proxy server. You can either run one yourself, or use a TLSNotary hosted proxy. + +### Local Proxy + +To run your own websockify proxy locally, run: +``` +git clone https://github.com/novnc/websockify && cd websockify +./docker/build.sh +docker run -it --rm -p 55688:80 novnc/websockify 80 api.twitter.com:443 +``` +Note the `api.twitter.com:443` argument on the last line. + +### Hosted proxy + +Or, you can simply use remote proxy at `ws://notary.efprivacyscaling.org:55688` + +1. Open the extension +2. Click "Option" +3. Update proxy URL and click "Save" + + + +## Self-signed Certificates + +We have to jump through one more hoop: Because the local notary server is using a self-generated certificate, we have manually allow the certificate in our browser: + +* Visit or in a new browser tab +* click **Advanced** and next **Proceed to 127.0.0.1 (unsafe) + +This will manually override the ssl check on the local notary server and allow the extension to interact with it. + + +![](images/notary_certificate_advanced.png) + +> **_NOTE:_** ℹ️ The page will show "This site can’t be reached" or "127.0.0.1 refused to connect". This is OK, we only need your browser to accept the local certificate. + +## Notarize Twitter Account Access + +* Open Twitter and login if you haven't yet. +* open the extension, you should see requests being recorded: + +* If you click "Notarize" here, the extension will automatically notarize the correct request to prove your twitter ID. **However, we are going to do it manually** +* Click on "Requests", and then search for the text "setting" in search box: + +* Select the request, and then click on **Notarize**: + +* First, select any headers that you would like to reveal. + +* Second, highlight the text that you want to make public to hide everything else. + +* Click **Notarize**, you should see your notarization being processed: + + +You can open the offscreen console and observe the browser extension logs by going to -> TLSN Extension -> Details -> offscreen.html + +## Verify + +When the notarization is ready, you can click **View Proof**. + +If you did close the UI, you can find the proof by clicking **History** and **View Proof**. + + + +You also have the option to download the proof. You can view this proof later by using the **Verify** button or via . + +## Troubleshooting + +* Did you allow the locally generated notary certificate? [link](#certificate) +* Requests(0): no requests in the Browser extension => restart the TLSN browser extension in and reload the Twitter page. +* Is the notary server still running? It should, check the console log. diff --git a/src/quick_start/images/discord_authentication_token.png b/src/quick_start/images/discord_authentication_token.png new file mode 100644 index 0000000..b76ed12 Binary files /dev/null and b/src/quick_start/images/discord_authentication_token.png differ diff --git a/src/quick_start/images/extension_headers.png b/src/quick_start/images/extension_headers.png new file mode 100644 index 0000000..94fb315 Binary files /dev/null and b/src/quick_start/images/extension_headers.png differ diff --git a/src/quick_start/images/extension_headers_reveal.png b/src/quick_start/images/extension_headers_reveal.png new file mode 100644 index 0000000..b50aeaa Binary files /dev/null and b/src/quick_start/images/extension_headers_reveal.png differ diff --git a/src/quick_start/images/extension_history.png b/src/quick_start/images/extension_history.png new file mode 100644 index 0000000..308658c Binary files /dev/null and b/src/quick_start/images/extension_history.png differ diff --git a/src/quick_start/images/extension_install.png b/src/quick_start/images/extension_install.png new file mode 100644 index 0000000..6653921 Binary files /dev/null and b/src/quick_start/images/extension_install.png differ diff --git a/src/quick_start/images/extension_notarize.png b/src/quick_start/images/extension_notarize.png new file mode 100644 index 0000000..803fccf Binary files /dev/null and b/src/quick_start/images/extension_notarize.png differ diff --git a/src/quick_start/images/extension_pin.png b/src/quick_start/images/extension_pin.png new file mode 100644 index 0000000..b44b14a Binary files /dev/null and b/src/quick_start/images/extension_pin.png differ diff --git a/src/quick_start/images/extension_process.png b/src/quick_start/images/extension_process.png new file mode 100644 index 0000000..5200c7d Binary files /dev/null and b/src/quick_start/images/extension_process.png differ diff --git a/src/quick_start/images/extension_proxy.png b/src/quick_start/images/extension_proxy.png new file mode 100644 index 0000000..ecf3807 Binary files /dev/null and b/src/quick_start/images/extension_proxy.png differ diff --git a/src/quick_start/images/extension_request.png b/src/quick_start/images/extension_request.png new file mode 100644 index 0000000..1b61031 Binary files /dev/null and b/src/quick_start/images/extension_request.png differ diff --git a/src/quick_start/images/extension_requests.png b/src/quick_start/images/extension_requests.png new file mode 100644 index 0000000..cd9822b Binary files /dev/null and b/src/quick_start/images/extension_requests.png differ diff --git a/src/quick_start/images/extension_text_reveal.png b/src/quick_start/images/extension_text_reveal.png new file mode 100644 index 0000000..cb307cb Binary files /dev/null and b/src/quick_start/images/extension_text_reveal.png differ diff --git a/src/quick_start/images/extension_twitter_requests.png b/src/quick_start/images/extension_twitter_requests.png new file mode 100644 index 0000000..e11ce5a Binary files /dev/null and b/src/quick_start/images/extension_twitter_requests.png differ diff --git a/src/quick_start/images/extesnion_notarize_pending.png b/src/quick_start/images/extesnion_notarize_pending.png new file mode 100644 index 0000000..8292287 Binary files /dev/null and b/src/quick_start/images/extesnion_notarize_pending.png differ diff --git a/src/quick_start/images/notary_certificate.png b/src/quick_start/images/notary_certificate.png new file mode 100644 index 0000000..510796c Binary files /dev/null and b/src/quick_start/images/notary_certificate.png differ diff --git a/src/quick_start/images/notary_certificate_advanced.png b/src/quick_start/images/notary_certificate_advanced.png new file mode 100644 index 0000000..491727c Binary files /dev/null and b/src/quick_start/images/notary_certificate_advanced.png differ diff --git a/src/quick_start/images/proof_viz.png b/src/quick_start/images/proof_viz.png new file mode 100644 index 0000000..2aefd2c Binary files /dev/null and b/src/quick_start/images/proof_viz.png differ diff --git a/src/quick_start/images/run_vs_code.png b/src/quick_start/images/run_vs_code.png new file mode 100644 index 0000000..2767df7 Binary files /dev/null and b/src/quick_start/images/run_vs_code.png differ diff --git a/src/quick_start/rust.md b/src/quick_start/rust.md new file mode 100644 index 0000000..a21a965 --- /dev/null +++ b/src/quick_start/rust.md @@ -0,0 +1,224 @@ +# Rust Quick Start + +This Quick Start will show you how to use TLSNotary in a native Rust application. + +## Requirements + +Before we start, make sure you have cloned the `tlsn` repository and have a recent version of Rust installed. + +### Clone the TLSNotary Repository + +Clone the `tlsn` repository: + +```shell +git clone https://github.com/tlsnotary/tlsn.git +``` + +Next open the `tlsn` folder in your favorite IDE. + +### Install Rust + +If you don't have Rust installed yet, you can install it using [rustup](https://rustup.rs/): + +```shell +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +``` + +To configure your current shell, run: +```shell +source "$HOME/.cargo/env" +``` + +## Simple Example: Notarizing Public Data from example.com + +We will start with the simplest possible use case for TLSNotary: +1. Notarize: Fetch and create a proof of its content. +2. Verify the proof. +3. Redact the `USER_AGENT` and titles. +4. Verify the redacted proof. + +### 1. Notarize + +Run a simple prover: + +```shell +cd tlsn/examples/simple +cargo run --release --example simple_prover +``` + +If the notarization was successful, you should see this output in the console: + +```log +Starting an MPC TLS connection with the server +Got a response from the server +Notarization completed successfully! +The proof has been written to `simple_proof.json` +``` + +If you want to see more details, you can run the prover with extra logging: +```shell +RUST_LOG=DEBUG,yamux=INFO cargo run --release --example simple_prover +``` + +### 2. Verify the Proof + +When you open `simple_proof.json` in an editor, you will see a JSON file with lots of non-human-readable byte arrays. You can decode this file by running: + +```shell +cargo run --release --example simple_verifier +``` + +This will output the TLS-transaction in clear text: + +```log +Successfully verified that the bytes below came from a session with Dns("example.com") at 2023-11-03 08:48:20 UTC. +Note that the bytes which the Prover chose not to disclose are shown as X. + +Bytes sent: +... +``` + +### 3. Redact Information + +Open `tlsn/examples/simple/simple_prover.rs` and locate the line with: + +```rust +let redact = false; +``` + +and change it to: + +```rust +let redact = true; +``` + +Next, if you run the `simple_prover` and `simple_verifier` again, you'll notice redacted `X`'s in the output: + +```shell +cargo run --release --example simple_prover +cargo run --release --example simple_verifier +``` + +```log + + + + XXXXXXXXXXXXXX +... +``` + +You can also use to inspect your proofs. Open and drag and drop `simple_proof.json` from your file explorer into the drop zone. + +![Proof Visualization](images/proof_viz.png) + +Redacted bytes are marked with red █ characters. + +### (Optional) Extra Experiments + +Feel free to try these extra challenges: + +- [ ] Modify the `server_name` (or any other data) in `simple_proof.json` and verify that the proof is no longer valid. +- [ ] Modify the `build_proof_with_redactions` function in `simple_prover.rs` to redact more or different data. + +## Notarizing Private Information: Discord Message + +Next, we will use TLSNotary to generate a proof of private information: a private Discord DM. + +We will also use an explicit (locally hosted) notary server this time. + +### 1. Start a Local Notary Server + +The notary server used in this example is more functional compared to the (implicit) simple notary service used in the example above. This notary server should actually be run by the Verifier or a neutral party. To make things simple, we run everything on the same machine. + +```shell +cd notary-server +cargo run --release +``` + +The notary server will now be running in the background waiting for connections. + +Keep it running and open a new terminal. + +### 2. Get Authorization Token and Channel ID + +Before we can notarize a Discord message, we need some parameters in a `.env` file. + +In the `tlsn/examples/discord` folder, copy the `.env.example` file and name it `.env`. + +In this `.env`, we will input the `USER_AGENT`, `AUTHORIZATION` token, and `CHANNEL_ID`. + +| Name | Example | Location | +| ------------- | ---------------------------------------------------------------------------------- | ------------------------------------------- | +| USER_AGENT | `"Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:109.0) Gecko/20100101 Firefox/116.0"` | Look for `User-Agent` in request headers | +| AUTHORIZATION | `"MTE1NDe1Otg4N6NxNjczOTM2OA.GYbUBf.aDtcMUKDOmg6C2kxxFtlFSN1pgdMMBtpHgBBEs"` | Look for `Authorization` in request headers | +| CHANNEL_ID | `"1154750485639745567"` | URL | + +You can obtain these parameters by opening [Discord](https://discord.com/channels/@me) in your browser and accessing the message history you want to notarize. + +> **_NOTE:_** ⚠️ Please note that notarizing only works for short transcripts at the moment, so choose a contact with a short history. + +Next, open the **Developer Tools**, go to the **Network** tab, and refresh the page. Then, click on **Search** and type `/api` to filter results to Discord API requests. From there, you can copy the needed information into your `.env` as indicated above. + +You can find the `CHANNEL_ID` directly in the URL: + +`https://discord.com/channels/@me/{CHANNEL_ID)` + +![Discord Authentication Token](./images/discord_authentication_token.png) + +### 3. Create the proof + +Next, run the `discord_dm` example to generate a proof: + +```shell +cd tlsn/tlsn/examples/discord +RUST_LOG=debug,yamux=info cargo run --release --example discord_dm +``` + +If everything goes well, you should see this output: + +```log +... +2023-11-03T15:53:51.147732Z DEBUG discord_dm: Notarization complete! +``` + +The Notary server should log: + +```log +2023-11-03T15:53:46.540247Z DEBUG main ThreadId(01) run_server: notary_server::server: Received a prover's TCP connection prover_address=127.0.0.1:56631 +... +2023-11-03T15:53:46.542261Z DEBUG tokio-runtime-worker ThreadId(10) notary_server::service: Starting notarization... session_id="006b3293-8fba-44ac-8692-41daa47e4a9a" +... +2023-11-03T15:53:51.147074Z INFO tokio-runtime-worker ThreadId(10) notary_server::service::tcp: Successful notarization using tcp! session_id="006b3293-8fba-44ac-8692-41daa47e4a9a" +``` + +If the transcript was too long, you may encounter the following error. This occurs because there is a default limit of notarization size to 16kB: + +```log +thread 'tokio-runtime-worker' panicked at 'called `Result::unwrap()` on an `Err` value: IOError(Custom { kind: InvalidData, error: BackendError(DecryptionError("Other: KOSReceiverActor is not setup")) })', /Users/heeckhau/tlsnotary/tlsn/tlsn/tlsn-prover/src/lib.rs:173:50 +``` + +The Discord example code redacts the `auth_token`, but feel free to change the redacted regions. + +The proof is written to `discord_dm_proof.json`. + +### Verify + +Verify the proof by dropping the JSON file into or by running: + +```shell +cargo run --release --example discord_dm_verifier +``` + +🍾 Great job! You have successfully used TLSNotary in Rust. + +### (Optional) Notarize More Private Data + +If the examples above were too easy for you, try to notarize data from other websites such as: + +- [ ] Amazon purchase +- [ ] Twitter DM (see ) +- [ ] LinkedIn skill +- [ ] Steam accomplishment +- [ ] Garmin Connect achievement +- [ ] AirBnB score +- [ ] Tesla ownership \ No newline at end of file