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 00000000000000..7f75d18dd5499f --- /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 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. + +## Get Auditor information + +`keys` contain Auditor public keys which allow for key rotation later. + +```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 00000000000000..aede0f399528ae --- /dev/null +++ b/src/content/docs/key-transparency/api/epochs.mdx @@ -0,0 +1,54 @@ +--- +pcx_content_type: overview +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. + +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' \ + --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. +``` 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 00000000000000..e2f4ef456c940b --- /dev/null +++ b/src/content/docs/key-transparency/api/index.mdx @@ -0,0 +1,12 @@ +--- +title: API +pcx_content_type: navigation +sidebar: + order: 1 + 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 00000000000000..713d55186f52f3 --- /dev/null +++ b/src/content/docs/key-transparency/api/namespaces.mdx @@ -0,0 +1,86 @@ +--- +pcx_content_type: overview +title: Namespaces +sidebar: + order: 2 +--- + +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 + +The following fields are required when making a `POST` request: + +- `name` +- `public` +- `root` +- `signature_version`: + - 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. + +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' \ + --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 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 +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 new file mode 100644 index 00000000000000..c60e75a28e0772 --- /dev/null +++ b/src/content/docs/key-transparency/index.mdx @@ -0,0 +1,36 @@ +--- +title: Overview +pcx_content_type: overview +sidebar: + order: 1 +head: + - tag: title + content: Key Transparency Auditor + +--- + +import { CardGrid, Description, Feature, LinkTitleCard, RelatedProduct } from "~/components" + + + +Secure the distribution of public keys in your end-to-end encrypted (E2EE) messaging systems + + + +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. + +## Related products + + + +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. + + + + + +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. + + diff --git a/src/content/docs/key-transparency/monitor-the-auditor/index.mdx b/src/content/docs/key-transparency/monitor-the-auditor/index.mdx new file mode 100644 index 00000000000000..6ccfdf1ce5d5ab --- /dev/null +++ b/src/content/docs/key-transparency/monitor-the-auditor/index.mdx @@ -0,0 +1,72 @@ +--- +pcx_content_type: overview +title: Monitor the Auditor +sidebar: + order: 2 +--- + +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](/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 + +## Installation + +| Environment | CLI Command | +| :------------------------------------------------------------ | :-------------------- | +| [Cargo](https://www.rust-lang.org/tools/install) (Rust 1.76+) | `cargo install plexi` | + +## Usage + +Use the `--help` option for more details about the commands and their options. + +```bash +plexi [OPTIONS] +``` + +### Configure your auditor remote + +`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: + +| 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). + +### List monitored Logs + +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 +``` + +### Audit a signature + +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. + +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 +Ciphersuite: ed25519(protobuf) +Timestamp: 2024-09-19T09:59:44Z +Epoch height: 476847 +Epoch digest: 9d217c91dc629d16a3b1379e8fd7c949c27b1b6038259e3918bd0da3cd6c34d1 +Signature: e4c83e3091ba8764752120bd7a726a28759d25a01f39d07131d6ba66a913d58d8f0f48f63bc7e037cc5ddd81dc76acc847dbf8d02b2f55251e6f2b1f00191902 +Verification: success +``` diff --git a/src/content/products/key-transparency.yaml b/src/content/products/key-transparency.yaml new file mode 100644 index 00000000000000..4bd1a6ad33b55b --- /dev/null +++ b/src/content/products/key-transparency.yaml @@ -0,0 +1,21 @@ +name: Key Transparency Auditor + +product: + title: Key Transparency Auditor + url: /key-transparency/ + group: Application security + +meta: + title: Key Transparency Auditor + description: + Key Transparency Auditor 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 00000000000000..63dfbeec970f30 --- /dev/null +++ b/src/icons/key-transparency.svg @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file