Skip to content

Commit 404d396

Browse files
pedrosousadcpenathibmeumgalicerOxyjun
authored
[Key Transparency] Add tile (#17048)
--------- Co-authored-by: Denise Pena <[email protected]> Co-authored-by: Thibault Meunier <[email protected]> Co-authored-by: Mari <[email protected]> Co-authored-by: Denise Peña <[email protected]> Co-authored-by: Jun Lee <[email protected]>
1 parent 2705bca commit 404d396

File tree

8 files changed

+318
-0
lines changed

8 files changed

+318
-0
lines changed

‎src/content/docs/key-transparency/api/auditor-information.mdx‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
pcx_content_type: overview
3+
title: Auditor
4+
sidebar:
5+
order: 1
6+
---
7+
8+
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).
9+
10+
If the Log is setup to provide [AKD](https://github.com/facebook/akd) audit proof, the Auditor verifies them asynchronously.
11+
12+
## Get Auditor information
13+
14+
`keys` contain Auditor public keys which allow for key rotation later.
15+
16+
```sh
17+
curl 'https://plexi.key-transparency.cloudflare.com/info'
18+
{
19+
"keys": [
20+
{
21+
"public_key": "d1036a33a8731e82a29dc68210988b32b60b7c1bd22d2341f2e339f4db3a2f4a",
22+
"not_before": 1712311441501
23+
}
24+
],
25+
"logs": [
26+
"508607faff7cb16be841e901eca41a6239461f239e7e610c9ea2576f334bc144"
27+
]
28+
}
29+
```

‎src/content/docs/key-transparency/api/epochs.mdx‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
pcx_content_type: overview
3+
title: Epochs
4+
sidebar:
5+
order: 3
6+
---
7+
8+
## Get an epoch
9+
10+
```sh
11+
curl 'https://plexi.key-transparency.cloudflare.com/namespaces/{namespace}/audits/1'
12+
{
13+
"namespace": "your.new.log.com",
14+
"timestamp": 1717084639921,
15+
"epoch": 1,
16+
"digest": "1111111111111111111111111111111111111111111111111111111111111111",
17+
"signature": "f6a51443bb6703813b330959d9d97471bc06464142165e59733fa102a18b052782a5307d59c31b8b13c1af7dfff6f6e7bf44e880d44e26e96c50a72f72a30c07"
18+
}
19+
```
20+
21+
## Publish a new epoch
22+
23+
Refer to the example below to publish a new epoch by requesting its signature.
24+
25+
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.
26+
27+
```sh
28+
curl 'https://plexi.key-transparency.cloudflare.com/namespaces/{namespace}/audits' \
29+
--header 'Content-Type: application/json' \
30+
--data '{"epoch": 1, "digest": "1111111111111111111111111111111111111111111111111111111111111111"}'
31+
{
32+
"namespace": "your.new.log.com",
33+
"timestamp": 1717084639921,
34+
"epoch": 1,
35+
"digest": "1111111111111111111111111111111111111111111111111111111111111111",
36+
"signature": "f6a51443bb6703813b330959d9d97471bc06464142165e59733fa102a18b052782a5307d59c31b8b13c1af7dfff6f6e7bf44e880d44e26e96c50a72f72a30c07",
37+
"key_id": 74,
38+
}
39+
```
40+
41+
### Constraints
42+
43+
- If `root` is defined for the namespace, the first epoch must match it (number and digest).
44+
- Epochs must be increasing. Second epoch is 2, third is 3, etc.
45+
- Epochs must have a unique digest or it will be rejected.
46+
- Epochs cannot be republished.
47+
- Digest must be a 32 byte string hex encoded (length 64).
48+
49+
If a namespace is disabled, you receive the following error:
50+
51+
```txt
52+
HTTP 400 Bad Request
53+
Namespace is disabled and read-only.
54+
```

‎src/content/docs/key-transparency/api/index.mdx‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
title: API
3+
pcx_content_type: navigation
4+
sidebar:
5+
order: 1
6+
group:
7+
hideIndex: true
8+
---
9+
10+
import { DirectoryListing } from "~/components"
11+
12+
<DirectoryListing />

‎src/content/docs/key-transparency/api/namespaces.mdx‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
pcx_content_type: overview
3+
title: Namespaces
4+
sidebar:
5+
order: 2
6+
---
7+
8+
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.
9+
10+
## Create a namespace
11+
12+
The following fields are required when making a `POST` request:
13+
14+
- `name`
15+
- `public`
16+
- `root`
17+
- `signature_version`:
18+
- 0x0001 for [Protobuf serialisation](https://github.com/cloudflare/plexi/blob/main/plexi_core/src/proto/specs/types.proto) Ed25519 signature from the Auditor
19+
- 0x0002 for [bincode serialisation](https://github.com/bincode-org/bincode/blob/trunk/docs/spec.md) E25519 serialisation by the Auditor
20+
21+
The `log_directory` field is optional. If set, Cloudflare will use it to fetch audit proofs and validate them.
22+
23+
This API is authenticated via [mTLS](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/).
24+
25+
```sh
26+
curl 'https://plexi.key-transparency.cloudflare.com/namespaces' \
27+
--header 'Content-Type: application/json' \
28+
--data '{
29+
"name": "your.new.log.com",
30+
"root": "1/1111111111111111111111111111111111111111111111111111111111111111",
31+
"log_directory": "https://your.new.log.com/path/to/proofs",
32+
"signature_version": 1
33+
}'
34+
{
35+
"name": "your.new.log.com",
36+
"log_directory": "https://your.new.log.com/path/to/proofs",
37+
"root": "1/1111111111111111111111111111111111111111111111111111111111111111",
38+
"status": "Initialization",
39+
"reports_uri": "/namespaces/your.new.log.com/reports",
40+
"audits_uri": "/namespaces/your.new.log.com/audits",
41+
"signature_version": 1
42+
}
43+
```
44+
45+
After publishing the first epoch, `status` will show `Online`. Possible statuses include:
46+
- `Online`
47+
- `Initialization`
48+
- `Disabled`
49+
50+
## List all namespaces
51+
52+
Refer to the example below to get information about all public namespaces.
53+
54+
```sh
55+
curl 'https://plexi.key-transparency.cloudflare.com/namespaces'
56+
{
57+
"namespaces": [
58+
{ "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" },
59+
{ "name": "my.new.log.com", "reports_uri": "/namespaces/meta-bt-2024/reports", "audits_uri": "/namespaces/meta-bt-2024/audits", "status": "initialization" }
60+
]
61+
}
62+
```
63+
64+
## Disable a namespace
65+
66+
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`.
67+
68+
This API is authenticated via [mTLS](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/).
69+
70+
71+
```sh
72+
curl -X PATCH 'https://plexi.key-transparency.cloudflare.com/namespaces/{namespace}' \
73+
-H 'Content-Type: application/json' \
74+
-d '{
75+
"status": "Disabled"
76+
}'
77+
{
78+
"name": "your.new.log.com",
79+
"log_directory": "https://your.new.log.com/path/to/proofs",
80+
"root": "1/1111111111111111111111111111111111111111111111111111111111111111",
81+
"status": "Disabled",
82+
"reports_uri": "/namespaces/your.new.log.com/reports",
83+
"audits_uri": "/namespaces/your.new.log.com/audits",
84+
"signature_version": 1
85+
}
86+
```

‎src/content/docs/key-transparency/index.mdx‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: Overview
3+
pcx_content_type: overview
4+
sidebar:
5+
order: 1
6+
head:
7+
- tag: title
8+
content: Key Transparency Auditor
9+
10+
---
11+
12+
import { CardGrid, Description, Feature, LinkTitleCard, RelatedProduct } from "~/components"
13+
14+
<Description>
15+
16+
Secure the distribution of public keys in your end-to-end encrypted (E2EE) messaging systems
17+
18+
</Description>
19+
20+
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).
21+
22+
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.
23+
24+
## Related products
25+
26+
<RelatedProduct header="Certificate Transparency Monitoring" href="/ssl/edge-certificates/additional-options/certificate-transparency-monitoring/" product="ssl">
27+
28+
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.
29+
30+
</RelatedProduct>
31+
32+
<RelatedProduct header="Privacy Gateway" href="/privacy-gateway/" product="privacy-gateway">
33+
34+
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.
35+
36+
</RelatedProduct>

‎src/content/docs/key-transparency/monitor-the-auditor/index.mdx‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
pcx_content_type: overview
3+
title: Monitor the Auditor
4+
sidebar:
5+
order: 2
6+
---
7+
8+
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.
9+
10+
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/).
11+
12+
## Features
13+
14+
- Verify authenticity of a signature, to confirm it has been signed by a given public key
15+
- Verify the validity of [facebook/akd](https://github.com/facebook/akd) proofs
16+
- List Logs an Auditor monitors
17+
18+
## Installation
19+
20+
| Environment | CLI Command |
21+
| :------------------------------------------------------------ | :-------------------- |
22+
| [Cargo](https://www.rust-lang.org/tools/install) (Rust 1.76+) | `cargo install plexi` |
23+
24+
## Usage
25+
26+
Use the `--help` option for more details about the commands and their options.
27+
28+
```bash
29+
plexi [OPTIONS] <COMMAND>
30+
```
31+
32+
### Configure your auditor remote
33+
34+
`plexi` does not come with a default remote auditor, and you will need to choose your own.
35+
36+
You can do so either by passing `--remote-url=<REMOTE>` or setting the `PLEXI_REMOTE_URL` environment variable.
37+
38+
A common remote is provided below:
39+
40+
| Name | Remote |
41+
| :--------- | :---------------------------------------------- |
42+
| Cloudflare | `https://plexi.key-transparency.cloudflare.com` |
43+
44+
If you have deployed your own auditor, you can add a remote by filing a [GitHub issue](https://github.com/cloudflare/plexi/issues).
45+
46+
### List monitored Logs
47+
48+
An auditor monitors multiple Logs at once. To discover which Logs an auditor is monitoring, run the following:
49+
50+
```shell
51+
plexi ls --remote-url 'https://plexi.key-transparency.cloudflare.com'
52+
whatsapp.key-transparency.v1
53+
```
54+
55+
### Audit a signature
56+
57+
The Key Transparency Auditor vouches for Log validity by ensuring epoch uniqueness and verifying the associated proof.
58+
59+
`plexi audit` provides information about a given epoch and its validity. It can perform a local audit to confirm the auditor behaviour.
60+
61+
For instance, to verify WhatsApp Log auditted by Cloudflare Auditor, run the following:
62+
63+
```shell
64+
> plexi audit --remote-url 'https://plexi.key-transparency.cloudflare.com' --namespace 'whatsapp.key-transparency.v1' --long
65+
Namespace: whatsapp.key-transparency.v1
66+
Ciphersuite: ed25519(protobuf)
67+
Timestamp: 2024-09-19T09:59:44Z
68+
Epoch height: 476847
69+
Epoch digest: 9d217c91dc629d16a3b1379e8fd7c949c27b1b6038259e3918bd0da3cd6c34d1
70+
Signature: e4c83e3091ba8764752120bd7a726a28759d25a01f39d07131d6ba66a913d58d8f0f48f63bc7e037cc5ddd81dc76acc847dbf8d02b2f55251e6f2b1f00191902
71+
Verification: success
72+
```

‎src/content/products/key-transparency.yaml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
name: Key Transparency Auditor
2+
3+
product:
4+
title: Key Transparency Auditor
5+
url: /key-transparency/
6+
group: Application security
7+
8+
meta:
9+
title: Key Transparency Auditor
10+
description:
11+
Key Transparency Auditor docs
12+
author: "@cloudflare"
13+
14+
externals:
15+
- title: Cloudflare homepage
16+
url: https://cloudflare.com
17+
18+
algolia:
19+
index: TEST - Re-dev docs
20+
apikey: 4edb0a6cef3338ff4bcfbc6b3d2db56b
21+
product: security-center

‎src/icons/key-transparency.svg‎

Lines changed: 8 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)