From b717533e2ac3e536957c665fdb23c7b1153f1298 Mon Sep 17 00:00:00 2001 From: Denise Pena Date: Wed, 18 Sep 2024 09:40:49 -0500 Subject: [PATCH 01/27] Initial file set up --- src/content/products/key-transparency.yaml | 21 +++++++++++++++++++++ src/icons/key-transparency.svg | 1 + 2 files changed, 22 insertions(+) create mode 100644 src/content/products/key-transparency.yaml create mode 100644 src/icons/key-transparency.svg diff --git a/src/content/products/key-transparency.yaml b/src/content/products/key-transparency.yaml new file mode 100644 index 000000000000000..7645e2a8ecf2009 --- /dev/null +++ b/src/content/products/key-transparency.yaml @@ -0,0 +1,21 @@ +name: Key Transparency + +product: + title: Key Transparency + url: /key-transparency/ + group: Application security + +meta: + title: Key Transparency + description: + Key Transparency docs + author: "@cloudflare" + +externals: + - title: Cloudflare homepage + url: https://cloudflare.com + +algolia: + index: TEST - Re-dev docs + apikey: 4edb0a6cef3338ff4bcfbc6b3d2db56b + product: security-center diff --git a/src/icons/key-transparency.svg b/src/icons/key-transparency.svg new file mode 100644 index 000000000000000..ef28eea7ce34632 --- /dev/null +++ b/src/icons/key-transparency.svg @@ -0,0 +1 @@ + \ No newline at end of file From 261b36029e7a1b38e70a768551a5dd0d4d410c59 Mon Sep 17 00:00:00 2001 From: Denise Pena Date: Wed, 18 Sep 2024 09:41:00 -0500 Subject: [PATCH 02/27] Added rest of nav items --- .../docs/key-transparency/auditor/index.mdx | 39 +++++++++++++++++++ src/content/docs/key-transparency/index.mdx | 20 ++++++++++ .../key-transparency/namespaces/index.mdx | 4 ++ .../docs/key-transparency/reports/index.mdx | 4 ++ .../key-transparency/verify-epochs/index.mdx | 4 ++ 5 files changed, 71 insertions(+) create mode 100644 src/content/docs/key-transparency/auditor/index.mdx create mode 100644 src/content/docs/key-transparency/index.mdx create mode 100644 src/content/docs/key-transparency/namespaces/index.mdx create mode 100644 src/content/docs/key-transparency/reports/index.mdx create mode 100644 src/content/docs/key-transparency/verify-epochs/index.mdx diff --git a/src/content/docs/key-transparency/auditor/index.mdx b/src/content/docs/key-transparency/auditor/index.mdx new file mode 100644 index 000000000000000..69463d54f001207 --- /dev/null +++ b/src/content/docs/key-transparency/auditor/index.mdx @@ -0,0 +1,39 @@ +--- +pcx_content_type: overview +title: Auditor +--- + +The auditor is designed to sign epoch information, which includes the timestamp seen by the auditor, epoch number, and epoch digest. The auditor serialises this information in binary using protobuf or bincode and checks whether the requested inclusion is valid, as in not seen, and incremental. + +## Get auditor information + +`keys` contain auditor public keys which allow for key rotation later. Currently, keys can be reotated upon request. + +```sh +curl 'https://plexi-staging.research.cloudflare.com/info' +{ + "keys": [ + { + "public_key": "d1036a33a8731e82a29dc68210988b32b60b7c1bd22d2341f2e339f4db3a2f4a", + "not_before": 1712311441501 + } + ], + "logs": [ + "508607faff7cb16be841e901eca41a6239461f239e7e610c9ea2576f334bc144" + ] +} +``` + +## Reset the auditor + +Resetting the auditor removes existing signatures and allows clients to test behavior at initialization. + +```sh +curl 'https://plexi-staging.research.cloudflare.com/namespaces' +{ + "namespaces": [ + { "name": "whatsapp-2024", "public": true, "root": "1/abc", "reports_uri": "/namespaces//whatsapp-2024/reports", "audits_uri": "/namespaces/whatsapp-2024/audits", "log_directory": "https://meta.com/.well-known/key-transparency-log-directory", "status": "online" }, + { "name": "meta-bt-2024", "public": true, "reports_uri": "/namespaces/meta-bt-2024/reports", "audits_uri": "/namespaces/meta-bt-2024/audits", "status": "initialization" } + ] +} +``` diff --git a/src/content/docs/key-transparency/index.mdx b/src/content/docs/key-transparency/index.mdx new file mode 100644 index 000000000000000..a2998875e2c79cc --- /dev/null +++ b/src/content/docs/key-transparency/index.mdx @@ -0,0 +1,20 @@ +--- +title: Overview +pcx_content_type: overview +sidebar: + order: 1 +head: + - tag: title + content: Key Transparency + +--- + +import { CardGrid, Description, Feature, LinkTitleCard } from "~/components" + + + +Ensure the transparency of end-to-end encrypted messaging conversations. + + + +Cloudflare verifies key transparency audit proofs to ensure the transparency of end-to-end encrypted messaging conversations without the use of QR codes. \ No newline at end of file diff --git a/src/content/docs/key-transparency/namespaces/index.mdx b/src/content/docs/key-transparency/namespaces/index.mdx new file mode 100644 index 000000000000000..0f022926cdc5ad4 --- /dev/null +++ b/src/content/docs/key-transparency/namespaces/index.mdx @@ -0,0 +1,4 @@ +--- +pcx_content_type: overview +title: Namespaces +--- \ No newline at end of file diff --git a/src/content/docs/key-transparency/reports/index.mdx b/src/content/docs/key-transparency/reports/index.mdx new file mode 100644 index 000000000000000..2c5ab6473f0dfd1 --- /dev/null +++ b/src/content/docs/key-transparency/reports/index.mdx @@ -0,0 +1,4 @@ +--- +pcx_content_type: overview +title: Reports +--- \ No newline at end of file diff --git a/src/content/docs/key-transparency/verify-epochs/index.mdx b/src/content/docs/key-transparency/verify-epochs/index.mdx new file mode 100644 index 000000000000000..a478f531fbb5d9e --- /dev/null +++ b/src/content/docs/key-transparency/verify-epochs/index.mdx @@ -0,0 +1,4 @@ +--- +pcx_content_type: overview +title: Verify epochs +--- \ No newline at end of file From 732e0d7ece8032fa524395467a3e916d57f73280 Mon Sep 17 00:00:00 2001 From: Denise Pena Date: Wed, 18 Sep 2024 13:13:42 -0500 Subject: [PATCH 03/27] Added namespace content --- .../key-transparency/namespaces/index.mdx | 77 ++++++++++++++++++- 1 file changed, 76 insertions(+), 1 deletion(-) diff --git a/src/content/docs/key-transparency/namespaces/index.mdx b/src/content/docs/key-transparency/namespaces/index.mdx index 0f022926cdc5ad4..6c204150b8dc4d3 100644 --- a/src/content/docs/key-transparency/namespaces/index.mdx +++ b/src/content/docs/key-transparency/namespaces/index.mdx @@ -1,4 +1,79 @@ --- pcx_content_type: overview title: Namespaces ---- \ No newline at end of file +--- + +## Create a namespace + +The following fields are required when making a `POST` request: + +- `name` +- `public` +- `root` +- `signature_version` + +The `log_directory` field is optional but is the URL used to retrieve the log public key. + +```sh +curl --request POST 'https://plexi-staging.research.cloudflare.com/namespaces' \ + --header 'Content-Type: application/json' \ + --data '{ + "name": "whatsapp-2024", + "public": true, + "root": "1/1111111111111111111111111111111111111111111111111111111111111111", + "log_directory": "https://meta.com/.well-known/key-transparency-log-directory", + "signature_version": 2 + }' +{ + "name": "whatsapp-2024", + "public": true, + "log_directory": "https://meta.com/.well-known/key-transparency-log-directory", + "root": "1/1111111111111111111111111111111111111111111111111111111111111111", + "status": "Initialization", + "reports_uri": "/namespaces/whatsapp-2024/reports", + "audits_uri": "/namespaces/whatsapp-2024/audits", + "signature_version": 2 +} +``` + +After publishing the first epoch, `status` will show `Online`. Possible statuses include: +- `Online` +- `Initialization` +- `Disabled` + +## List all namespaces + +Refer to the exmaple below to get information about all public namespaces. + +```sh +curl 'https://plexi-staging.research.cloudflare.com/namespaces' +{ + "namespaces": [ + { "name": "whatsapp-2024", "public": true, "root": "1/abc", "reports_uri": "/namespaces//whatsapp-2024/reports", "audits_uri": "/namespaces/whatsapp-2024/audits", "log_directory": "https://meta.com/.well-known/key-transparency-log-directory", "status": "online" }, + { "name": "meta-bt-2024", "public": true, "reports_uri": "/namespaces/meta-bt-2024/reports", "audits_uri": "/namespaces/meta-bt-2024/audits", "status": "initialization" } + ] +} +``` + +## Disable a namespace + +If a log state has been corrupted, lost, or needs to be sharded to be maintainbale, the auditor allows the Log operator to mark a namespace as `Disabled`. + + +```sh +curl -X PATCH 'https://plexi-staging.research.cloudflare.com/namespaces/{namespace}' \ + -H 'Content-Type: application/json' \ + -d '{ + "status": "Disabled" + }' +{ + "name": "whatsapp-2024", + "public": true, + "log_directory": "https://meta.com/.well-known/key-transparency-log-directory", + "root": "1/1111111111111111111111111111111111111111111111111111111111111111", + "status": "Disabled", + "reports_uri": "/namespaces/whatsapp-2024/reports", + "audits_uri": "/namespaces/whatsapp-2024/audits", + "signature_version": 2 +} +``` \ No newline at end of file From 00c33cf26aa02f2ae13bcde04f660f041046bcb5 Mon Sep 17 00:00:00 2001 From: Denise Pena Date: Wed, 18 Sep 2024 15:45:37 -0500 Subject: [PATCH 04/27] Added epochs content --- .../key-transparency/verify-epochs/index.mdx | 54 ++++++++++++++++++- 1 file changed, 53 insertions(+), 1 deletion(-) diff --git a/src/content/docs/key-transparency/verify-epochs/index.mdx b/src/content/docs/key-transparency/verify-epochs/index.mdx index a478f531fbb5d9e..a38a32ae59a3073 100644 --- a/src/content/docs/key-transparency/verify-epochs/index.mdx +++ b/src/content/docs/key-transparency/verify-epochs/index.mdx @@ -1,4 +1,56 @@ --- pcx_content_type: overview title: Verify epochs ---- \ No newline at end of file +sidebar: + order: 3 +--- + +## Publish a new epoch + +Refer to the example below to publish a new epoch by requesting its signature. + +```sh +curl 'https://plexi-staging.research.cloudflare.com/namespaces/{namespace}/audits' \ + --header 'Content-Type: application/json' \ + --data '{"epoch": 1, "digest": "1111111111111111111111111111111111111111111111111111111111111111"}' +{ + "namespace": "whatsapp-2024", + "timestamp": 1717084639921, + "epoch": 1, + "digest": "1111111111111111111111111111111111111111111111111111111111111111", + "signature": "f6a51443bb6703813b330959d9d97471bc06464142165e59733fa102a18b052782a5307d59c31b8b13c1af7dfff6f6e7bf44e880d44e26e96c50a72f72a30c07", + "key_id": 74, +} +``` + +### Constraints + +- If `root` is defined for the namespace, the first epoch must match it (number and digest). +- Epochs must be increasing. Second epoch is 2, third is 3, etc. +- Epochs must have a unique digest or it will be rejected. +- Epochs cannot be republished. +- Digest must be a 32 byte string hex encoded (length 64). + +If a namespace is disabled, you receive the following error: + +```txt +HTTP 400 Bad Request +Namespace is disabled and read-only. +``` + +:::note +Avoid publishing more than 100 epochs as reset might not work beyond this threshold. +::: + +## Get an epoch + +```sh +curl 'https://plexi-staging.research.cloudflare.com/namespaces/{namespace}/audits/1' +{ + "namespace": "whatsapp-2024", + "timestamp": 1717084639921,~ + "epoch": 1, + "digest": "1111111111111111111111111111111111111111111111111111111111111111", + "signature": "f6a51443bb6703813b330959d9d97471bc06464142165e59733fa102a18b052782a5307d59c31b8b13c1af7dfff6f6e7bf44e880d44e26e96c50a72f72a30c07" +} +``` \ No newline at end of file From fee02b59fb59aecef73a11da948edd0e48d624c6 Mon Sep 17 00:00:00 2001 From: Denise Pena Date: Wed, 18 Sep 2024 15:46:28 -0500 Subject: [PATCH 05/27] Added reports content --- .../docs/key-transparency/reports/index.mdx | 63 ++++++++++++++++++- 1 file changed, 62 insertions(+), 1 deletion(-) diff --git a/src/content/docs/key-transparency/reports/index.mdx b/src/content/docs/key-transparency/reports/index.mdx index 2c5ab6473f0dfd1..8389ba3007a1439 100644 --- a/src/content/docs/key-transparency/reports/index.mdx +++ b/src/content/docs/key-transparency/reports/index.mdx @@ -1,4 +1,65 @@ --- pcx_content_type: overview title: Reports ---- \ No newline at end of file +sidebar: + order: 4 +--- + +## Verify a signature + +1. Install the `plexi` cli. + +```sh +# Email thibault@cloudflare.com for access +git clone git@github.com:cloudflare/plexi.git && cd plexi +cargo install plexi --path . +``` + +2. Verify the signature locally. + +```sh +AUDITOR_PUBLIC_KEY="$(curl -sS 'https://plexi-staging.research.cloudflare.com/info' | jq -r '.keys[0].public_key')" +curl -sS 'https://plexi-staging.research.cloudflare.com/namespaces/{namespace}/audits/1' | \ + plexi verify --namespace {namespace} --publickey "${AUDITOR_PUBLIC_KEY}" + +Signature valid +``` + +## Get all reports + +A report is a signature over (timestamp, epoch, digest) by the Log which has not been seen by the auditor. This means the Log is trying to bypass the auditor validation. + + +```sh +curl 'https://plexi-staging.research.cloudflare.com/namespaces/{namespace}/reports' +[ + { + "id": "f7837d1c-fa0f-404f-ab40-5337a38d330e", + "report": { + "namespace": "{namespace}", + "timestamp": 1712588155604, + "epoch": 2, + "digest": "2222222222222222222222222222222222222222222222222222222222222222", + "signature": "f5533adbe1ce96c20d2bf20a0a052ca4e3e5670cd7888e1b9088523ba704c94c22942ce61d385158f241f3a56871b88d962a63c7b2f6eb92b66567898762f007" + } + } +] +``` + +## Submit a report + +```sh +curl 'https://plexi-staging.research.cloudflare.com/namespaces/{namespace}/reports' \ + --header 'Content-Type: application/json' \ + --data '{"namespace":"{namespace}","timestamp":1712588155604,"epoch":2,"digest":"2222222222222222222222222222222222222222222222222222222222222222","signature":"f5533adbe1ce96c20d2bf20a0a052ca4e3e5670cd7888e1b9088523ba704c94c22942ce61d385158f241f3a56871b88d962a63c7b2f6eb92b66567898762f007"}' + +{ + "id": "f7837d1c-fa0f-404f-ab40-5337a38d330e", + "report": { + "timestamp": 1712588155604, + "epoch": 2, + "digest": "2222222222222222222222222222222222222222222222222222222222222222", + "signature": "f5533adbe1ce96c20d2bf20a0a052ca4e3e5670cd7888e1b9088523ba704c94c22942ce61d385158f241f3a56871b88d962a63c7b2f6eb92b66567898762f007" + } +} +``` \ No newline at end of file From 59d12a2e3ae0fd7490887338c2e55b3cb80d66b3 Mon Sep 17 00:00:00 2001 From: Denise Pena Date: Wed, 18 Sep 2024 15:46:49 -0500 Subject: [PATCH 06/27] Fixing page order and curl examples --- src/content/docs/key-transparency/auditor/index.mdx | 2 ++ src/content/docs/key-transparency/namespaces/index.mdx | 4 +++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/src/content/docs/key-transparency/auditor/index.mdx b/src/content/docs/key-transparency/auditor/index.mdx index 69463d54f001207..f53bf47f295ccdd 100644 --- a/src/content/docs/key-transparency/auditor/index.mdx +++ b/src/content/docs/key-transparency/auditor/index.mdx @@ -1,6 +1,8 @@ --- pcx_content_type: overview title: Auditor +sidebar: + order: 1 --- The auditor is designed to sign epoch information, which includes the timestamp seen by the auditor, epoch number, and epoch digest. The auditor serialises this information in binary using protobuf or bincode and checks whether the requested inclusion is valid, as in not seen, and incremental. diff --git a/src/content/docs/key-transparency/namespaces/index.mdx b/src/content/docs/key-transparency/namespaces/index.mdx index 6c204150b8dc4d3..8743861e4f820f9 100644 --- a/src/content/docs/key-transparency/namespaces/index.mdx +++ b/src/content/docs/key-transparency/namespaces/index.mdx @@ -1,6 +1,8 @@ --- pcx_content_type: overview title: Namespaces +sidebar: + order: 2 --- ## Create a namespace @@ -15,7 +17,7 @@ The following fields are required when making a `POST` request: The `log_directory` field is optional but is the URL used to retrieve the log public key. ```sh -curl --request POST 'https://plexi-staging.research.cloudflare.com/namespaces' \ +curl 'https://plexi-staging.research.cloudflare.com/namespaces' \ --header 'Content-Type: application/json' \ --data '{ "name": "whatsapp-2024", From 3b536d9be697d7b9aadc06fa89aa7e7c9e77d5ba Mon Sep 17 00:00:00 2001 From: Thibault Meunier Date: Thu, 19 Sep 2024 16:26:28 +0200 Subject: [PATCH 07/27] Key transparency API documentation update reorganise the API --- .../api/auditor-information.mdx | 29 +++++++ .../docs/key-transparency/api/epochs.mdx | 56 +++++++++++++ .../docs/key-transparency/api/index.mdx | 12 +++ .../docs/key-transparency/api/namespaces.mdx | 80 +++++++++++++++++++ src/content/docs/key-transparency/index.mdx | 6 +- .../key-transparency/verify-epochs/index.mdx | 54 +------------ 6 files changed, 184 insertions(+), 53 deletions(-) create mode 100644 src/content/docs/key-transparency/api/auditor-information.mdx create mode 100644 src/content/docs/key-transparency/api/epochs.mdx create mode 100644 src/content/docs/key-transparency/api/index.mdx create mode 100644 src/content/docs/key-transparency/api/namespaces.mdx diff --git a/src/content/docs/key-transparency/api/auditor-information.mdx b/src/content/docs/key-transparency/api/auditor-information.mdx new file mode 100644 index 000000000000000..c45246cdb020ce6 --- /dev/null +++ b/src/content/docs/key-transparency/api/auditor-information.mdx @@ -0,0 +1,29 @@ +--- +pcx_content_type: overview +title: Auditor +sidebar: + order: 1 +--- + +The Auditor is designed to sign epoch information, which includes the time at which the request is received by the Auditor, the epoch number, and the epoch digest. The Auditor serialises these information in binary using protobuf or bincode and checks whether the requested inclusion is valid, as in not seen, and incremental. + +If the Log is setup to provide [AKD](https://github.com/facebook/akd) audit proof, the Auditor verifies them asynchronously. + +## Get Auditor information + +`keys` contain Auditor public keys which allow for key rotation later. Currently, keys can be reotated upon request. + +```sh +curl 'https://plexi.key-transparency.cloudflare.com/info' +{ + "keys": [ + { + "public_key": "d1036a33a8731e82a29dc68210988b32b60b7c1bd22d2341f2e339f4db3a2f4a", + "not_before": 1712311441501 + } + ], + "logs": [ + "508607faff7cb16be841e901eca41a6239461f239e7e610c9ea2576f334bc144" + ] +} +``` diff --git a/src/content/docs/key-transparency/api/epochs.mdx b/src/content/docs/key-transparency/api/epochs.mdx new file mode 100644 index 000000000000000..48bb2efe44e619e --- /dev/null +++ b/src/content/docs/key-transparency/api/epochs.mdx @@ -0,0 +1,56 @@ +--- +pcx_content_type: overview +title: Verify epochs +sidebar: + order: 3 +--- + +## Publish a new epoch + +Refer to the example below to publish a new epoch by requesting its signature. + +```sh +curl 'https://plexi.key-transparency.cloudflare.com/namespaces/{namespace}/audits' \ + --header 'Content-Type: application/json' \ + --data '{"epoch": 1, "digest": "1111111111111111111111111111111111111111111111111111111111111111"}' +{ + "namespace": "your.new.log.com", + "timestamp": 1717084639921, + "epoch": 1, + "digest": "1111111111111111111111111111111111111111111111111111111111111111", + "signature": "f6a51443bb6703813b330959d9d97471bc06464142165e59733fa102a18b052782a5307d59c31b8b13c1af7dfff6f6e7bf44e880d44e26e96c50a72f72a30c07", + "key_id": 74, +} +``` + +### Constraints + +- If `root` is defined for the namespace, the first epoch must match it (number and digest). +- Epochs must be increasing. Second epoch is 2, third is 3, etc. +- Epochs must have a unique digest or it will be rejected. +- Epochs cannot be republished. +- Digest must be a 32 byte string hex encoded (length 64). + +If a namespace is disabled, you receive the following error: + +```txt +HTTP 400 Bad Request +Namespace is disabled and read-only. +``` + +:::note +Avoid publishing more than 100 epochs as reset might not work beyond this threshold. +::: + +## Get an epoch + +```sh +curl 'https://plexi.key-transparency.cloudflare.com/namespaces/{namespace}/audits/1' +{ + "namespace": "your.new.log.com", + "timestamp": 1717084639921,~ + "epoch": 1, + "digest": "1111111111111111111111111111111111111111111111111111111111111111", + "signature": "f6a51443bb6703813b330959d9d97471bc06464142165e59733fa102a18b052782a5307d59c31b8b13c1af7dfff6f6e7bf44e880d44e26e96c50a72f72a30c07" +} +``` \ No newline at end of file diff --git a/src/content/docs/key-transparency/api/index.mdx b/src/content/docs/key-transparency/api/index.mdx new file mode 100644 index 000000000000000..b60ca06b09e7fc2 --- /dev/null +++ b/src/content/docs/key-transparency/api/index.mdx @@ -0,0 +1,12 @@ +--- +title: API +pcx_content_type: navigation +sidebar: + order: 2 + group: + hideIndex: true +--- + +import { DirectoryListing } from "~/components" + + \ No newline at end of file diff --git a/src/content/docs/key-transparency/api/namespaces.mdx b/src/content/docs/key-transparency/api/namespaces.mdx new file mode 100644 index 000000000000000..ec3346fceedd0bb --- /dev/null +++ b/src/content/docs/key-transparency/api/namespaces.mdx @@ -0,0 +1,80 @@ +--- +pcx_content_type: overview +title: Namespaces +sidebar: + order: 2 +--- + +Cloudflare Key Transparency API is organised in namespaces, representing a Log Cloudflare Auditor monitors. If you want to register a namespace, please contact us. + +## Create a namespace + +The following fields are required when making a `POST` request: + +- `name` +- `public` +- `root` +- `signature_version`: 0x0001 is for [Protobuf serialisation](https://github.com/cloudflare/plexi/blob/main/plexi_core/src/proto/specs/types.proto) and Ed25519 signature from the Auditor, 0x0002 is for [bincode serialisation](https://github.com/bincode-org/bincode/blob/trunk/docs/spec.md) and E25519 serialisation by the Auditor. + +The `log_directory` field is optional. If set, Cloudflare will use it to fetch audit proofs and validate them. + +```sh +curl 'https://plexi.key-transparency.cloudflare.com/namespaces' \ + --header 'Content-Type: application/json' \ + --data '{ + "name": "your.new.log.com", + "root": "1/1111111111111111111111111111111111111111111111111111111111111111", + "log_directory": "https://your.new.log.com/path/to/proofs", + "signature_version": 1 + }' +{ + "name": "your.new.log.com", + "log_directory": "https://your.new.log.com/path/to/proofs", + "root": "1/1111111111111111111111111111111111111111111111111111111111111111", + "status": "Initialization", + "reports_uri": "/namespaces/your.new.log.com/reports", + "audits_uri": "/namespaces/your.new.log.com/audits", + "signature_version": 1 +} +``` + +After publishing the first epoch, `status` will show `Online`. Possible statuses include: +- `Online` +- `Initialization` +- `Disabled` + +## List all namespaces + +Refer to the example below to get information about all public namespaces. + +```sh +curl 'https://plexi.key-transparency.cloudflare.com/namespaces' +{ + "namespaces": [ + { "name": "your.new.log.com", "root": "1/abc", "reports_uri": "/namespaces/your.new.log.com/reports", "audits_uri": "/namespaces/your.new.log.com/audits", "log_directory": "https://your.new.log.com/path/to/proofs", "status": "online" }, + { "name": "my.new.log.com", "reports_uri": "/namespaces/meta-bt-2024/reports", "audits_uri": "/namespaces/meta-bt-2024/audits", "status": "initialization" } + ] +} +``` + +## Disable a namespace + +If a log state has been corrupted, lost, or needs to be sharded to be maintainbale, the Auditor allows the Log operator to mark a namespace as `Disabled`. + + +```sh +curl -X PATCH 'https://plexi.key-transparency.cloudflare.com/namespaces/{namespace}' \ + -H 'Content-Type: application/json' \ + -d '{ + "status": "Disabled" + }' +{ + "name": "your.new.log.com", + "log_directory": "https://your.new.log.com/path/to/proofs", + "root": "1/1111111111111111111111111111111111111111111111111111111111111111", + "status": "Disabled", + "reports_uri": "/namespaces/your.new.log.com/reports", + "audits_uri": "/namespaces/your.new.log.com/audits", + "signature_version": 1 +} +``` \ No newline at end of file diff --git a/src/content/docs/key-transparency/index.mdx b/src/content/docs/key-transparency/index.mdx index a2998875e2c79cc..05293c4748dd466 100644 --- a/src/content/docs/key-transparency/index.mdx +++ b/src/content/docs/key-transparency/index.mdx @@ -13,8 +13,10 @@ import { CardGrid, Description, Feature, LinkTitleCard } from "~/components" -Ensure the transparency of end-to-end encrypted messaging conversations. +Secure the distribution of public keys in your end-to-end encrypted (E2EE) messaging systems -Cloudflare verifies key transparency audit proofs to ensure the transparency of end-to-end encrypted messaging conversations without the use of QR codes. \ No newline at end of file +Key Transparency aims to secure the distribution of public keys for end-to-end encrypted (E2EE) messaging systems, such as Signal or Whatsapp. It achieves this by building a verifiable append-only data structure called a Log, similar to [Certificate Transparency](https://developer.mozilla.org/en-US/docs/Web/Security/Certificate_Transparency). + +Cloudflare verifies Key Transparency Logs to ensure the transparency of end-to-end encrypted messaging public keys. This component is called an Auditor. Cloudflare provides an API for anyone to monitor the work of the Auditor, and verify the state of its associated Logs locally. diff --git a/src/content/docs/key-transparency/verify-epochs/index.mdx b/src/content/docs/key-transparency/verify-epochs/index.mdx index a38a32ae59a3073..dec7144d2369ec4 100644 --- a/src/content/docs/key-transparency/verify-epochs/index.mdx +++ b/src/content/docs/key-transparency/verify-epochs/index.mdx @@ -1,56 +1,8 @@ --- pcx_content_type: overview -title: Verify epochs +title: Monitor the Auditor sidebar: - order: 3 + order: 2 --- -## Publish a new epoch - -Refer to the example below to publish a new epoch by requesting its signature. - -```sh -curl 'https://plexi-staging.research.cloudflare.com/namespaces/{namespace}/audits' \ - --header 'Content-Type: application/json' \ - --data '{"epoch": 1, "digest": "1111111111111111111111111111111111111111111111111111111111111111"}' -{ - "namespace": "whatsapp-2024", - "timestamp": 1717084639921, - "epoch": 1, - "digest": "1111111111111111111111111111111111111111111111111111111111111111", - "signature": "f6a51443bb6703813b330959d9d97471bc06464142165e59733fa102a18b052782a5307d59c31b8b13c1af7dfff6f6e7bf44e880d44e26e96c50a72f72a30c07", - "key_id": 74, -} -``` - -### Constraints - -- If `root` is defined for the namespace, the first epoch must match it (number and digest). -- Epochs must be increasing. Second epoch is 2, third is 3, etc. -- Epochs must have a unique digest or it will be rejected. -- Epochs cannot be republished. -- Digest must be a 32 byte string hex encoded (length 64). - -If a namespace is disabled, you receive the following error: - -```txt -HTTP 400 Bad Request -Namespace is disabled and read-only. -``` - -:::note -Avoid publishing more than 100 epochs as reset might not work beyond this threshold. -::: - -## Get an epoch - -```sh -curl 'https://plexi-staging.research.cloudflare.com/namespaces/{namespace}/audits/1' -{ - "namespace": "whatsapp-2024", - "timestamp": 1717084639921,~ - "epoch": 1, - "digest": "1111111111111111111111111111111111111111111111111111111111111111", - "signature": "f6a51443bb6703813b330959d9d97471bc06464142165e59733fa102a18b052782a5307d59c31b8b13c1af7dfff6f6e7bf44e880d44e26e96c50a72f72a30c07" -} -``` \ No newline at end of file +Add local client documentation here \ No newline at end of file From 8dd323f093dacee4e40d797afb310e74a469fc14 Mon Sep 17 00:00:00 2001 From: Denise Pena Date: Thu, 19 Sep 2024 16:49:01 -0500 Subject: [PATCH 08/27] Removed separate Nampespaces and Reports sections --- .../key-transparency/namespaces/index.mdx | 81 ------------------- .../docs/key-transparency/reports/index.mdx | 65 --------------- 2 files changed, 146 deletions(-) delete mode 100644 src/content/docs/key-transparency/namespaces/index.mdx delete mode 100644 src/content/docs/key-transparency/reports/index.mdx diff --git a/src/content/docs/key-transparency/namespaces/index.mdx b/src/content/docs/key-transparency/namespaces/index.mdx deleted file mode 100644 index 8743861e4f820f9..000000000000000 --- a/src/content/docs/key-transparency/namespaces/index.mdx +++ /dev/null @@ -1,81 +0,0 @@ ---- -pcx_content_type: overview -title: Namespaces -sidebar: - order: 2 ---- - -## Create a namespace - -The following fields are required when making a `POST` request: - -- `name` -- `public` -- `root` -- `signature_version` - -The `log_directory` field is optional but is the URL used to retrieve the log public key. - -```sh -curl 'https://plexi-staging.research.cloudflare.com/namespaces' \ - --header 'Content-Type: application/json' \ - --data '{ - "name": "whatsapp-2024", - "public": true, - "root": "1/1111111111111111111111111111111111111111111111111111111111111111", - "log_directory": "https://meta.com/.well-known/key-transparency-log-directory", - "signature_version": 2 - }' -{ - "name": "whatsapp-2024", - "public": true, - "log_directory": "https://meta.com/.well-known/key-transparency-log-directory", - "root": "1/1111111111111111111111111111111111111111111111111111111111111111", - "status": "Initialization", - "reports_uri": "/namespaces/whatsapp-2024/reports", - "audits_uri": "/namespaces/whatsapp-2024/audits", - "signature_version": 2 -} -``` - -After publishing the first epoch, `status` will show `Online`. Possible statuses include: -- `Online` -- `Initialization` -- `Disabled` - -## List all namespaces - -Refer to the exmaple below to get information about all public namespaces. - -```sh -curl 'https://plexi-staging.research.cloudflare.com/namespaces' -{ - "namespaces": [ - { "name": "whatsapp-2024", "public": true, "root": "1/abc", "reports_uri": "/namespaces//whatsapp-2024/reports", "audits_uri": "/namespaces/whatsapp-2024/audits", "log_directory": "https://meta.com/.well-known/key-transparency-log-directory", "status": "online" }, - { "name": "meta-bt-2024", "public": true, "reports_uri": "/namespaces/meta-bt-2024/reports", "audits_uri": "/namespaces/meta-bt-2024/audits", "status": "initialization" } - ] -} -``` - -## Disable a namespace - -If a log state has been corrupted, lost, or needs to be sharded to be maintainbale, the auditor allows the Log operator to mark a namespace as `Disabled`. - - -```sh -curl -X PATCH 'https://plexi-staging.research.cloudflare.com/namespaces/{namespace}' \ - -H 'Content-Type: application/json' \ - -d '{ - "status": "Disabled" - }' -{ - "name": "whatsapp-2024", - "public": true, - "log_directory": "https://meta.com/.well-known/key-transparency-log-directory", - "root": "1/1111111111111111111111111111111111111111111111111111111111111111", - "status": "Disabled", - "reports_uri": "/namespaces/whatsapp-2024/reports", - "audits_uri": "/namespaces/whatsapp-2024/audits", - "signature_version": 2 -} -``` \ No newline at end of file diff --git a/src/content/docs/key-transparency/reports/index.mdx b/src/content/docs/key-transparency/reports/index.mdx deleted file mode 100644 index 8389ba3007a1439..000000000000000 --- a/src/content/docs/key-transparency/reports/index.mdx +++ /dev/null @@ -1,65 +0,0 @@ ---- -pcx_content_type: overview -title: Reports -sidebar: - order: 4 ---- - -## Verify a signature - -1. Install the `plexi` cli. - -```sh -# Email thibault@cloudflare.com for access -git clone git@github.com:cloudflare/plexi.git && cd plexi -cargo install plexi --path . -``` - -2. Verify the signature locally. - -```sh -AUDITOR_PUBLIC_KEY="$(curl -sS 'https://plexi-staging.research.cloudflare.com/info' | jq -r '.keys[0].public_key')" -curl -sS 'https://plexi-staging.research.cloudflare.com/namespaces/{namespace}/audits/1' | \ - plexi verify --namespace {namespace} --publickey "${AUDITOR_PUBLIC_KEY}" - -Signature valid -``` - -## Get all reports - -A report is a signature over (timestamp, epoch, digest) by the Log which has not been seen by the auditor. This means the Log is trying to bypass the auditor validation. - - -```sh -curl 'https://plexi-staging.research.cloudflare.com/namespaces/{namespace}/reports' -[ - { - "id": "f7837d1c-fa0f-404f-ab40-5337a38d330e", - "report": { - "namespace": "{namespace}", - "timestamp": 1712588155604, - "epoch": 2, - "digest": "2222222222222222222222222222222222222222222222222222222222222222", - "signature": "f5533adbe1ce96c20d2bf20a0a052ca4e3e5670cd7888e1b9088523ba704c94c22942ce61d385158f241f3a56871b88d962a63c7b2f6eb92b66567898762f007" - } - } -] -``` - -## Submit a report - -```sh -curl 'https://plexi-staging.research.cloudflare.com/namespaces/{namespace}/reports' \ - --header 'Content-Type: application/json' \ - --data '{"namespace":"{namespace}","timestamp":1712588155604,"epoch":2,"digest":"2222222222222222222222222222222222222222222222222222222222222222","signature":"f5533adbe1ce96c20d2bf20a0a052ca4e3e5670cd7888e1b9088523ba704c94c22942ce61d385158f241f3a56871b88d962a63c7b2f6eb92b66567898762f007"}' - -{ - "id": "f7837d1c-fa0f-404f-ab40-5337a38d330e", - "report": { - "timestamp": 1712588155604, - "epoch": 2, - "digest": "2222222222222222222222222222222222222222222222222222222222222222", - "signature": "f5533adbe1ce96c20d2bf20a0a052ca4e3e5670cd7888e1b9088523ba704c94c22942ce61d385158f241f3a56871b88d962a63c7b2f6eb92b66567898762f007" - } -} -``` \ No newline at end of file From b911b374d3eb205c4b33e5f94262679aaa91f31b Mon Sep 17 00:00:00 2001 From: Thibault Meunier Date: Fri, 20 Sep 2024 14:36:17 +0200 Subject: [PATCH 09/27] [Key Transparency] Add plexi client documentation local auditting --- .../docs/key-transparency/api/index.mdx | 2 +- .../docs/key-transparency/auditor/index.mdx | 41 ------------ .../key-transparency/verify-epochs/index.mdx | 65 ++++++++++++++++++- 3 files changed, 65 insertions(+), 43 deletions(-) delete mode 100644 src/content/docs/key-transparency/auditor/index.mdx diff --git a/src/content/docs/key-transparency/api/index.mdx b/src/content/docs/key-transparency/api/index.mdx index b60ca06b09e7fc2..e2f4ef456c940bd 100644 --- a/src/content/docs/key-transparency/api/index.mdx +++ b/src/content/docs/key-transparency/api/index.mdx @@ -2,7 +2,7 @@ title: API pcx_content_type: navigation sidebar: - order: 2 + order: 1 group: hideIndex: true --- diff --git a/src/content/docs/key-transparency/auditor/index.mdx b/src/content/docs/key-transparency/auditor/index.mdx deleted file mode 100644 index f53bf47f295ccdd..000000000000000 --- a/src/content/docs/key-transparency/auditor/index.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -pcx_content_type: overview -title: Auditor -sidebar: - order: 1 ---- - -The auditor is designed to sign epoch information, which includes the timestamp seen by the auditor, epoch number, and epoch digest. The auditor serialises this information in binary using protobuf or bincode and checks whether the requested inclusion is valid, as in not seen, and incremental. - -## Get auditor information - -`keys` contain auditor public keys which allow for key rotation later. Currently, keys can be reotated upon request. - -```sh -curl 'https://plexi-staging.research.cloudflare.com/info' -{ - "keys": [ - { - "public_key": "d1036a33a8731e82a29dc68210988b32b60b7c1bd22d2341f2e339f4db3a2f4a", - "not_before": 1712311441501 - } - ], - "logs": [ - "508607faff7cb16be841e901eca41a6239461f239e7e610c9ea2576f334bc144" - ] -} -``` - -## Reset the auditor - -Resetting the auditor removes existing signatures and allows clients to test behavior at initialization. - -```sh -curl 'https://plexi-staging.research.cloudflare.com/namespaces' -{ - "namespaces": [ - { "name": "whatsapp-2024", "public": true, "root": "1/abc", "reports_uri": "/namespaces//whatsapp-2024/reports", "audits_uri": "/namespaces/whatsapp-2024/audits", "log_directory": "https://meta.com/.well-known/key-transparency-log-directory", "status": "online" }, - { "name": "meta-bt-2024", "public": true, "reports_uri": "/namespaces/meta-bt-2024/reports", "audits_uri": "/namespaces/meta-bt-2024/audits", "status": "initialization" } - ] -} -``` diff --git a/src/content/docs/key-transparency/verify-epochs/index.mdx b/src/content/docs/key-transparency/verify-epochs/index.mdx index dec7144d2369ec4..d618846a1a76064 100644 --- a/src/content/docs/key-transparency/verify-epochs/index.mdx +++ b/src/content/docs/key-transparency/verify-epochs/index.mdx @@ -5,4 +5,67 @@ sidebar: order: 2 --- -Add local client documentation here \ No newline at end of file +Cloudflare Key Transparency Auditor validates Log audit proofs, and provides a signature for them. This allows Log to distribute these signatures to its end-users, and users to have confidence that the Log is not tricking them. + +Cloudflare provides [Plexi](https://github.com/cloudflare/plexi), a cli companion to verify an Auditor claims locally. This leverages the public [API](./api), and allows people most at risk to back Cloudflare claims. + +## Features + +* Verify authenticity of a signature, to confirm it has been signed by a given public key +* Verify the validity of [facebook/akd](https://github.com/facebook/akd) proofs +* List Logs an Auditor monitors + +## Installation + +| Environment | CLI Command | +|:--------------------------------------------------------------|:----------------------| +| [Cargo](https://www.rust-lang.org/tools/install) (Rust 1.76+) | `cargo install plexi` | + +## Usage + +You can use the `--help` option to get more details about the commands and their options. + +```bash +plexi [OPTIONS] +``` + +### Configure your auditor remote + +`plexi` does not come with a default remote auditor. You should decide whichever suit your needs. + +You can do so either by passing `--remote-url=`, or setting `PLEXI_REMOTE_URL` environment variable. + +A list of common remote is provided bellow + +| Name | Remote | +|:-----------|:------------------------------------------------| +| Cloudflare | `https://plexi.key-transparency.cloudflare.com` | + +If you have deployed your own auditor, you can add a remote by filing a [GitHub issue](https://github.com/cloudflare/plexi/issues). + +### Listing monitored Logs + +An auditor monitors multiple Logs at once. To discover which Logs an auditor is monitoring, you run the following + +```shell +plexi ls --remote-url 'https://plexi.key-transparency.cloudflare.com' +whatsapp.key-transparency.v1 +``` + +### Auditting a signature + +Key Transparency Auditor vouch for Log validity. They do so by ensuring epoch uniqueness, and verifying the associated proof + +`plexi audit` provides information about a given epoch, and its validity. It can perform a local audit to confirm the auditor behaviour. + +For instance, to verify WhatsApp Log auditted by Cloudflare Auditor, you run the following +```shell +> plexi audit --remote-url 'https://plexi.key-transparency.cloudflare.com' --namespace 'whatsapp.key-transparency.v1' --long +Namespace: whatsapp.key-transparency.v1 +Ciphersuite: ed25519(protobuf) +Timestamp: 2024-09-19T09:59:44Z +Epoch height: 476847 +Epoch digest: 9d217c91dc629d16a3b1379e8fd7c949c27b1b6038259e3918bd0da3cd6c34d1 +Signature: e4c83e3091ba8764752120bd7a726a28759d25a01f39d07131d6ba66a913d58d8f0f48f63bc7e037cc5ddd81dc76acc847dbf8d02b2f55251e6f2b1f00191902 +Verification: success +``` From b4c61d25afd27845138c4d29e45f0d03fae8bfc9 Mon Sep 17 00:00:00 2001 From: Thibault Meunier Date: Fri, 20 Sep 2024 16:06:04 +0200 Subject: [PATCH 10/27] [Key Transparency] Move verify-epochs to monitor-the-auditor --- .../{verify-epochs => monitor-the-auditor}/index.mdx | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename src/content/docs/key-transparency/{verify-epochs => monitor-the-auditor}/index.mdx (100%) diff --git a/src/content/docs/key-transparency/verify-epochs/index.mdx b/src/content/docs/key-transparency/monitor-the-auditor/index.mdx similarity index 100% rename from src/content/docs/key-transparency/verify-epochs/index.mdx rename to src/content/docs/key-transparency/monitor-the-auditor/index.mdx From d60e4eec74137942cc734dbaddca22d92da8d484 Mon Sep 17 00:00:00 2001 From: Thibault Meunier Date: Fri, 20 Sep 2024 16:17:11 +0200 Subject: [PATCH 11/27] [Key Transparency] Fix typo --- src/content/docs/key-transparency/api/auditor-information.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/key-transparency/api/auditor-information.mdx b/src/content/docs/key-transparency/api/auditor-information.mdx index c45246cdb020ce6..c3e0012b5516b64 100644 --- a/src/content/docs/key-transparency/api/auditor-information.mdx +++ b/src/content/docs/key-transparency/api/auditor-information.mdx @@ -11,7 +11,7 @@ If the Log is setup to provide [AKD](https://github.com/facebook/akd) audit proo ## Get Auditor information -`keys` contain Auditor public keys which allow for key rotation later. Currently, keys can be reotated upon request. +`keys` contain Auditor public keys which allow for key rotation later. ```sh curl 'https://plexi.key-transparency.cloudflare.com/info' From c1c2714a9d506a5ac69a4c6f187d20c76f03c38c Mon Sep 17 00:00:00 2001 From: Thibault Meunier Date: Fri, 20 Sep 2024 16:18:48 +0200 Subject: [PATCH 12/27] [Key transparency] Improve wording on local verification --- src/content/docs/key-transparency/monitor-the-auditor/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/key-transparency/monitor-the-auditor/index.mdx b/src/content/docs/key-transparency/monitor-the-auditor/index.mdx index d618846a1a76064..4a423bd30a020b9 100644 --- a/src/content/docs/key-transparency/monitor-the-auditor/index.mdx +++ b/src/content/docs/key-transparency/monitor-the-auditor/index.mdx @@ -7,7 +7,7 @@ sidebar: Cloudflare Key Transparency Auditor validates Log audit proofs, and provides a signature for them. This allows Log to distribute these signatures to its end-users, and users to have confidence that the Log is not tricking them. -Cloudflare provides [Plexi](https://github.com/cloudflare/plexi), a cli companion to verify an Auditor claims locally. This leverages the public [API](./api), and allows people most at risk to back Cloudflare claims. +Cloudflare provides [Plexi](https://github.com/cloudflare/plexi), a cli companion to verify an Auditor claims locally. This leverages the public [API](./api/index.mdx), and allows users to verify Cloudflare Auditor claims. ## Features From d59939518aa23eb671c210c78b5bb24eefc1dfae Mon Sep 17 00:00:00 2001 From: Thibault Meunier Date: Fri, 20 Sep 2024 16:38:00 +0200 Subject: [PATCH 13/27] [Key Transparency] Fix typo --- src/content/docs/key-transparency/api/epochs.mdx | 2 ++ src/content/docs/key-transparency/api/namespaces.mdx | 6 +++++- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/src/content/docs/key-transparency/api/epochs.mdx b/src/content/docs/key-transparency/api/epochs.mdx index 48bb2efe44e619e..e5fccbe03ec65bb 100644 --- a/src/content/docs/key-transparency/api/epochs.mdx +++ b/src/content/docs/key-transparency/api/epochs.mdx @@ -9,6 +9,8 @@ sidebar: Refer to the example below to publish a new epoch by requesting its signature. +This API is authenticated via [mTLS](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/), so that only a Log owner can publish new epochs. + ```sh curl 'https://plexi.key-transparency.cloudflare.com/namespaces/{namespace}/audits' \ --header 'Content-Type: application/json' \ diff --git a/src/content/docs/key-transparency/api/namespaces.mdx b/src/content/docs/key-transparency/api/namespaces.mdx index ec3346fceedd0bb..fd24e8a64e2f499 100644 --- a/src/content/docs/key-transparency/api/namespaces.mdx +++ b/src/content/docs/key-transparency/api/namespaces.mdx @@ -18,6 +18,8 @@ The following fields are required when making a `POST` request: The `log_directory` field is optional. If set, Cloudflare will use it to fetch audit proofs and validate them. +This API is authenticated via [mTLS](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/). + ```sh curl 'https://plexi.key-transparency.cloudflare.com/namespaces' \ --header 'Content-Type: application/json' \ @@ -59,7 +61,9 @@ curl 'https://plexi.key-transparency.cloudflare.com/namespaces' ## Disable a namespace -If a log state has been corrupted, lost, or needs to be sharded to be maintainbale, the Auditor allows the Log operator to mark a namespace as `Disabled`. +If a log state has been corrupted, lost, or needs to be sharded to be maintainable, the Auditor allows the Log operator to mark a namespace as `Disabled`. + +This API is authenticated via [mTLS](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/). ```sh From 86378ae4328b20bed989e18d1f243869c3900830 Mon Sep 17 00:00:00 2001 From: Denise Pena Date: Fri, 20 Sep 2024 09:54:01 -0500 Subject: [PATCH 14/27] Changed icon to key --- src/icons/key-transparency.svg | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/src/icons/key-transparency.svg b/src/icons/key-transparency.svg index ef28eea7ce34632..63dfbeec970f30f 100644 --- a/src/icons/key-transparency.svg +++ b/src/icons/key-transparency.svg @@ -1 +1,8 @@ - \ No newline at end of file + + + + + + + + \ No newline at end of file From 7008fb2114a133ccc960f04c2f9e6ae314fa5581 Mon Sep 17 00:00:00 2001 From: Denise Pena Date: Fri, 20 Sep 2024 10:43:33 -0500 Subject: [PATCH 15/27] Minor spelling and grammar fixes --- .../api/auditor-information.mdx | 2 +- .../docs/key-transparency/api/namespaces.mdx | 6 +++-- src/content/docs/key-transparency/index.mdx | 16 +++++++++++++- .../monitor-the-auditor/index.mdx | 22 +++++++++---------- 4 files changed, 31 insertions(+), 15 deletions(-) diff --git a/src/content/docs/key-transparency/api/auditor-information.mdx b/src/content/docs/key-transparency/api/auditor-information.mdx index c3e0012b5516b64..4686a59b0bdf3dc 100644 --- a/src/content/docs/key-transparency/api/auditor-information.mdx +++ b/src/content/docs/key-transparency/api/auditor-information.mdx @@ -5,7 +5,7 @@ sidebar: order: 1 --- -The Auditor is designed to sign epoch information, which includes the time at which the request is received by the Auditor, the epoch number, and the epoch digest. The Auditor serialises these information in binary using protobuf or bincode and checks whether the requested inclusion is valid, as in not seen, and incremental. +The Auditor is designed to sign epoch information, which includes the time at which the request is received by the Auditor, the epoch number, and the epoch digest. The Auditor serialises this information in binary using protobuf or bincode and checks whether the requested inclusion is valid, as in not seen, and incremental. If the Log is setup to provide [AKD](https://github.com/facebook/akd) audit proof, the Auditor verifies them asynchronously. diff --git a/src/content/docs/key-transparency/api/namespaces.mdx b/src/content/docs/key-transparency/api/namespaces.mdx index fd24e8a64e2f499..79a8dfbf378dfe2 100644 --- a/src/content/docs/key-transparency/api/namespaces.mdx +++ b/src/content/docs/key-transparency/api/namespaces.mdx @@ -5,7 +5,7 @@ sidebar: order: 2 --- -Cloudflare Key Transparency API is organised in namespaces, representing a Log Cloudflare Auditor monitors. If you want to register a namespace, please contact us. +The Cloudflare Key Transparency API is organized in namespaces, representing a log Cloudflare Auditor monitors. If you want to register a namespace, contact us. ## Create a namespace @@ -14,7 +14,9 @@ The following fields are required when making a `POST` request: - `name` - `public` - `root` -- `signature_version`: 0x0001 is for [Protobuf serialisation](https://github.com/cloudflare/plexi/blob/main/plexi_core/src/proto/specs/types.proto) and Ed25519 signature from the Auditor, 0x0002 is for [bincode serialisation](https://github.com/bincode-org/bincode/blob/trunk/docs/spec.md) and E25519 serialisation by the Auditor. +- `signature_version`: + - 0x0001 is for [Protobuf serialisation](https://github.com/cloudflare/plexi/blob/main/plexi_core/src/proto/specs/types.proto) Ed25519 signature from the Auditor + - 0x0002 is for [bincode serialisation](https://github.com/bincode-org/bincode/blob/trunk/docs/spec.md) E25519 serialisation by the Auditor The `log_directory` field is optional. If set, Cloudflare will use it to fetch audit proofs and validate them. diff --git a/src/content/docs/key-transparency/index.mdx b/src/content/docs/key-transparency/index.mdx index 05293c4748dd466..1cc17d0d4ec74ef 100644 --- a/src/content/docs/key-transparency/index.mdx +++ b/src/content/docs/key-transparency/index.mdx @@ -9,7 +9,7 @@ head: --- -import { CardGrid, Description, Feature, LinkTitleCard } from "~/components" +import { CardGrid, Description, Feature, LinkTitleCard, RelatedProduct } from "~/components" @@ -20,3 +20,17 @@ Secure the distribution of public keys in your end-to-end encrypted (E2EE) messa Key Transparency aims to secure the distribution of public keys for end-to-end encrypted (E2EE) messaging systems, such as Signal or Whatsapp. It achieves this by building a verifiable append-only data structure called a Log, similar to [Certificate Transparency](https://developer.mozilla.org/en-US/docs/Web/Security/Certificate_Transparency). Cloudflare verifies Key Transparency Logs to ensure the transparency of end-to-end encrypted messaging public keys. This component is called an Auditor. Cloudflare provides an API for anyone to monitor the work of the Auditor, and verify the state of its associated Logs locally. + +## Related products + + + +Certificate Transparency (CT) Monitoring is an opt-in feature in public beta that aims at improving security by allowing you to double-check any SSL/TLS certificates issued for your domain. + + + + + +Privacy Gateway is a managed service deployed on Cloudflare's global network that implements part of the [Oblivious HTTP (OHTTP) IETF](https://www.ietf.org/archive/id/draft-thomson-http-oblivious-01.html) standard. The goal of Privacy Gateway and Oblivious HTTP is to hide the client's IP address when interacting with an application backend. + + \ No newline at end of file diff --git a/src/content/docs/key-transparency/monitor-the-auditor/index.mdx b/src/content/docs/key-transparency/monitor-the-auditor/index.mdx index 4a423bd30a020b9..3fa5e0748dcc234 100644 --- a/src/content/docs/key-transparency/monitor-the-auditor/index.mdx +++ b/src/content/docs/key-transparency/monitor-the-auditor/index.mdx @@ -5,7 +5,7 @@ sidebar: order: 2 --- -Cloudflare Key Transparency Auditor validates Log audit proofs, and provides a signature for them. This allows Log to distribute these signatures to its end-users, and users to have confidence that the Log is not tricking them. +Cloudflare Key Transparency Auditor validates Log audit proofs and provides a signature for them. This allows Log to distribute these signatures to its end-users, and provides users with confidence that the Log is not tricking them. Cloudflare provides [Plexi](https://github.com/cloudflare/plexi), a cli companion to verify an Auditor claims locally. This leverages the public [API](./api/index.mdx), and allows users to verify Cloudflare Auditor claims. @@ -23,7 +23,7 @@ Cloudflare provides [Plexi](https://github.com/cloudflare/plexi), a cli companio ## Usage -You can use the `--help` option to get more details about the commands and their options. +Use the `--help` option for more details about the commands and their options. ```bash plexi [OPTIONS] @@ -31,11 +31,11 @@ plexi [OPTIONS] ### Configure your auditor remote -`plexi` does not come with a default remote auditor. You should decide whichever suit your needs. +`plexi` does not come with a default remote auditor, and you will need to choose your own. -You can do so either by passing `--remote-url=`, or setting `PLEXI_REMOTE_URL` environment variable. +You can do so either by passing `--remote-url=` or setting the `PLEXI_REMOTE_URL` environment variable. -A list of common remote is provided bellow +A common remote is provided below: | Name | Remote | |:-----------|:------------------------------------------------| @@ -43,22 +43,22 @@ A list of common remote is provided bellow If you have deployed your own auditor, you can add a remote by filing a [GitHub issue](https://github.com/cloudflare/plexi/issues). -### Listing monitored Logs +### List monitored Logs -An auditor monitors multiple Logs at once. To discover which Logs an auditor is monitoring, you run the following +An auditor monitors multiple Logs at once. To discover which Logs an auditor is monitoring, run the following: ```shell plexi ls --remote-url 'https://plexi.key-transparency.cloudflare.com' whatsapp.key-transparency.v1 ``` -### Auditting a signature +### Audit a signature -Key Transparency Auditor vouch for Log validity. They do so by ensuring epoch uniqueness, and verifying the associated proof +Key Transparency Auditor vouches for Log validity by ensuring epoch uniqueness. and verifying the associated proof -`plexi audit` provides information about a given epoch, and its validity. It can perform a local audit to confirm the auditor behaviour. +`plexi audit` provides information about a given epoch and its validity. It can perform a local audit to confirm the auditor behaviour. -For instance, to verify WhatsApp Log auditted by Cloudflare Auditor, you run the following +For instance, to verify WhatsApp Log auditted by Cloudflare Auditor, run the following: ```shell > plexi audit --remote-url 'https://plexi.key-transparency.cloudflare.com' --namespace 'whatsapp.key-transparency.v1' --long Namespace: whatsapp.key-transparency.v1 From d9b96af4a3691b1bebdfaca7b21d05a4e84dab69 Mon Sep 17 00:00:00 2001 From: Mari <7750294+mgalicer@users.noreply.github.com> Date: Fri, 20 Sep 2024 16:54:53 +0100 Subject: [PATCH 16/27] rename product to Key Transparency Auditor --- src/content/docs/key-transparency/index.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/key-transparency/index.mdx b/src/content/docs/key-transparency/index.mdx index 1cc17d0d4ec74ef..30dbc2dcf69cf55 100644 --- a/src/content/docs/key-transparency/index.mdx +++ b/src/content/docs/key-transparency/index.mdx @@ -5,7 +5,7 @@ sidebar: order: 1 head: - tag: title - content: Key Transparency + content: Key Transparency Auditor --- @@ -17,9 +17,9 @@ Secure the distribution of public keys in your end-to-end encrypted (E2EE) messa -Key Transparency aims to secure the distribution of public keys for end-to-end encrypted (E2EE) messaging systems, such as Signal or Whatsapp. It achieves this by building a verifiable append-only data structure called a Log, similar to [Certificate Transparency](https://developer.mozilla.org/en-US/docs/Web/Security/Certificate_Transparency). +Cloudflare's Key Transparency Auditor aims to secure the distribution of public keys for end-to-end encrypted (E2EE) messaging systems like [Whatsapp](https://engineering.fb.com/2023/04/13/security/whatsapp-key-transparency/). It achieves this by building a verifiable append-only data structure called a Log, similar to [Certificate Transparency](https://developer.mozilla.org/en-US/docs/Web/Security/Certificate_Transparency). -Cloudflare verifies Key Transparency Logs to ensure the transparency of end-to-end encrypted messaging public keys. This component is called an Auditor. Cloudflare provides an API for anyone to monitor the work of the Auditor, and verify the state of its associated Logs locally. +Cloudflare acts as an auditor of Key Transparency Logs to ensure the transparency of end-to-end encrypted messaging public keys. Cloudflare provides an API for anyone to monitor the verification work we perform, and verify the state of its associated Logs locally. ## Related products @@ -33,4 +33,4 @@ Certificate Transparency (CT) Monitoring is an opt-in feature in public beta tha Privacy Gateway is a managed service deployed on Cloudflare's global network that implements part of the [Oblivious HTTP (OHTTP) IETF](https://www.ietf.org/archive/id/draft-thomson-http-oblivious-01.html) standard. The goal of Privacy Gateway and Oblivious HTTP is to hide the client's IP address when interacting with an application backend. - \ No newline at end of file + From e396a56c3b4bace8d7f4020a67e889ef1cb37dd1 Mon Sep 17 00:00:00 2001 From: Mari <7750294+mgalicer@users.noreply.github.com> Date: Fri, 20 Sep 2024 17:02:27 +0100 Subject: [PATCH 17/27] Copy edits --- .../docs/key-transparency/monitor-the-auditor/index.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/key-transparency/monitor-the-auditor/index.mdx b/src/content/docs/key-transparency/monitor-the-auditor/index.mdx index 3fa5e0748dcc234..083123beeb239f6 100644 --- a/src/content/docs/key-transparency/monitor-the-auditor/index.mdx +++ b/src/content/docs/key-transparency/monitor-the-auditor/index.mdx @@ -5,9 +5,9 @@ sidebar: order: 2 --- -Cloudflare Key Transparency Auditor validates Log audit proofs and provides a signature for them. This allows Log to distribute these signatures to its end-users, and provides users with confidence that the Log is not tricking them. +Cloudflare's Key Transparency Auditor validates Log audit proofs and provides a signature for them. The Log can then distribute these signatures to its end-users, and provides users with confidence that keys have not been tampered with. -Cloudflare provides [Plexi](https://github.com/cloudflare/plexi), a cli companion to verify an Auditor claims locally. This leverages the public [API](./api/index.mdx), and allows users to verify Cloudflare Auditor claims. +In order to verify _our_ work, you can use [Plexi](https://github.com/cloudflare/plexi), a CLI tool that allows anyone to perform proof verification locally via a public [API](./api/index.mdx). ## Features @@ -54,7 +54,7 @@ whatsapp.key-transparency.v1 ### Audit a signature -Key Transparency Auditor vouches for Log validity by ensuring epoch uniqueness. and verifying the associated proof +The Key Transparency Auditor vouches for Log validity by ensuring epoch uniqueness. and verifying the associated proof `plexi audit` provides information about a given epoch and its validity. It can perform a local audit to confirm the auditor behaviour. From d00186ce22e24995a0f4535d02f7fd8de7b5dc3a Mon Sep 17 00:00:00 2001 From: Thibault Meunier Date: Fri, 20 Sep 2024 18:08:49 +0200 Subject: [PATCH 18/27] Rename Key Transparency --- src/content/products/key-transparency.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/products/key-transparency.yaml b/src/content/products/key-transparency.yaml index 7645e2a8ecf2009..4bd1a6ad33b55bf 100644 --- a/src/content/products/key-transparency.yaml +++ b/src/content/products/key-transparency.yaml @@ -1,14 +1,14 @@ -name: Key Transparency +name: Key Transparency Auditor product: - title: Key Transparency + title: Key Transparency Auditor url: /key-transparency/ group: Application security meta: - title: Key Transparency + title: Key Transparency Auditor description: - Key Transparency docs + Key Transparency Auditor docs author: "@cloudflare" externals: From 93be64f4f020e75a0d10f6af7ef9ff2f83ffb7db Mon Sep 17 00:00:00 2001 From: Thibault Meunier Date: Mon, 23 Sep 2024 16:28:23 +0200 Subject: [PATCH 19/27] [Key Transparency Auditor] Fix WhatApp capitalization --- src/content/docs/key-transparency/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/key-transparency/index.mdx b/src/content/docs/key-transparency/index.mdx index 30dbc2dcf69cf55..4e52582720e5247 100644 --- a/src/content/docs/key-transparency/index.mdx +++ b/src/content/docs/key-transparency/index.mdx @@ -17,7 +17,7 @@ Secure the distribution of public keys in your end-to-end encrypted (E2EE) messa -Cloudflare's Key Transparency Auditor aims to secure the distribution of public keys for end-to-end encrypted (E2EE) messaging systems like [Whatsapp](https://engineering.fb.com/2023/04/13/security/whatsapp-key-transparency/). It achieves this by building a verifiable append-only data structure called a Log, similar to [Certificate Transparency](https://developer.mozilla.org/en-US/docs/Web/Security/Certificate_Transparency). +Cloudflare's Key Transparency Auditor aims to secure the distribution of public keys for end-to-end encrypted (E2EE) messaging systems like [WhatsApp](https://engineering.fb.com/2023/04/13/security/whatsapp-key-transparency/). It achieves this by building a verifiable append-only data structure called a Log, similar to [Certificate Transparency](https://developer.mozilla.org/en-US/docs/Web/Security/Certificate_Transparency). Cloudflare acts as an auditor of Key Transparency Logs to ensure the transparency of end-to-end encrypted messaging public keys. Cloudflare provides an API for anyone to monitor the verification work we perform, and verify the state of its associated Logs locally. From 110824ad8f64bef44e5a397889bc5709165c01d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Denise=20Pe=C3=B1a?= <75506267+dcpena@users.noreply.github.com> Date: Mon, 23 Sep 2024 15:48:03 -0500 Subject: [PATCH 20/27] Removed random punctuation mark --- src/content/docs/key-transparency/monitor-the-auditor/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/key-transparency/monitor-the-auditor/index.mdx b/src/content/docs/key-transparency/monitor-the-auditor/index.mdx index 083123beeb239f6..b8699af4dacb1e1 100644 --- a/src/content/docs/key-transparency/monitor-the-auditor/index.mdx +++ b/src/content/docs/key-transparency/monitor-the-auditor/index.mdx @@ -54,7 +54,7 @@ whatsapp.key-transparency.v1 ### Audit a signature -The Key Transparency Auditor vouches for Log validity by ensuring epoch uniqueness. and verifying the associated proof +The Key Transparency Auditor vouches for Log validity by ensuring epoch uniqueness and verifying the associated proof. `plexi audit` provides information about a given epoch and its validity. It can perform a local audit to confirm the auditor behaviour. From 44607007b99985077685f727e1f3ff262a7c45ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Denise=20Pe=C3=B1a?= <75506267+dcpena@users.noreply.github.com> Date: Mon, 23 Sep 2024 15:50:26 -0500 Subject: [PATCH 21/27] Removed incorrect use of italics --- src/content/docs/key-transparency/monitor-the-auditor/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/key-transparency/monitor-the-auditor/index.mdx b/src/content/docs/key-transparency/monitor-the-auditor/index.mdx index b8699af4dacb1e1..b2a885f8978b787 100644 --- a/src/content/docs/key-transparency/monitor-the-auditor/index.mdx +++ b/src/content/docs/key-transparency/monitor-the-auditor/index.mdx @@ -7,7 +7,7 @@ sidebar: Cloudflare's Key Transparency Auditor validates Log audit proofs and provides a signature for them. The Log can then distribute these signatures to its end-users, and provides users with confidence that keys have not been tampered with. -In order to verify _our_ work, you can use [Plexi](https://github.com/cloudflare/plexi), a CLI tool that allows anyone to perform proof verification locally via a public [API](./api/index.mdx). +In order to verify our work, you can use [Plexi](https://github.com/cloudflare/plexi), a CLI tool that allows anyone to perform proof verification locally via a public [API](./api/index.mdx). ## Features From b5805d15e174de4d605398b6ec6012b528544e6a Mon Sep 17 00:00:00 2001 From: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> Date: Tue, 24 Sep 2024 11:10:54 +0100 Subject: [PATCH 22/27] Remove extra tilde --- src/content/docs/key-transparency/api/epochs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/key-transparency/api/epochs.mdx b/src/content/docs/key-transparency/api/epochs.mdx index e5fccbe03ec65bb..15eeeb5feed35c2 100644 --- a/src/content/docs/key-transparency/api/epochs.mdx +++ b/src/content/docs/key-transparency/api/epochs.mdx @@ -50,7 +50,7 @@ Avoid publishing more than 100 epochs as reset might not work beyond this thresh curl 'https://plexi.key-transparency.cloudflare.com/namespaces/{namespace}/audits/1' { "namespace": "your.new.log.com", - "timestamp": 1717084639921,~ + "timestamp": 1717084639921, "epoch": 1, "digest": "1111111111111111111111111111111111111111111111111111111111111111", "signature": "f6a51443bb6703813b330959d9d97471bc06464142165e59733fa102a18b052782a5307d59c31b8b13c1af7dfff6f6e7bf44e880d44e26e96c50a72f72a30c07" From 0e3f7c4a6e50bf9e57aa34029a921920ba73b821 Mon Sep 17 00:00:00 2001 From: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> Date: Tue, 24 Sep 2024 11:15:57 +0100 Subject: [PATCH 23/27] Small update Co-authored-by: Jun Lee --- src/content/docs/key-transparency/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/key-transparency/index.mdx b/src/content/docs/key-transparency/index.mdx index 4e52582720e5247..c60e75a28e07728 100644 --- a/src/content/docs/key-transparency/index.mdx +++ b/src/content/docs/key-transparency/index.mdx @@ -25,7 +25,7 @@ Cloudflare acts as an auditor of Key Transparency Logs to ensure the transparenc -Certificate Transparency (CT) Monitoring is an opt-in feature in public beta that aims at improving security by allowing you to double-check any SSL/TLS certificates issued for your domain. +Certificate Transparency (CT) Monitoring is an opt-in feature in public beta that aims to improve security by allowing you to double-check any SSL/TLS certificates issued for your domain. From 5b8075c0ab4469c0e6094d594aeb111b6f5410c0 Mon Sep 17 00:00:00 2001 From: Thibault Meunier Date: Tue, 24 Sep 2024 12:01:37 +0200 Subject: [PATCH 24/27] [Key transparency auditor] Address oxyjun comments * Point to constraints in the auditor information * Add comma --- .../api/auditor-information.mdx | 2 +- .../docs/key-transparency/api/epochs.mdx | 32 ++++++++----------- 2 files changed, 15 insertions(+), 19 deletions(-) diff --git a/src/content/docs/key-transparency/api/auditor-information.mdx b/src/content/docs/key-transparency/api/auditor-information.mdx index 4686a59b0bdf3dc..44c01086e2da504 100644 --- a/src/content/docs/key-transparency/api/auditor-information.mdx +++ b/src/content/docs/key-transparency/api/auditor-information.mdx @@ -5,7 +5,7 @@ sidebar: order: 1 --- -The Auditor is designed to sign epoch information, which includes the time at which the request is received by the Auditor, the epoch number, and the epoch digest. The Auditor serialises this information in binary using protobuf or bincode and checks whether the requested inclusion is valid, as in not seen, and incremental. +The Auditor is designed to sign epoch information, which includes the time at which the request is received by the Auditor, the epoch number, and the epoch digest. The Auditor serialises this information in binary using protobuf or bincode and checks whether the requested inclusion is valid, as in not satisfies [publication constraints](./epochs/#constraints). If the Log is setup to provide [AKD](https://github.com/facebook/akd) audit proof, the Auditor verifies them asynchronously. diff --git a/src/content/docs/key-transparency/api/epochs.mdx b/src/content/docs/key-transparency/api/epochs.mdx index 15eeeb5feed35c2..aede0f399528ae8 100644 --- a/src/content/docs/key-transparency/api/epochs.mdx +++ b/src/content/docs/key-transparency/api/epochs.mdx @@ -1,10 +1,23 @@ --- pcx_content_type: overview -title: Verify epochs +title: Epochs sidebar: order: 3 --- +## Get an epoch + +```sh +curl 'https://plexi.key-transparency.cloudflare.com/namespaces/{namespace}/audits/1' +{ + "namespace": "your.new.log.com", + "timestamp": 1717084639921, + "epoch": 1, + "digest": "1111111111111111111111111111111111111111111111111111111111111111", + "signature": "f6a51443bb6703813b330959d9d97471bc06464142165e59733fa102a18b052782a5307d59c31b8b13c1af7dfff6f6e7bf44e880d44e26e96c50a72f72a30c07" +} +``` + ## Publish a new epoch Refer to the example below to publish a new epoch by requesting its signature. @@ -39,20 +52,3 @@ If a namespace is disabled, you receive the following error: HTTP 400 Bad Request Namespace is disabled and read-only. ``` - -:::note -Avoid publishing more than 100 epochs as reset might not work beyond this threshold. -::: - -## Get an epoch - -```sh -curl 'https://plexi.key-transparency.cloudflare.com/namespaces/{namespace}/audits/1' -{ - "namespace": "your.new.log.com", - "timestamp": 1717084639921, - "epoch": 1, - "digest": "1111111111111111111111111111111111111111111111111111111111111111", - "signature": "f6a51443bb6703813b330959d9d97471bc06464142165e59733fa102a18b052782a5307d59c31b8b13c1af7dfff6f6e7bf44e880d44e26e96c50a72f72a30c07" -} -``` \ No newline at end of file From 59c8f9b2d2293a96ac27db668af697862e08b7d9 Mon Sep 17 00:00:00 2001 From: Thibault Meunier Date: Tue, 24 Sep 2024 12:04:22 +0200 Subject: [PATCH 25/27] [Key Transparency auditor] Fix grammatical nits --- src/content/docs/key-transparency/api/namespaces.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/key-transparency/api/namespaces.mdx b/src/content/docs/key-transparency/api/namespaces.mdx index 79a8dfbf378dfe2..183d0130c7f9c89 100644 --- a/src/content/docs/key-transparency/api/namespaces.mdx +++ b/src/content/docs/key-transparency/api/namespaces.mdx @@ -5,7 +5,7 @@ sidebar: order: 2 --- -The Cloudflare Key Transparency API is organized in namespaces, representing a log Cloudflare Auditor monitors. If you want to register a namespace, contact us. +The Cloudflare Key Transparency API is organized in namespaces, each one representing a Log Cloudflare Auditor monitors. If you want to register a namespace, contact us. ## Create a namespace @@ -15,8 +15,8 @@ The following fields are required when making a `POST` request: - `public` - `root` - `signature_version`: - - 0x0001 is for [Protobuf serialisation](https://github.com/cloudflare/plexi/blob/main/plexi_core/src/proto/specs/types.proto) Ed25519 signature from the Auditor - - 0x0002 is for [bincode serialisation](https://github.com/bincode-org/bincode/blob/trunk/docs/spec.md) E25519 serialisation by the Auditor + - 0x0001 for [Protobuf serialisation](https://github.com/cloudflare/plexi/blob/main/plexi_core/src/proto/specs/types.proto) Ed25519 signature from the Auditor + - 0x0002 for [bincode serialisation](https://github.com/bincode-org/bincode/blob/trunk/docs/spec.md) E25519 serialisation by the Auditor The `log_directory` field is optional. If set, Cloudflare will use it to fetch audit proofs and validate them. From 714c570ee02b31037d2469c42ad57e94d86daa05 Mon Sep 17 00:00:00 2001 From: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> Date: Tue, 24 Sep 2024 11:41:03 +0100 Subject: [PATCH 26/27] Small fix --- src/content/docs/key-transparency/api/namespaces.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/key-transparency/api/namespaces.mdx b/src/content/docs/key-transparency/api/namespaces.mdx index 183d0130c7f9c89..713d55186f52f3a 100644 --- a/src/content/docs/key-transparency/api/namespaces.mdx +++ b/src/content/docs/key-transparency/api/namespaces.mdx @@ -5,7 +5,7 @@ sidebar: order: 2 --- -The Cloudflare Key Transparency API is organized in namespaces, each one representing a Log Cloudflare Auditor monitors. If you want to register a namespace, contact us. +The Cloudflare Key Transparency API is organized in namespaces, each one representing a Log monitored by Cloudflare Auditor. If you want to register a namespace, contact us. ## Create a namespace From 7b2d78b4f6ca94351bb79fbbd88f26a70a97aec1 Mon Sep 17 00:00:00 2001 From: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> Date: Tue, 24 Sep 2024 11:57:44 +0100 Subject: [PATCH 27/27] Replace relative links --- .../api/auditor-information.mdx | 4 ++-- .../monitor-the-auditor/index.mdx | 17 +++++++++-------- 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/src/content/docs/key-transparency/api/auditor-information.mdx b/src/content/docs/key-transparency/api/auditor-information.mdx index 44c01086e2da504..7f75d18dd5499fe 100644 --- a/src/content/docs/key-transparency/api/auditor-information.mdx +++ b/src/content/docs/key-transparency/api/auditor-information.mdx @@ -1,11 +1,11 @@ --- pcx_content_type: overview title: Auditor -sidebar: +sidebar: order: 1 --- -The Auditor is designed to sign epoch information, which includes the time at which the request is received by the Auditor, the epoch number, and the epoch digest. The Auditor serialises this information in binary using protobuf or bincode and checks whether the requested inclusion is valid, as in not satisfies [publication constraints](./epochs/#constraints). +The Auditor is designed to sign epoch information, which includes the time at which the request is received by the Auditor, the epoch number, and the epoch digest. The Auditor serializes this information in binary using protobuf or bincode and checks whether the requested inclusion is valid, as in not satisfies [publication constraints](/key-transparency/api/epochs/#constraints). If the Log is setup to provide [AKD](https://github.com/facebook/akd) audit proof, the Auditor verifies them asynchronously. diff --git a/src/content/docs/key-transparency/monitor-the-auditor/index.mdx b/src/content/docs/key-transparency/monitor-the-auditor/index.mdx index b2a885f8978b787..6ccfdf1ce5d5abf 100644 --- a/src/content/docs/key-transparency/monitor-the-auditor/index.mdx +++ b/src/content/docs/key-transparency/monitor-the-auditor/index.mdx @@ -7,18 +7,18 @@ sidebar: Cloudflare's Key Transparency Auditor validates Log audit proofs and provides a signature for them. The Log can then distribute these signatures to its end-users, and provides users with confidence that keys have not been tampered with. -In order to verify our work, you can use [Plexi](https://github.com/cloudflare/plexi), a CLI tool that allows anyone to perform proof verification locally via a public [API](./api/index.mdx). +In order to verify our work, you can use [Plexi](https://github.com/cloudflare/plexi), a CLI tool that allows anyone to perform proof verification locally via a public [API](/key-transparency/api/). ## Features -* Verify authenticity of a signature, to confirm it has been signed by a given public key -* Verify the validity of [facebook/akd](https://github.com/facebook/akd) proofs -* List Logs an Auditor monitors +- Verify authenticity of a signature, to confirm it has been signed by a given public key +- Verify the validity of [facebook/akd](https://github.com/facebook/akd) proofs +- List Logs an Auditor monitors ## Installation | Environment | CLI Command | -|:--------------------------------------------------------------|:----------------------| +| :------------------------------------------------------------ | :-------------------- | | [Cargo](https://www.rust-lang.org/tools/install) (Rust 1.76+) | `cargo install plexi` | ## Usage @@ -31,14 +31,14 @@ plexi [OPTIONS] ### Configure your auditor remote -`plexi` does not come with a default remote auditor, and you will need to choose your own. +`plexi` does not come with a default remote auditor, and you will need to choose your own. You can do so either by passing `--remote-url=` or setting the `PLEXI_REMOTE_URL` environment variable. -A common remote is provided below: +A common remote is provided below: | Name | Remote | -|:-----------|:------------------------------------------------| +| :--------- | :---------------------------------------------- | | Cloudflare | `https://plexi.key-transparency.cloudflare.com` | If you have deployed your own auditor, you can add a remote by filing a [GitHub issue](https://github.com/cloudflare/plexi/issues). @@ -59,6 +59,7 @@ The Key Transparency Auditor vouches for Log validity by ensuring epoch uniquene `plexi audit` provides information about a given epoch and its validity. It can perform a local audit to confirm the auditor behaviour. For instance, to verify WhatsApp Log auditted by Cloudflare Auditor, run the following: + ```shell > plexi audit --remote-url 'https://plexi.key-transparency.cloudflare.com' --namespace 'whatsapp.key-transparency.v1' --long Namespace: whatsapp.key-transparency.v1