restructure

book.toml

@@ -8,6 +8,7 @@ title = "tlsn-docs"
 [output.html]
 default-theme = "ayu"
 additional-css = ["src/css/katex.css", "src/css/global.css"]
+use-site-url-as-root = true
 
 [preprocessor.katex]
 after = ["links"]

src/SUMMARY.md

@@ -1,20 +1,25 @@
 # Summary
 
 [Introduction](./intro.md)
- [Protocol](./protocol/README.md)
-  - [Overview](./overview.md)
-  - [Notarization](./protocol/notarization/README.md)
-      - [TLS Handshake]()
-        - [Key Exchange](./protocol/notarization/key_exchange.md)
-        - [Symmetric key derivation](./protocol/notarization/prf.md)
-      - [Encryption](./protocol/notarization/encryption.md)
-      - [Commitment](./protocol/notarization/commitment.md)
-        - [Commitment to public data](./protocol/notarization/public_data_commitment.md)
-  - [Selective Disclosure]()
-  - [Secure 2-Party Computation](./protocol/2pc/garbled_circuits.md)
-    - [Garbled Circuits]()
-      - [Dual Execution with Asymmetric Privacy](./protocol/2pc/deap.md)
-    - [Oblivious Transfer]()
-    - [Paillier]()
-    - [MAC](./protocol/2pc/mac.md)
-    - [Finite-Field Arithmetic](./protocol/2pc/ff-arithmetic.md)
+[Protocol]()
+1. [Overview](./overview.md)
+2. [Notarization](./protocol/notarization/README.md)
+    - [TLS Handshake](./protocol/notarization/handshake.md)
+    - [Encryption and Decryption](./protocol/notarization/encryption.md)
+    - [Commitment](./protocol/notarization/commitment.md)
+    - [Signing](./protocol/notarization/signing.md)
+3. [Verification](./protocol/verification.md)
+4. [Selective Disclosure]()
+[MPC]()
+- [Garbled Circuits](./mpc/garbled_circuits.md)
+- [Dual Execution with Asymmetric Privacy](./mpc/deap.md)
+- [Oblivious Transfer]()
+- [MAC](./mpc/mac.md)
+- [Finite-Field Arithmetic](./mpc/ff-arithmetic.md)
+- [Encodings](./mpc/encodings.md)
+- [Key Exchange](./mpc/key_exchange.md)
+- [ECtF](./mpc/ectf.md)
+- [Commitment scheme](./mpc/commitment_scheme.md)
+- [Encryption](./mpc/encryption.md)
+- [TLS handhsake](./mpc/tls_handshake.md)
+

src/mpc/commitment_scheme.md

@@ -0,0 +1,9 @@
+# Commitment scheme
+
+// TODO will polish
+
+BEFORE the `Notary` "opens his gabled circuit" in Step 17 of [DEAP](/mpc/deap.md), the `User` commits (e.g. computes a blake3 hash) to the encodings of the plaintext generated by the `Notary` (i.e. the encoded output [v]_B from Step 8 in DEAP).
+
+"Opening the garbled circuit" simply means that the `Notary` reveals and signs the seed of randomness which (among other things) was used to generate the [encoding](/mpc/encodings.md) of the plaintext. 
+
+Having both the signed seed from the `Notary` and also the commitment to the plaintext encoding, the `User` can prove to any third-party Verifier the authenticity of the plaintext. 

src/mpc/deap.md

@@ -1,5 +1,12 @@
 # Dual Execution with Asymmetric Privacy
 
+TLSNotary uses the `DEAP` protocol described below to ensure malicious security during the Encryption and Decryption steps.
+
+When using DEAP in TLSNotary, the `User` plays the role of Alice and has full privacy and the `Notary` plays the role of Bob and reveals all of his private inputs after the TLS session with the server is over. (The Notary's private inputs are his TLS session key shares).
+
+The parties run the `Setup` and `Execution` steps of `DEAP` but they defer the `Equality Check`.
+Since during the `Equality Check` all of the Notary's secrets are revealed to User, it must be deferred until after the TLS session with the server is over, otherwise the User would learn the full TLS session keys and be able to forge the TLS transcript.
+
 ## Introduction
 
 Malicious secure 2-party computation with garbled circuits typically comes at the expense of dramatically lower efficiency compared to execution in the semi-honest model. One technique, called Dual Execution [[MF06]](https://www.iacr.org/archive/pkc2006/39580468/39580468.pdf) [[HKE12]](https://www.cs.umd.edu/~jkatz/papers/SP12.pdf), achieves malicious security with a minimal 2x overhead. However, it comes with the concession that a malicious adversary may learn $k$ bits of the other's input with probability $2^{-k}$.

src/mpc/ectf.md

@@ -0,0 +1,4 @@
+# ECtF
+
+This protocol enables the User and the Notary to convert their shares of an ECDH secret into shares of the pre-master secret (PMS).
+

src/mpc/encodings.md

@@ -0,0 +1,3 @@
+# Encodings
+
+// Explain here how each input/output/intermediate wire in GC can have value either 0 or 1 and a random 128-bit value encodes that wire value

src/mpc/encryption.md

@@ -0,0 +1,74 @@
+# Encryption
+
+Here we will explain our protocol for 2PC encryption using a block cipher in counter-mode.
+
+Our documentation on [Dual Execution with Asymmetric Privacy](/mpc/deap.md) is recommended prior reading for this section.
+
+## Preliminary
+
+### Ephemeral Keyshare
+
+It is important to recognise that the Notary's keyshare is an _ephemeral secret_. It is only private for the duration of the User's TLS session, after which the User is free to learn it without affecting the security of the protocol.
+
+It is this fact which allows us to achieve malicious security for relatively low cost. More details on this [here](/mpc/deap.md).
+
+### Premature Leakage
+
+A small amount of undetected premature keyshare leakage is quite tolerable. For example, if the Notary leaks 3 bits of their keyshare, it gives the User no meaningful advantage in any attack, as she could have simply guessed the bits correctly with $2^{-3} = 12.5\%$ probability and mounted the same attack. Assuming a sufficiently long cipher key is used, eg. 128 bits, this is not a concern.
+
+The equality check at the end of our protocol ensures that premature leakage is detected with a probability of $1 - 2^{-k}$ where k is the number of leaked bits. The Notary is virtually guaranteed to detect significant leakage and can abort prior to notarization.
+
+### Plaintext Leakage
+
+Our protocol assures _no leakage_ of the plaintext to the Notary during both encryption and decryption. The Notary reveals their keyshare at the end of the protocol, which allows the Notary to open their garbled circuits and oblivious transfers completely to the User. The User can then perform a series of consistency checks to ensure that the Notary behaved honestly. Because these consistency checks do not depend on any inputs of the User, aborting does not reveal any sensitive information (in contrast to standard DualEx which does).
+
+### Integrity
+
+During the entirety of the TLS session the User performs the role of the garbled circuit generator, thus ensuring that a malicious Notary can not corrupt or otherwise compromise the integrity of messages sent to/from the Server.
+
+### Notation
+
+* $p$ is one block of plaintext
+* $c$ is the corresponding block of ciphertext, ie $c = \mathsf{Enc}(k, ctr) \oplus p$
+* $k$ is the cipher key
+* $ctr$ is the counter block
+* $k_U$ and $k_N$ denote the User and Notary cipher keyshares, respectively, where $k = k_U \oplus k_N$
+* $z$ is a mask randomly selected by the User
+* $ectr$ is the encrypted counter-block, ie $ectr = \mathsf{Enc}(k, ctr)$
+* $\mathsf{Enc}$ denotes the block cipher used by the TLS session
+* $\mathsf{com}_x$ denotes a binding commitment to the value $x$
+* $[x]_A$ denotes a garbled encoding of $x$ chosen by party $A$
+
+## Encryption Protocol
+
+The encryption protocol uses [DEAP](/mpc/deap.md) without any special variations. The User and Notary directly compute the ciphertext for each block of a message the User wishes to send to the Server:
+
+$$f(k_U, k_N, ctr, p) = \mathsf{Enc}(k_U \oplus k_N, ctr) \oplus p = c$$
+
+The User creates a commitment to the plaintext active labels for the Notary's circuit $\mathsf{Com}([p]_N, r) = \mathsf{com}_{[p]_N}$ where $r$ is a random key known only to the User. The User sends this commitment to the Notary to be used in the authdecode protocol later. It's critical that the User commits to $[p]_N$ prior to the Notary revealing $\Delta$ in the final phase of DEAP. This ensures that if $\mathsf{com}_{[p]_N}$ is a commitment to valid labels, then it must be a valid commitment to the plaintext $p$. This is because learning the complementary wire label for any bit of $p$ prior to learning $\Delta$ is virtually impossible.
+
+## Decryption Protocol
+
+The protocol for decryption is very similar but has some key differences to encryption.
+
+For decryption, [DEAP](/mpc/deap.md) is used for every block of the ciphertext to compute the _masked encrypted counter-block_:
+
+$$f(k_U, k_N, ctr, z) = \mathsf{Enc}(k_U \oplus k_N, ctr) \oplus z = ectr_z$$
+
+This mask $z$, chosen by the User, hides $ectr$ from the Notary and thus the plaintext too. Conversely, the User can simply remove this mask in order to compute the plaintext $p = c \oplus ectr_z \oplus z$.
+
+Following this, the User can retrieve the wire labels $[p]_N$ from the Notary using OT.
+
+Similarly to the procedure for encryption, the User creates a commitment $\mathsf{Com}([p]_N, r) = \mathsf{com}_{[p]_N}$ where $r$ is a random key known only to the User. The User sends this commitment to the Notary to be used in the authdecode protocol later.
+
+### Proving the validity of $[p]_N$
+
+In addition to computing the masked encrypted counter-block, the User must also prove that the labels $[p]_N$ they chose afterwards actually correspond to the ciphertext $c$ sent by the Server.
+
+This is can be done efficiently in one execution using the zero-knowledge protocol described in [[JKO13]](https://eprint.iacr.org/2013/073.pdf) the same as we do in the final phase of DEAP.
+
+The Notary garbles a circuit $G_N$ which computes:
+
+$$p \oplus ectr = c$$
+
+Notice that the User and Notary will already have computed $ectr$ when they computed $ectr_z$ earlier. Conveniently, the Notary can re-use the garbled labels $[ectr]_N$ as input labels for this circuit. For more details on the reuse of garbled labels see [[AMR17]](https://eprint.iacr.org/2017/062.pdf).

src/mpc/tls_handshake.md

@@ -0,0 +1,16 @@
+# TLS handshake
+
+During the TLS handshake the TLS Client and the TLS Server compute the session keys needed to perform the encryption and decryption of data.
+
+In TLSNotary protocol `User` and `Notary` jointly play the role of the TLS Client. They use MPC to compute the session keys in such a way that neither party ever learns the full keys but each has their share of the keys.
+
+
+First they compute their shares of the TLS Client's ECDH secret using [this protocol](/mpc/key_exchange.md). Since an ECDH secret is an EC point, the parties have their shares of that point.
+
+Then they compute their shares of the pre-master secret (PMS) using an MPC protocol described [here](/mpc/ectf.md).
+
+Then the parties input their PMS shares as private inputs to the [DEAP](/mpc/deap.md) protocol (along with some other public data). They perform the following in MPC: 
+
+- they derive their shares of the TLS session keys
+- they encrypt the Client Finished message (and the `User` sends the CF to the server)
+- (the `User` receives the Server Finished message from the server and) they decrypt the SF message and check its authenticity.

src/outdated/commitment.md

@@ -0,0 +1,7 @@
+At the end of the TLSNotary protocol, the User has the authenticated AES ciphertext which can be thought of as a commitment to the plaintext. This form of commitment is not amenable to use cases when the User wants to make part of the plaintext public while keeping another part private. Naively, the User's option is to prove the decryption of the ciphertext in zero-knowledge which is computationally expensive.
+
+We describe two less computationally heavy approaches for converting the AES ciphertext commitments. 
+
+The first approach is useful for commitments to the data which the User intends to make public. It is based on decrypting the ciphertext with Garbled Circuits and producing a hash commitment to the wire labels.
+
+The second approach is useful for commitments to the private data which the User later intends to prove statements about in zero-knowledge. This approach produces a Poseidon hash over the private data. 

src/protocol/README.md

@@ -1 +0,0 @@
-# Protocol

src/protocol/notarization/commitment.md

@@ -1,9 +1,8 @@
 # Commitment
 
-At the end of the TLSNotary protocol, the User has the authenticated AES ciphertext which can be thought of as a commitment to the plaintext. This form of commitment is not amenable to use cases when the User wants to make part of the plaintext public while keeping another part private. Naively, the User's option is to prove the decryption of the ciphertext in zero-knowledge which is computationally expensive.
+The TLSNotary protocol completely hides the plaintext transcript from the `Notary`. At the same time we want to have a way for the `User` to selectively prove the authenticity of arbitrary portions of the plaintext to the `Verifier`.
 
-We describe two less computationally heavy approaches for converting the AES ciphertext commitments. 
+Naively, we could extend the above `Encryption and Decryption` steps to also compute a commitment (e.g. a blake3 hash) to the plaintext in MPC and have the `Notary` sign that commitment. Then the `User` could open the commitment to the `Verifier`. Unfortunately such approach would be resource-heavy, and so we provide a more lightweight commitment scheme.
 
-The first approach is useful for commitments to the data which the User intends to make public. It is based on decrypting the ciphertext with Garbled Circuits and producing a hash commitment to the wire labels.
-
-The second approach is useful for commitments to the private data which the User later intends to prove statements about in zero-knowledge. This approach produces a Poseidon hash over the private data. 
+The high-level idea is that the `User` will reuse the encodings from the MPC protocol used for `Encryption and Decryption` to create commitments (see here for low-level details). Since those encodings are chosen by the `Notary` and are not known to the `User` at the time when she makes a commitment, they can be thought of as "authenticated plaintext".
+For technical details on the commitment scheme, see [Commitment scheme](/mpc/commitment_scheme.md)

src/protocol/notarization/encryption.md

@@ -1,74 +1,33 @@
-# Encryption
+# Encryption and Decryption (and MAC computation)
 
-Here we will explain our protocol for 2PC encryption using a block cipher in counter-mode.
+Here we explain how the `User` and the `Notary` use MPC to encrypt the data for the server and also how they decrypt the data received from the server. They also compute the MAC for the ciphertext in MPC.
 
-Our documentation on [Dual Execution with Asymmetric Privacy](../2pc/deap.md) is recommended prior reading for this section.
+## Encryption
 
-## Preliminary
+In order to encrypt the plaintext, the parties input their key shares as private inputs to the [MPC](/mpc/deap.md) protocol (along with some other public data). Additionally, the `User` inputs her plaintext as a private input.
 
-### Ephemeral Keyshare
+Both parties learn the resulting ciphertext and they proceed to run an [MPC](/mpc/mac.md) protocol to compute the MAC for the ciphertext.
 
-It is important to recognise that the Notary's keyshare is an _ephemeral secret_. It is only private for the duration of the User's TLS session, after which the User is free to learn it without affecting the security of the protocol.
+The User sends the ciphertext with the MAC to the server.
 
-It is this fact which allows us to achieve malicious security for relatively low cost. More details on this [here](../2pc/deap.md).
+As we explain in the [Commitment section](/protocol/notarization/commitment.md), the `User` creates a commitment to the plaintext (her private input to MPC).
 
-### Premature Leakage
 
-A small amount of undetected premature keyshare leakage is quite tolerable. For example, if the Notary leaks 3 bits of their keyshare, it gives the User no meaningful advantage in any attack, as she could have simply guessed the bits correctly with $2^{-3} = 12.5\%$ probability and mounted the same attack. Assuming a sufficiently long cipher key is used, eg. 128 bits, this is not a concern.
+## Decryption
 
-The equality check at the end of our protocol ensures that premature leakage is detected with a probability of $1 - 2^{-k}$ where k is the number of leaked bits. The Notary is virtually guaranteed to detect significant leakage and can abort prior to notarization.
+After the `User` receives the ciphertext with the associated MAC from the server, the parties first authenticate the ciphertext by checking if MAC is valid. They do it by running an [MPC] (/mpc/mac.md) protocol to compute the authentic MAC for the ciphertext. Then they check if the authentic MAC matches the MAC received from the server.
 
-### Plaintext Leakage
+The parties then decrypt the ciphertext by inputting their key shares as private inputs to the [MPC](/mpc/deap.md) protocol (along with the ciphertext and some other public data).
 
-Our protocol assures _no leakage_ of the plaintext to the Notary during both encryption and decryption. The Notary reveals their keyshare at the end of the protocol, which allows the Notary to open their garbled circuits and oblivious transfers completely to the User. The User can then perform a series of consistency checks to ensure that the Notary behaved honestly. Because these consistency checks do not depend on any inputs of the User, aborting does not reveal any sensitive information (in contrast to standard DualEx which does).
+The resulting plaintext is revealed ONLY to the User.
 
-### Integrity
+As we explain in the [Commitment section](/protocol/notarization/commitment.md), the `User` creates a commitment to the plaintext. 
 
-During the entirety of the TLS session the User performs the role of the garbled circuit generator, thus ensuring that a malicious Notary can not corrupt or otherwise compromise the integrity of messages sent to/from the Server.
+Note that the actual low-level details of implementation of `Decryption` are more nuanced than what we described here. Please consult the [Low-level Decryption details](/mpc/encryption.md) for more information.
 
-### Notation
 
-* $p$ is one block of plaintext
-* $c$ is the corresponding block of ciphertext, ie $c = \mathsf{Enc}(k, ctr) \oplus p$
-* $k$ is the cipher key
-* $ctr$ is the counter block
-* $k_U$ and $k_N$ denote the User and Notary cipher keyshares, respectively, where $k = k_U \oplus k_N$
-* $z$ is a mask randomly selected by the User
-* $ectr$ is the encrypted counter-block, ie $ectr = \mathsf{Enc}(k, ctr)$
-* $\mathsf{Enc}$ denotes the block cipher used by the TLS session
-* $\mathsf{com}_x$ denotes a binding commitment to the value $x$
-* $[x]_A$ denotes a garbled encoding of $x$ chosen by party $A$
 
-## Encryption Protocol
+To summarize:
 
-The encryption protocol uses [DEAP](../2pc/deap.md) without any special variations. The User and Notary directly compute the ciphertext for each block of a message the User wishes to send to the Server:
-
-$$f(k_U, k_N, ctr, p) = \mathsf{Enc}(k_U \oplus k_N, ctr) \oplus p = c$$
-
-The User creates a commitment to the plaintext active labels for the Notary's circuit $\mathsf{Com}([p]_N, r) = \mathsf{com}_{[p]_N}$ where $r$ is a random key known only to the User. The User sends this commitment to the Notary to be used in the authdecode protocol later. It's critical that the User commits to $[p]_N$ prior to the Notary revealing $\Delta$ in the final phase of DEAP. This ensures that if $\mathsf{com}_{[p]_N}$ is a commitment to valid labels, then it must be a valid commitment to the plaintext $p$. This is because learning the complementary wire label for any bit of $p$ prior to learning $\Delta$ is virtually impossible.
-
-## Decryption Protocol
-
-The protocol for decryption is very similar but has some key differences to encryption.
-
-For decryption, [DEAP](../2pc/deap.md) is used for every block of the ciphertext to compute the _masked encrypted counter-block_:
-
-$$f(k_U, k_N, ctr, z) = \mathsf{Enc}(k_U \oplus k_N, ctr) \oplus z = ectr_z$$
-
-This mask $z$, chosen by the User, hides $ectr$ from the Notary and thus the plaintext too. Conversely, the User can simply remove this mask in order to compute the plaintext $p = c \oplus ectr_z \oplus z$.
-
-Following this, the User can retrieve the wire labels $[p]_N$ from the Notary using OT.
-
-Similarly to the procedure for encryption, the User creates a commitment $\mathsf{Com}([p]_N, r) = \mathsf{com}_{[p]_N}$ where $r$ is a random key known only to the User. The User sends this commitment to the Notary to be used in the authdecode protocol later.
-
-### Proving the validity of $[p]_N$
-
-In addition to computing the masked encrypted counter-block, the User must also prove that the labels $[p]_N$ they chose afterwards actually correspond to the ciphertext $c$ sent by the Server.
-
-This is can be done efficiently in one execution using the zero-knowledge protocol described in [[JKO13]](https://eprint.iacr.org/2013/073.pdf) the same as we do in the final phase of DEAP.
-
-The Notary garbles a circuit $G_N$ which computes:
-
-$$p \oplus ectr = c$$
-
-Notice that the User and Notary will already have computed $ectr$ when they computed $ectr_z$ earlier. Conveniently, the Notary can re-use the garbled labels $[ectr]_N$ as input labels for this circuit. For more details on the reuse of garbled labels see [[AMR17]](https://eprint.iacr.org/2017/062.pdf).
+We showed above how the Notary and User work together to encrypt and decrypt data. The Notary does it "blindly", without learning the plaintext. In fact, the Notary does not even know which server the User is communicating with.
+Additionally, the User created commitments to the plaintext and will be able to later prove the plaintext authenticity to a third party.

src/protocol/notarization/handshake.md

@@ -0,0 +1,13 @@
+# TLS handshake
+
+During the TLS handshake the TLS Client and the TLS Server compute the session keys needed to perform the encryption and decryption of data.
+
+In TLSNotary protocol `User` and `Notary` jointly play the role of the TLS Client. The User is the one who physically communicates with the server but all cryptographic TLS operations are performed in MPC.
+The parties use MPC to compute the session keys in such a way that neither party ever learns the full keys but each has their share of the keys.
+They then use their shares of the keys to finish the TLS handshake.
+
+To a third party who observes the `User`'s connection to the server, the connection looks like a regular TLS connection. The `User` maintains all the security guarantees of a regular TLS connection against a third-party bad actor.
+
+However, the `User`'s TLS connection does not maintain the normal TLS security against the `Notary`. Instead, the `User` relies on the security which the underlying MPC protocols provide.
+
+With the shares of the session keys computed, the parties now proceed to the next MPC protocol where they use their session key shares to jointly encrypt requests to and decrypt responses from the server while keeping the plaintext of the request/response private from the Notary.

src/protocol/notarization/signing.md

@@ -0,0 +1,16 @@
+# Signing the session header.
+
+The `Notary` signs the following artifacts called the `Session Header` which are required for the `User` to prove to a third-party `Verifier` the authenticity of the plaintext from the TLS session.
+We emphasize that throughout the whole TLSNotary protocol, the `Notary` never learns the plaintext neither learns what domain the `User` communicates with.
+
+// taken from tlsn/tlsn-core/src/session/header.rs
+
+// TODO: will explain the meaning of each
+
+- encoder_seed:  
+- merkle_root
+- sent_len
+- recv_len
+- time
+- server_public_key
+- handshake_commitment

src/protocol/verification.md

@@ -0,0 +1,31 @@
+# Verification
+
+A `Verifier`` receives the following from the `User`:
+
+// TODO will explain each
+
+- domain name (e.g. "tlsnotary.org")
+- signed `Session Header`
+- openings to the commitments (the plaintext which the User committed to)
+- handshake_data which consists of:
+ - server certificate
+ - key exchange details
+ - client and server random
+
+and performs the following steps to verify the commitments:
+
+// you can see these steps in tlsn/tlsn-core/tests/api.rs
+
+- verify that `Session Header` was signed by the Notary
+- verify handshake_data against handshake_commitment
+- verify validity of `server certificate` for the `domian name`
+- verify that `key exchange details` were signed by `server certificate`
+
+- use encoder_seed to re-generate encodings and re-create a commitment for the opening plaintext 
+(maybe this step needs to be spelled out in more detail)
+- use `merkle_root` to check that this re-created commitment is in the Merkle tree
+
+
+To summarize: the `Verifier` will only learn those portions of the TLS session transcript which the `User` chose to reveal. The portions which were not revealed (`User`'s private data) will appear to the `Verifier` as redacted. Here is an example of what the `Verifier` output may look like:
+
+// paste here a picture of an HTTP request with redacted fields