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.