From 95cc6a8ed1785e7fa73e518286001f5e78a80562 Mon Sep 17 00:00:00 2001 From: yuroitaki <25913766+yuroitaki@users.noreply.github.com> Date: Wed, 21 May 2025 12:21:10 +0800 Subject: [PATCH 1/5] Add custom extension, minor fixes. --- docs/intro.md | 2 +- docs/protocol/commit_strategy.md | 2 +- docs/protocol/custom_extension.md | 64 ++++++++++++++++++++++++ docs/protocol/server_identity_privacy.md | 4 +- 4 files changed, 68 insertions(+), 4 deletions(-) create mode 100644 docs/protocol/custom_extension.md diff --git a/docs/intro.md b/docs/intro.md index bb679dd..0f2ab28 100644 --- a/docs/intro.md +++ b/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? diff --git a/docs/protocol/commit_strategy.md b/docs/protocol/commit_strategy.md index c3e6f3f..60489d1 100644 --- a/docs/protocol/commit_strategy.md +++ b/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). diff --git a/docs/protocol/custom_extension.md b/docs/protocol/custom_extension.md new file mode 100644 index 0000000..02df6b5 --- /dev/null +++ b/docs/protocol/custom_extension.md @@ -0,0 +1,64 @@ +--- +sidebar_position: 5 +--- +# Custom Extension + +The attestation signed by the `Notary` can be extended with custom extensions to support application specific requirements. Both the `Prover` and `Notary` can be configured to include custom data, which can later be verified by the third-party `Verifier`. The `Notary` can also be configured to validate any extensions requested by the `Prover`. + +## Use Cases +- `Prover` includes their public key to bind it to their identity. +- `Notary` includes their TEE (trusted execution environment) attestation to prove code integrity. +- `Prover` includes a nullifier to prevent reuse of the attestation. + +## Example +The following modifies 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 `Extension`'s `id` and `value` are of `Vec`, which means one is free to choose their encoding format. + +### Notary +The [notary server](https://github.com/tlsnotary/tlsn/tree/main/crates/notary/server) is run with `allow_extensions` turned on. +```bash +NS_NOTARIZATION__ALLOW_EXTENSIONS=true cargo run --release +``` +Note that the notary server currently doesn't support adding its own extension, or performing custom validations on extensions from the `Prover`. To do that, the notary server needs to be modified by using the relevant 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) is modified as follows. +```rust +... + +let PresentationOutput { + server_name, + connection_info, + transcript, + mut extensions, // Optionally, verify any custom extensions from prover/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(); + ... +} + +... +``` +The `Verifier` can now be confident that the attestation is binded to the identity associated with this public key. + diff --git a/docs/protocol/server_identity_privacy.md b/docs/protocol/server_identity_privacy.md index 3a3a65c..aaf4a81 100644 --- a/docs/protocol/server_identity_privacy.md +++ b/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. From dd9df6d64d18fa5df3163a5b0050b84d4a1c4f00 Mon Sep 17 00:00:00 2001 From: Hendrik Eeckhaut Date: Wed, 21 May 2025 10:47:38 +0200 Subject: [PATCH 2/5] improvements --- docs/protocol/custom_extension.md | 40 ++++++++++++++++++++----------- 1 file changed, 26 insertions(+), 14 deletions(-) diff --git a/docs/protocol/custom_extension.md b/docs/protocol/custom_extension.md index 02df6b5..5877248 100644 --- a/docs/protocol/custom_extension.md +++ b/docs/protocol/custom_extension.md @@ -1,23 +1,28 @@ --- sidebar_position: 5 --- -# Custom Extension -The attestation signed by the `Notary` can be extended with custom extensions to support application specific requirements. Both the `Prover` and `Notary` can be configured to include custom data, which can later be verified by the third-party `Verifier`. The `Notary` can also be configured to validate any extensions requested by the `Prover`. +# Custom Extensions + +Notary attestations can be extended with custom fields defined by the `Prover`. This allows applications to attach additional data to attestations in a verifiable way. For now, the `Notary` simply includes these fields in the signed attestation without validation. In the future, a plugin system will allow developers to add custom logic to the `Notary` for verifying this data. Until then, such validation requires modifying the Notary code directly. ## Use Cases -- `Prover` includes their public key to bind it to their identity. -- `Notary` includes their TEE (trusted execution environment) attestation to prove code integrity. -- `Prover` includes a nullifier to prevent reuse of the attestation. + +- 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 modifies 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. + +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. + +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 { @@ -29,17 +34,23 @@ let request_config = builder.build()?; ... ``` -Note that `Extension`'s `id` and `value` are of `Vec`, which means one is free to choose their encoding format. + +Note that the `Extension`'s `id` and `value` are both `Vec`, giving full control over the encoding format. ### Notary -The [notary server](https://github.com/tlsnotary/tlsn/tree/main/crates/notary/server) is run with `allow_extensions` turned on. + +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 ``` -Note that the notary server currently doesn't support adding its own extension, or performing custom validations on extensions from the `Prover`. To do that, the notary server needs to be modified by using the relevant APIs outlined in the [API docs](https://tlsnotary.github.io/tlsn/tlsn_core/attestation/index.html#extensions). + +Currently, the notary server does not support adding its own extensions or performing validations on `Prover`-supplied extensions 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) is modified as follows. + +The [attestation verifier](https://github.com/tlsnotary/tlsn/blob/main/crates/examples/attestation/verify.rs) can be modified to inspect extensions: + ```rust ... @@ -47,11 +58,12 @@ let PresentationOutput { server_name, connection_info, transcript, - mut extensions, // Optionally, verify any custom extensions from prover/notary. + 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(); @@ -60,5 +72,5 @@ if id.as_slice() == b"prover_public_key" { ... ``` -The `Verifier` can now be confident that the attestation is binded to the identity associated with this public key. +This allows the `Verifier` to confirm that the attestation is bound to the identity associated with the specified public key. From 468dd8aa37651a8bf9cacea6d5e0c33eec925135 Mon Sep 17 00:00:00 2001 From: Hendrik Eeckhaut Date: Thu, 22 May 2025 09:24:01 +0200 Subject: [PATCH 3/5] Update docs/protocol/custom_extension.md Co-authored-by: yuroitaki <25913766+yuroitaki@users.noreply.github.com> --- docs/protocol/custom_extension.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/protocol/custom_extension.md b/docs/protocol/custom_extension.md index 5877248..0fc3354 100644 --- a/docs/protocol/custom_extension.md +++ b/docs/protocol/custom_extension.md @@ -45,7 +45,7 @@ The [Notary server](https://github.com/tlsnotary/tlsn/tree/main/crates/notary/se NS_NOTARIZATION__ALLOW_EXTENSIONS=true cargo run --release ``` -Currently, the notary server does not support adding its own extensions or performing validations on `Prover`-supplied extensions 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). +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 From c6618a5255b302f25ede133ffa0bad0ce28b2c2c Mon Sep 17 00:00:00 2001 From: yuroitaki <25913766+yuroitaki@users.noreply.github.com> Date: Mon, 26 May 2025 17:13:16 +0800 Subject: [PATCH 4/5] Modify intro. --- docs/protocol/custom_extension.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/protocol/custom_extension.md b/docs/protocol/custom_extension.md index 0fc3354..59df8b0 100644 --- a/docs/protocol/custom_extension.md +++ b/docs/protocol/custom_extension.md @@ -4,7 +4,9 @@ sidebar_position: 5 # Custom Extensions -Notary attestations can be extended with custom fields defined by the `Prover`. This allows applications to attach additional data to attestations in a verifiable way. For now, the `Notary` simply includes these fields in the signed attestation without validation. In the future, a plugin system will allow developers to add custom logic to the `Notary` for verifying this data. Until then, such validation requires modifying the Notary code directly. +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 From 4e472b27b06aae24a28bc5dcf267a721a8a4eaec Mon Sep 17 00:00:00 2001 From: yuroitaki <25913766+yuroitaki@users.noreply.github.com> Date: Tue, 27 May 2025 16:11:21 +0800 Subject: [PATCH 5/5] Add comment. --- docs/protocol/custom_extension.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/protocol/custom_extension.md b/docs/protocol/custom_extension.md index 59df8b0..8e83e81 100644 --- a/docs/protocol/custom_extension.md +++ b/docs/protocol/custom_extension.md @@ -23,7 +23,7 @@ The following demonstrates how to modify the [attestation example](https://githu The [attestation prover](https://github.com/tlsnotary/tlsn/blob/main/crates/examples/attestation/prove.rs) is modified as follows: ```rust -... +// ... let builder = RequestConfig::builder(); @@ -34,7 +34,7 @@ builder.extension(Extension { let request_config = builder.build()?; -... +// ... ``` Note that the `Extension`'s `id` and `value` are both `Vec`, giving full control over the encoding format. @@ -54,7 +54,7 @@ Currently, the notary server does not support adding its own extensions or perfo 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, @@ -69,10 +69,10 @@ 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.