Merge pull request #17 from tlsnotary/custom-extension

feat: add custom extension, minor fixes.

docs/intro.md

@@ -74,7 +74,7 @@ While TLSNotary can notarize publicly available data, it does not solve the "[or
 
 ## What TLS version does TLSNotary support?
 
-TLSNotary currently supports TLS 1.2. TLS 1.3 support will be added in 2024.
+TLSNotary currently supports TLS 1.2. Support for TLS 1.3 is on the roadmap.
 
 ## Who is behind TLSNotary?
 

docs/protocol/commit_strategy.md

@@ -25,4 +25,4 @@ The commitment strategies differ mainly in the number of committed ranges (`K`).
 | `Attestation` | Artifact signed by the `Notary` attesting to the authenticity of the plaintext from a TLS session | Constant     | `Attestation` only contains data that remains constant-sized regardless of `K`, e.g., the Merkle root of the commitments |
 | `Secret`      | Artifact containing secret data that correspond to commitments in `Attestation`                   | Linear       | `Secret` contains some data whose sizes scale linearly with `K`, e.g., a Merkle tree whose number of leaves equals `K`   |
 
-Using the default hash algorithm (i.e., BLAKE3), every additional range committed costs around 250 bytes of increment in the size of `Secret`. For more details, please visit this [Jupyter notebook](https://github.com/tlsnotary/landing-page/blob/docusaurus/docs/Protocol/commit_strategy.ipynb).
+Using the default hash algorithm (i.e., BLAKE3), every additional range committed costs around 250 bytes of increment in the size of `Secret`. For more details, please visit this [Jupyter notebook](https://github.com/tlsnotary/landing-page/blob/master/docs/protocol/commit_strategy.ipynb).

docs/protocol/custom_extension.md

@@ -0,0 +1,78 @@
+---
+sidebar_position: 5
+---
+
+# Custom Extensions
+
+Notary attestations can be extended with custom fields defined by the `Prover` or the `Notary`. This allows applications to attach additional data to attestations in a verifiable way.
+
+For now, the default notary server implementation only supports including custom data requested by the `Prover` in the attestation without any validation. In the future, a plugin system will allow developers to add custom logic to the notary server for adding or validating these data, without needing to modify the notary server code.
+
+## Use Cases
+
+- The `Prover` includes their public key to bind the attestation to their identity.
+- The `Notary` includes a TEE (Trusted Execution Environment) attestation to prove code integrity.
+- The `Prover` includes a nullifier to prevent reuse of the attestation.
+
+## Example
+
+The following demonstrates how to modify the [attestation example](https://github.com/tlsnotary/tlsn/blob/main/crates/examples/attestation/README.md) to include the `Prover`'s public key as a custom extension.
+
+### Prover
+
+The [attestation prover](https://github.com/tlsnotary/tlsn/blob/main/crates/examples/attestation/prove.rs) is modified as follows:
+
+```rust
+// ...
+
+let builder = RequestConfig::builder();
+
+builder.extension(Extension {
+    id: b"prover_public_key".to_vec(),
+    value: b"PUBLIC_KEY_PEM".to_vec(),
+});
+
+let request_config = builder.build()?;
+
+// ...
+```
+
+Note that the `Extension`'s `id` and `value` are both `Vec<u8>`, giving full control over the encoding format.
+
+### Notary
+
+The [Notary server](https://github.com/tlsnotary/tlsn/tree/main/crates/notary/server) must be started with `allow_extensions` enabled:
+
+```bash
+NS_NOTARIZATION__ALLOW_EXTENSIONS=true cargo run --release
+```
+
+Currently, the notary server does not support adding its own extensions or performing validations on extensions requested by the `Prover` out of the box. To do so, you’ll need to extend the notary server using the APIs outlined in the [API docs](https://tlsnotary.github.io/tlsn/tlsn_core/attestation/index.html#extensions).
+
+### Verifier
+
+The [attestation verifier](https://github.com/tlsnotary/tlsn/blob/main/crates/examples/attestation/verify.rs) can be modified to inspect extensions:
+
+```rust
+// ...
+
+let PresentationOutput {
+    server_name,
+    connection_info,
+    transcript,
+    mut extensions, // Optionally, verify any custom extensions from the prover or notary.
+    ..
+} = presentation.verify(&crypto_provider).unwrap();
+
+let Extension { id, value } = extensions.pop().unwrap();
+
+// Check the prover's public key.
+if id.as_slice() == b"prover_public_key" {
+    let public_key_pem = String::from_utf8(value).unwrap();
+    // ...
+}
+
+// ...
+```
+
+This allows the `Verifier` to confirm that the attestation is bound to the identity associated with the specified public key.

docs/protocol/server_identity_privacy.md

@@ -1,7 +1,7 @@
 ---
-sidebar_position: 5
+sidebar_position: 6
 ---
-# Server identity privacy
+# Server Identity Privacy
 
 To maximize `Prover` privacy, the server identity is not revealed to the `Verifier` by default. 
 The TLSNotary protocol mitigates the threat of a malicious `Verifier` attempting to infer the server identity from the messages they receive during MPC-TLS.