New quickstart: based on ProgCrypto workshop

tlsnotary · Dec 29, 2023 · a562f4b · a562f4b
1 parent cb5a9ed
commit a562f4b
Show file tree

Hide file tree

Showing 23 changed files with 349 additions and 77 deletions.
diff --git 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
diff --git a/src/quick_start/README.md 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)
diff --git a/src/quick_start/browser_extension.md b/src/quick_start/browser_extension.md
@@ -0,0 +1,104 @@
+# TLSNotary Browser Extension <a name="browser"></a>
+
+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: <https://github.com/tlsnotary/tlsn.git>):
+
+```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
+<https://github.com/tlsnotary/tlsn-extension/releases/download/0.0.1/tlsn-extension-0.0.1.zip>
+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**: <chrome://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"
+
+<img width="478"  src="images/extension_proxy.png">
+
+## 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:<a name="certificate"></a>
+
+* Visit <https://127.0.0.1:7047> or <https://localhost:7047> 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.png) -->
+![](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 <https://twitter.com> and login if you haven't yet.
+* open the extension, you should see requests being recorded:  
+<img width="477"  src="images/extension_requests.png">
+* 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:  
+<img width="479"  src="images/extension_request.png">
+* Select the request, and then click on **Notarize**:  
+<img width="477"  src="images/extension_headers.png">
+* First, select any headers that you would like to reveal.  
+<img width="479"  src="images/extension_headers_reveal.png">
+* Second, highlight the text that you want to make public to hide everything else.
+<img width="479"  src="images/extension_text_reveal.png">
+* Click **Notarize**, you should see your notarization being processed:
+<img width="477"  src="images/extension_process.png">
+
+You can open the offscreen console and observe the browser extension logs by going to <chrome://extensions> -> 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**.
+
+<img width="477" src="images/extension_history.png">
+
+You also have the option to download the proof. You can view this proof later by using the **Verify** button or via <https://tlsnotary.github.io/proof_viz/>.
+
+## 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 <chrome://extensions/> 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
diff --git a/src/quick_start/images/extension_headers.png b/src/quick_start/images/extension_headers.png
diff --git a/src/quick_start/images/extension_headers_reveal.png b/src/quick_start/images/extension_headers_reveal.png
diff --git a/src/quick_start/images/extension_history.png b/src/quick_start/images/extension_history.png
diff --git a/src/quick_start/images/extension_install.png b/src/quick_start/images/extension_install.png
diff --git a/src/quick_start/images/extension_notarize.png b/src/quick_start/images/extension_notarize.png
diff --git a/src/quick_start/images/extension_pin.png b/src/quick_start/images/extension_pin.png
diff --git a/src/quick_start/images/extension_process.png b/src/quick_start/images/extension_process.png
diff --git a/src/quick_start/images/extension_proxy.png b/src/quick_start/images/extension_proxy.png
diff --git a/src/quick_start/images/extension_request.png b/src/quick_start/images/extension_request.png
diff --git a/src/quick_start/images/extension_requests.png b/src/quick_start/images/extension_requests.png
diff --git a/src/quick_start/images/extension_text_reveal.png b/src/quick_start/images/extension_text_reveal.png
diff --git a/src/quick_start/images/extension_twitter_requests.png b/src/quick_start/images/extension_twitter_requests.png
diff --git a/src/quick_start/images/extesnion_notarize_pending.png b/src/quick_start/images/extesnion_notarize_pending.png
diff --git a/src/quick_start/images/notary_certificate.png b/src/quick_start/images/notary_certificate.png
diff --git a/src/quick_start/images/notary_certificate_advanced.png b/src/quick_start/images/notary_certificate_advanced.png
diff --git a/src/quick_start/images/proof_viz.png b/src/quick_start/images/proof_viz.png
diff --git a/src/quick_start/images/run_vs_code.png b/src/quick_start/images/run_vs_code.png